0
# Module Extraction and Loading
1

2
Utilities for discovering, loading, and walking Python modules with error handling and import safety. These functions handle the complex process of safely importing Python modules for documentation generation.
3

4
## Capabilities
5

6
### Module Specification Processing
7

8
Parse and process module specifications from command line arguments or API calls.
9

10
```python { .api }
11
def walk_specs(specs: Sequence[Path | str]) -> list[str]:
12
    """
13
    Process module specifications and return module names.
14
    
15
    Parameters:
16
    - specs: Sequence of module names (str) or file paths (Path)
17
    
18
    Returns:
19
    - list[str]: Module names ready for import
20
    
21
    Handles:
22
    - File path to module name conversion
23
    - Negative patterns for exclusion (!pattern)
24
    - Package discovery and filtering
25
    - Submodule collection
26
    """
27

28
def parse_spec(spec: Path | str) -> str:
29
    """
30
    Parse individual module specification.
31
    
32
    Parameters:
33
    - spec: Path | str - Module specification (name or file path)
34
    
35
    Returns:
36
    - str: Resolved module name
37
    
38
    Side Effects:
39
    - May modify sys.path for file-based modules
40
    - Sets up module search paths
41
    """
42
```
43

44
### Safe Module Loading
45

46
Load Python modules with error handling and side effect management.
47

48
```python { .api }
49
def load_module(module: str) -> types.ModuleType:
50
    """
51
    Safely load a Python module for documentation.
52
    
53
    Parameters:
54
    - module: str - Dotted module name to load
55
    
56
    Returns:
57
    - ModuleType: The loaded Python module object
58
    
59
    Raises:
60
    - ImportError: If module cannot be imported
61
    - RuntimeError: If module has import-time side effects
62
    """
63

64
@contextmanager
65
def mock_some_common_side_effects():
66
    """
67
    Mock common side effects that may occur during module import.
68
    
69
    Prevents modules from performing unwanted actions during documentation generation.
70
    
71
    Effects:
72
    - Patches common side-effect functions
73
    - Prevents GUI dialogs and interactive prompts
74
    - Disables network connections where possible
75
    """
76
```
77

78
### Module Discovery
79

80
Advanced module and package discovery utilities.
81

82
```python { .api }
83
def iter_modules2(module: types.ModuleType) -> dict[str, pkgutil.ModuleInfo]:
84
    """
85
    Iterate over all modules in a package.
86
    
87
    Parameters:
88
    - module: types.ModuleType - Package module to iterate
89
    
90
    Returns:
91
    - dict[str, pkgutil.ModuleInfo]: Module info by name
92
    """
93

94
def walk_packages2(modules: Iterable[pkgutil.ModuleInfo]) -> Iterator[pkgutil.ModuleInfo]:
95
    """
96
    Walk all packages and subpackages from given module info.
97
    
98
    Parameters:
99
    - modules: Iterable[pkgutil.ModuleInfo] - Module info objects to traverse
100
    
101
    Yields:
102
    - pkgutil.ModuleInfo: Information about each discovered module
103
    """
104
```
105

106
### Module Metadata
107

108
Utilities for extracting module metadata and managing import caches.
109

110
```python { .api }
111
def module_mtime(modulename: str) -> float | None:
112
    """
113
    Get modification time of module source file.
114
    
115
    Parameters:
116
    - modulename: str - Dotted module name
117
    
118
    Returns:
119
    - float | None: Modification timestamp or None if not available
120
    """
121

122
def invalidate_caches(module_name: str) -> None:
123
    """
124
    Clear import caches for a module.
125
    
126
    Parameters:
127
    - module_name: str - Module name to invalidate
128
    
129
    Effects:
130
    - Clears importlib caches
131
    - Removes module from sys.modules if present
132
    - Forces fresh import on next load
133
    """
134
```