0
# Documentation Object Model
1

2
Object hierarchy representing parsed Python code entities. The object model provides structured representation of modules, classes, functions, and other code constructs with comprehensive rendering capabilities for documentation generation.
3

4
## Base Object Class
5

6
### PythonObject
7

8
```python { .api }
9
class PythonObject:
10
    """
11
    Base class for representing parsed source code entities.
12
    
13
    All AutoAPI objects inherit from this base class, providing common
14
    properties and methods for documentation rendering.
15
    
16
    Attributes:
17
        name (str): Object name (e.g., 'MyClass', 'my_function')
18
        qual_name (str): Fully qualified name including module path
19
        id (str): Unique identifier for cross-referencing
20
        children (list[PythonObject]): Child objects (methods, attributes, etc.)
21
        docstring (str): Parsed docstring content
22
        imported (bool): Whether object was imported from another module
23
        inherited (bool): Whether object was inherited from parent class
24
    """
25
    
26
    def render(self, **kwargs):
27
        """
28
        Render object to reStructuredText using Jinja2 templates.
29
        
30
        Args:
31
            **kwargs: Additional context variables for template rendering
32
            
33
        Returns:
34
            str: Rendered reStructuredText content
35
            
36
        Uses appropriate template based on object type (module.rst, 
37
        class.rst, function.rst, etc.).
38
        """
39
    
40
    def get_context_data(self):
41
        """
42
        Get template context data for rendering.
43
        
44
        Returns:
45
            dict: Context data including object properties and metadata
46
            
47
        Provides all necessary data for template rendering including
48
        signatures, parameters, return types, and cross-references.
49
        """
50
```
51

52
From `autoapi._objects`:
53
```python
54
from autoapi._objects import PythonObject
55
```
56

57
## Container Objects
58

59
### PythonPackage
60

61
```python { .api }
62
class PythonPackage(PythonObject):
63
    """
64
    Represents a Python package containing modules and subpackages.
65
    
66
    Packages are directories with __init__.py files that group related
67
    modules together. AutoAPI generates package-level documentation
68
    including submodule listings and package docstrings.
69
    
70
    Attributes:
71
        children (list[PythonModule | PythonPackage]): Contained modules/packages
72
    """
73
```
74

75
### PythonModule
76

77
```python { .api }
78
class PythonModule(PythonObject):
79
    """
80
    Represents a Python module (.py file) containing classes, functions, and data.
81
    
82
    Modules are the primary organizational unit for Python code. AutoAPI
83
    extracts all module-level definitions and creates comprehensive
84
    documentation with proper cross-references.
85
    
86
    Attributes:
87
        children (list[PythonObject]): All module-level objects
88
        all (list[str]): Contents of __all__ if defined
89
        imports (list[dict]): Import statements in the module
90
    """
91
```
92

93
## Class Objects
94

95
### PythonClass
96

97
```python { .api }
98
class PythonClass(PythonObject):
99
    """
100
    Represents a Python class definition with methods, properties, and attributes.
101
    
102
    Classes are parsed with full inheritance information, including
103
    method resolution order, inherited members, and class hierarchies.
104
    
105
    Attributes:
106
        bases (list[str]): Base classes this class inherits from
107
        children (list[PythonMethod | PythonProperty | PythonAttribute]): Class members
108
        constructor (PythonMethod): __init__ method if present
109
    """
110
```
111

112
### PythonException
113

114
```python { .api }
115
class PythonException(PythonClass):
116
    """
117
    Represents a Python exception class.
118
    
119
    Exception classes are treated as specialized classes with additional
120
    documentation context for error handling scenarios.
121
    
122
    Inherits all PythonClass functionality with exception-specific templates.
123
    """
124
```
125

126
## Function Objects
127

128
### PythonFunction
129

130
```python { .api }
131
class PythonFunction(PythonObject):
132
    """
133
    Represents a Python function with complete signature information.
134
    
135
    Functions are parsed with full type annotation support, parameter
136
    documentation, and return type information.
137
    
138
    Attributes:
139
        args (list[ArgInfo]): Function parameters with types and defaults
140
        return_annotation (str): Return type annotation if present
141
        overloads (list[dict]): Function overloads from @overload decorator
142
        decorators (list[str]): Applied decorators
143
    """
144
```
145

146
### PythonMethod
147

148
```python { .api }
149
class PythonMethod(PythonFunction):
150
    """
151
    Represents a Python method (function defined within a class).
152
    
153
    Methods inherit all function capabilities with additional context
154
    for class membership, method types (static, class, instance), and
155
    inheritance relationships.
156
    
157
    Attributes:
158
        method_type (str): 'method', 'staticmethod', 'classmethod', or 'property'
159
        properties (list[str]): Method characteristics
160
    """
161
```
162

163
## Property and Data Objects
164

165
### PythonProperty
166

