0
# Handler and Core Functionality
1

2
Core components for creating and using the mkdocstrings-python handler to collect and render Python API documentation.
3

4
## Capabilities
5

6
### Handler Creation
7

8
Factory function to create a configured PythonHandler instance with specified options and base directory.
9

10
```python { .api }
11
def get_handler(
12
    handler_config: dict[str, Any],
13
    tool_config: object,
14
    **kwargs
15
) -> PythonHandler:
16
    """
17
    Return an instance of PythonHandler.
18
    
19
    Parameters:
20
    - handler_config: dict[str, Any] - The handler configuration dictionary
21
    - tool_config: object - The tool (SSG) configuration
22
    - **kwargs: Additional arguments to pass to the handler
23
    
24
    Returns:
25
    PythonHandler - An instance of PythonHandler
26
    """
27
```
28

29
**Usage Example:**
30

31
```python
32
from mkdocstrings_handlers.python import get_handler
33
from pathlib import Path
34

35
# Create handler configuration dictionary
36
handler_config = {
37
    "docstring_style": "google",
38
    "show_source": True,
39
    "show_root_heading": True,
40
    "members_order": "alphabetical"
41
}
42

43
# Mock tool config (normally provided by mkdocstrings)
44
tool_config = type('Config', (), {'config_file_path': 'mkdocs.yml'})()
45

46
# Get handler instance
47
handler = get_handler(handler_config=handler_config, tool_config=tool_config)
48
```
49

50
### Handler Class
51

52
Main handler class that extends BaseHandler and provides Python-specific documentation collection and rendering functionality.
53

54
```python { .api }
55
class PythonHandler(BaseHandler):
56
    """The Python handler class for mkdocstrings."""
57
    
58
    name: str = "python"
59
    domain: str = "py" 
60
    enable_inventory: bool = True
61
    fallback_theme: str = "material"
62
    
63
    def __init__(
64
        self,
65
        config: PythonConfig,
66
        base_dir: Path,
67
        **kwargs
68
    ) -> None:
69
        """
70
        Initialize the handler.
71
        
72
        Parameters:
73
        - config: PythonConfig - Handler configuration
74
        - base_dir: Path - Base directory of the project
75
        - **kwargs: Arguments passed to parent constructor
76
        """
77
        
78
    def collect(
79
        self,
80
        identifier: str,
81
        options: PythonOptions
82
    ) -> CollectorItem:
83
        """
84
        Collect the documentation for the given identifier.
85
        
86
        Parameters:
87
        - identifier: str - The identifier of the object to collect
88
        - options: PythonOptions - The options to use for the collection
89
        
90
        Returns:
91
        CollectorItem - The collected item
92
        
93
        Raises:
94
        CollectionError - If the object cannot be found or collected
95
        """
96
        
97
    def get_options(
98
        self,
99
        local_options: dict[str, Any]
100
    ) -> HandlerOptions:
101
        """
102
        Get handler options by merging local and global configurations.
103
        
104
        Parameters:
105
        - local_options: dict[str, Any] - Local configuration options
106
        
107
        Returns:
108
        HandlerOptions - Merged handler options
109
        """
110
        
111
    def get_inventory_urls(self) -> list[tuple[str, dict[str, Any]]]:
112
        """
113
        Get inventory URLs for cross-reference resolution.
114
        
115
        Returns:
116
        list[tuple[str, dict[str, Any]]] - List of inventory URLs and their metadata
117
        """
118
        
119
    def render(
120
        self,
121
        data: CollectorItem,
122
        options: PythonOptions,
123
        locale: str | None = None
124
    ) -> str:
125
        """
126
        Render the collected data.
127
        
128
        Parameters:
129
        - data: CollectorItem - The collected data
130
        - options: PythonOptions - The options to use for rendering
131
        - locale: str | None - The locale to use for rendering (default is "en")
132
        
133
        Returns:
134
        str - The rendered data (HTML)
135
        """
136
        
137
    def teardown(self) -> None:
138
        """Clean up handler resources."""
139
        
140
    def update_env(
141
        self,
142
        md: object,
143
        config: dict
144
    ) -> None:
145
        """Update the Jinja2 environment with handler-specific functions."""
146
```
147

148
**Usage Example:**
149

150
```python
151
from mkdocstrings_handlers.python import PythonHandler, PythonConfig
152
from pathlib import Path
153

154
# Create handler directly
155
handler = PythonHandler(
156
    config=PythonConfig(),
157
    base_dir=Path.cwd()
158
)
159

160
# Collect documentation for a module
161
from mkdocstrings_handlers.python import PythonOptions
162
options = PythonOptions(docstring_style="google")
163
data = handler.collect("numpy.array", options)
164

165
# Render the documentation
166
html = handler.render(data, options, locale="en")
167
```
168

169
### Error Handling
170

171
The handler raises specific exceptions for different error conditions:
172

173
- `CollectionError`: When a Python object cannot be found or analyzed
174
- `PluginError`: For configuration or setup issues
175
- `AliasResolutionError`: When cross-references cannot be resolved
176
- `TemplateNotFound`: When required Jinja2 templates are missing
177

178
**Example Error Handling:**
179

180
```python
181
from mkdocstrings import CollectionError
182
from mkdocs.exceptions import PluginError
183

184
try:
185
    data = handler.collect("nonexistent.module", {})
186
except CollectionError as e:
187
    print(f"Failed to collect documentation: {e}")
188
except PluginError as e:
189
    print(f"Configuration error: {e}")
190
```