0
# Python Loading
1

2
Python source code loading capabilities that parse Python modules and packages into docspec objects for documentation generation.
3

4
## Capabilities
5

6
### PythonLoader
7

8
Loads Python source code using docspec_python, providing comprehensive module discovery, package analysis, and configurable parsing options.
9

10
```python { .api }
11
class PythonLoader(Loader):
12
    """
13
    Loader implementation that parses Python modules and packages using docspec_python.
14
    
15
    With no modules or packages set, discovers available modules in current and src/ directories.
16
    
17
    Attributes:
18
        modules: List of module names to load (e.g., ["mypackage.module1"])
19
        packages: List of package names to load recursively (e.g., ["mypackage"])
20
        search_path: List of directories to search for modules (defaults to current and src/)
21
        ignore_when_discovered: List of module/package names to ignore during discovery
22
        parser: docspec_python.Parser instance with parsing configuration
23
    """
24
    modules: List[str]
25
    packages: List[str] 
26
    search_path: List[str]
27
    ignore_when_discovered: List[str]
28
    parser: docspec_python.Parser
29
    
30
    def load(self) -> Iterable[docspec.Module]:
31
        """
32
        Load and parse Python modules into docspec objects.
33
        
34
        Returns:
35
            Iterable of docspec.Module objects containing parsed API information
36
            
37
        Raises:
38
            LoaderError: If module loading or parsing fails
39
        """
40
```
41

42
### Parser Configuration
43

44
The parser field provides access to docspec_python.Parser configuration options for controlling how Python code is parsed.
45

46
```python { .api }
47
# Common parser configuration options accessed via loader.parser:
48
# parser.print_function: bool - Enable Python 3 print function syntax (default: True)
49
# parser.encoding: str - Source file encoding (default: "utf-8")
50
# parser.treat_singleline_comment_blocks_as_docstrings: bool - Treat comment blocks as docstrings
51
```
52

53
## Usage Examples
54

55
### Basic Module Loading
56

57
```python
58
from pydoc_markdown import PydocMarkdown
59
from pydoc_markdown.contrib.loaders.python import PythonLoader
60

61
# Load specific modules
62
loader = PythonLoader(
63
    modules=['mypackage.core', 'mypackage.utils']
64
)
65

66
config = PydocMarkdown(loaders=[loader])
67
modules = config.load_modules()
68
```
69

70
### Package Loading
71

72
```python
73
from pydoc_markdown.contrib.loaders.python import PythonLoader
74

75
# Load entire packages recursively
76
loader = PythonLoader(
77
    packages=['mypackage', 'mypackage.subpackage']
78
)
79

80
config = PydocMarkdown(loaders=[loader])
81
modules = config.load_modules()
82
```
83

84
### Custom Search Path
85

86
```python
87
from pydoc_markdown.contrib.loaders.python import PythonLoader
88

89
# Load with custom search paths
90
loader = PythonLoader(
91
    modules=['mypackage'],
92
    search_path=['src/', 'lib/', '/opt/custom/python/']
93
)
94

95
config = PydocMarkdown(loaders=[loader])
96
modules = config.load_modules()
97
```
98

99
### Module Discovery with Filtering
100

101
```python
102
from pydoc_markdown.contrib.loaders.python import PythonLoader
103

104
# Auto-discover modules but ignore specific ones
105
loader = PythonLoader(
106
    # Leave modules and packages empty for auto-discovery
107
    ignore_when_discovered=['test_*', 'internal', 'deprecated_module']
108
)
109

110
config = PydocMarkdown(loaders=[loader])
111
modules = config.load_modules()
112
```
113

114
### Parser Configuration
115

116
```python
117
from pydoc_markdown.contrib.loaders.python import PythonLoader
118
import docspec_python
119

120
# Configure parser for Python 2 compatibility
121
loader = PythonLoader(
122
    modules=['legacy_package'],
123
    parser=docspec_python.Parser(print_function=False)  # Python 2 print statement
124
)
125

126
# Or modify existing parser
127
loader = PythonLoader(modules=['mypackage'])
128
loader.parser.treat_singleline_comment_blocks_as_docstrings = True
129
loader.parser.encoding = 'latin-1'
130
```
131

132
## Configuration Examples
133

134
### YAML Configuration
135

136
```yaml
137
loaders:
138
  - type: python
139
    modules:
140
      - mypackage.core
141
      - mypackage.utils
142
    packages:
143
      - mypackage.subpackage
144
    search_path:
145
      - src/
146
      - lib/
147
    ignore_when_discovered:
148
      - test_*
149
      - internal.*
150
```
151

152
### Comprehensive Configuration
153

154
```yaml
155
loaders:
156
  - type: python
157
    # Specific modules to document
158
    modules:
159
      - mypackage.api
160
      - mypackage.client
161
    
162
    # Packages to document recursively  
163
    packages:
164
      - mypackage.core
165
      - mypackage.plugins
166
    
167
    # Custom search directories
168
    search_path:
169
      - src/
170
      - vendor/
171
      - /opt/myproject/
172
    
173
    # Modules to ignore during auto-discovery
174
    ignore_when_discovered:
175
      - test_*
176
      - *_test
177
      - internal
178
      - deprecated.*
179
      - experimental.*
180
```
181

182
### Multiple Loaders
183

184
```yaml
185
loaders:
186
  # Main package loader
187
  - type: python
188
    packages: [mypackage]
189
    search_path: [src/]
190
    
191
  # Separate loader for plugin system
192
  - type: python  
193
    modules: [myplugins.core]
194
    search_path: [plugins/]
195
    
196
  # Legacy code with Python 2 syntax
197
  - type: python
198
    modules: [legacy]
199
    search_path: [legacy/]
200
```
201

202
## Module Discovery Behavior
203

204
When neither `modules` nor `packages` are specified, PythonLoader automatically discovers available modules:
205

206
1. **Current Directory**: Searches for Python files and packages in the current working directory
207
2. **src/ Directory**: If present, searches the src/ directory for Python packages  
208
3. **Filtering**: Applies `ignore_when_discovered` patterns to exclude unwanted modules
209
4. **Recursive**: Discovers packages recursively, including all submodules and subpackages
210

211
### Discovery Examples
212

213
```python
214
# Project structure:
215
# myproject/
216
#   ├── src/
217
#   │   └── mypackage/
218
#   │       ├── __init__.py
219
#   │       ├── core.py
220
#   │       └── utils.py
221
#   ├── tests/
222
#   └── setup.py
223

224
# Auto-discovery will find:
225
# - mypackage (from src/)
226
# - mypackage.core
227
# - mypackage.utils
228

229
loader = PythonLoader()  # No modules/packages specified
230
modules = loader.load()  # Discovers src/mypackage/ automatically
231
```