167
```python { .api }
168
class PythonProperty(PythonObject):
169
    """
170
    Represents a Python property created with @property decorator.
171
    
172
    Properties are parsed with getter, setter, and deleter methods,
173
    including proper documentation inheritance and type information.
174
    
175
    Attributes:
176
        getter (PythonMethod): Property getter method
177
        setter (PythonMethod): Property setter method if defined
178
        deleter (PythonMethod): Property deleter method if defined
179
    """
180
```
181

182
### PythonAttribute
183

184
```python { .api }
185
class PythonAttribute(PythonObject):
186
    """
187
    Represents a class or instance attribute.
188
    
189
    Attributes include both explicitly defined class variables and
190
    attributes assigned in __init__ methods, with type annotation support.
191
    
192
    Attributes:
193
        annotation (str): Type annotation if present
194
        value (str): Assigned value if determinable
195
    """
196
```
197

198
### PythonData
199

200
```python { .api }
201
class PythonData(PythonObject):
202
    """
203
    Represents module-level data, constants, and variables.
204
    
205
    Data objects capture module-level assignments, constants, and
206
    configuration variables with type annotations and values.
207
    
208
    Attributes:
209
        annotation (str): Type annotation if present
210
        value (str): Assigned value representation
211
    """
212
```
213

214
## Object Relationships
215

216
### Inheritance Handling
217

218
```python { .api }
219
# Inheritance resolution
220
"""AutoAPI resolves inheritance relationships including:
221
- Method Resolution Order (MRO) for complex hierarchies
222
- Inherited method and attribute documentation
223
- Base class cross-references
224
- Abstract method identification
225
"""
226

227
# Cross-references
228
"""Objects maintain relationships through:
229
- Parent-child relationships in object tree
230
- Import tracking for external references  
231
- Type annotation resolution for parameters/returns
232
- Decorator application tracking
233
"""
234
```
235

236
### Object Tree Structure
237

238
```python { .api }
239
# Typical object hierarchy:
240
"""
241
PythonPackage
242
├── PythonModule
243
│   ├── PythonClass
244
│   │   ├── PythonMethod
245
│   │   ├── PythonProperty
246
│   │   └── PythonAttribute
247
│   ├── PythonFunction
248
│   └── PythonData
249
└── PythonModule (submodule)
250
    └── ...
251
"""
252
```
253

254
## Rendering and Templates
255

256
### Template Context
257

258
```python { .api }
259
def get_context_data(self):
260
    """
261
    Common context data provided to all templates:
262
    
263
    Returns:
264
        dict: Template context including:
265
            - obj: The object being rendered
266
            - name: Object name
267
            - qual_name: Fully qualified name
268
            - id: Unique identifier
269
            - docstring: Parsed docstring
270
            - children: Child objects
271
            - imported: Import status
272
            - inherited: Inheritance status
273
            - signature: Function/method signature
274
            - parameters: Parameter documentation
275
            - returns: Return type information
276
    """
277
```
278

279
### Template Files
280

281
Templates are located in `autoapi/templates/python/`:
282

283
```python { .api }
284
# Object-specific templates:
285
"""
286
- package.rst: Package documentation template
287
- module.rst: Module documentation template
288
- class.rst: Class documentation template
289
- function.rst: Function documentation template
290
- method.rst: Method documentation template
291
- property.rst: Property documentation template
292
- attribute.rst: Attribute documentation template
293
- data.rst: Data documentation template
294
- exception.rst: Exception documentation template
295
- index.rst: Main index template
296
"""
297
```
298

299
## Utility Functions
300

301
### Argument Formatting
302

303
```python { .api }
304
def _format_args(args_info, include_annotations=True, ignore_self=None):
305
    """
306
    Format function arguments for display in documentation.
307
    
308
    Args:
309
        args_info (list[ArgInfo]): Function parameter information
310
        include_annotations (bool): Whether to show type annotations
311
        ignore_self (str): Parameter to exclude (typically 'self' or 'cls')
312
        
313
    Returns:
314
        str: Formatted argument string for signatures
315
        
316
    Handles:
317
    - Regular parameters: name, name: type, name=default
318
    - *args and **kwargs parameters
319
    - Type annotations from PEP 484/526
320
    - Default value representations
321
    """
322
```
323

324
## Usage Example
325

326
```python { .api }
327
# Accessing object hierarchy
328
for package in mapper.objects:
329
    print(f"Package: {package.name}")
330
    for module in package.children:
331
        print(f"  Module: {module.name}")
332
        for obj in module.children:
333
            if isinstance(obj, PythonClass):
334
                print(f"    Class: {obj.name}")
335
                for method in obj.children:
336
                    if isinstance(method, PythonMethod):
337
                        print(f"      Method: {method.name}")
338

339
# Rendering objects
340
content = obj.render(
341
    sphinx_version="7.4.0",
342
    autoapi_options=["members", "show-inheritance"]
343
)
344
```
345

346
The object model provides a comprehensive, structured representation of Python code that enables reliable documentation generation with full type information and cross-reference support.