Documentation Object Model

class PythonObject:
    """
    Base class for representing parsed source code entities.
    
    All AutoAPI objects inherit from this base class, providing common
    properties and methods for documentation rendering.
    
    Attributes:
        name (str): Object name (e.g., 'MyClass', 'my_function')
        qual_name (str): Fully qualified name including module path
        id (str): Unique identifier for cross-referencing
        children (list[PythonObject]): Child objects (methods, attributes, etc.)
        docstring (str): Parsed docstring content
        imported (bool): Whether object was imported from another module
        inherited (bool): Whether object was inherited from parent class
    """
    
    def render(self, **kwargs):
        """
        Render object to reStructuredText using Jinja2 templates.
        
        Args:
            **kwargs: Additional context variables for template rendering
            
        Returns:
            str: Rendered reStructuredText content
            
        Uses appropriate template based on object type (module.rst, 
        class.rst, function.rst, etc.).
        """
    
    def get_context_data(self):
        """
        Get template context data for rendering.
        
        Returns:
            dict: Context data including object properties and metadata
            
        Provides all necessary data for template rendering including
        signatures, parameters, return types, and cross-references.
        """

from autoapi._objects import PythonObject

class PythonPackage(PythonObject):
    """
    Represents a Python package containing modules and subpackages.
    
    Packages are directories with __init__.py files that group related
    modules together. AutoAPI generates package-level documentation
    including submodule listings and package docstrings.
    
    Attributes:
        children (list[PythonModule | PythonPackage]): Contained modules/packages
    """

class PythonModule(PythonObject):
    """
    Represents a Python module (.py file) containing classes, functions, and data.
    
    Modules are the primary organizational unit for Python code. AutoAPI
    extracts all module-level definitions and creates comprehensive
    documentation with proper cross-references.
    
    Attributes:
        children (list[PythonObject]): All module-level objects
        all (list[str]): Contents of __all__ if defined
        imports (list[dict]): Import statements in the module
    """

class PythonClass(PythonObject):
    """
    Represents a Python class definition with methods, properties, and attributes.
    
    Classes are parsed with full inheritance information, including
    method resolution order, inherited members, and class hierarchies.
    
    Attributes:
        bases (list[str]): Base classes this class inherits from
        children (list[PythonMethod | PythonProperty | PythonAttribute]): Class members
        constructor (PythonMethod): __init__ method if present
    """

class PythonException(PythonClass):
    """
    Represents a Python exception class.
    
    Exception classes are treated as specialized classes with additional
    documentation context for error handling scenarios.
    
    Inherits all PythonClass functionality with exception-specific templates.
    """

class PythonFunction(PythonObject):
    """
    Represents a Python function with complete signature information.
    
    Functions are parsed with full type annotation support, parameter
    documentation, and return type information.
    
    Attributes:
        args (list[ArgInfo]): Function parameters with types and defaults
        return_annotation (str): Return type annotation if present
        overloads (list[dict]): Function overloads from @overload decorator
        decorators (list[str]): Applied decorators
    """

class PythonMethod(PythonFunction):
    """
    Represents a Python method (function defined within a class).
    
    Methods inherit all function capabilities with additional context
    for class membership, method types (static, class, instance), and
    inheritance relationships.
    
    Attributes:
        method_type (str): 'method', 'staticmethod', 'classmethod', or 'property'
        properties (list[str]): Method characteristics
    """

class PythonProperty(PythonObject):
    """
    Represents a Python property created with @property decorator.
    
    Properties are parsed with getter, setter, and deleter methods,
    including proper documentation inheritance and type information.
    
    Attributes:
        getter (PythonMethod): Property getter method
        setter (PythonMethod): Property setter method if defined
        deleter (PythonMethod): Property deleter method if defined
    """

class PythonAttribute(PythonObject):
    """
    Represents a class or instance attribute.
    
    Attributes include both explicitly defined class variables and
    attributes assigned in __init__ methods, with type annotation support.
    
    Attributes:
        annotation (str): Type annotation if present
        value (str): Assigned value if determinable
    """

class PythonData(PythonObject):
    """
    Represents module-level data, constants, and variables.
    
    Data objects capture module-level assignments, constants, and
    configuration variables with type annotations and values.
    
    Attributes:
        annotation (str): Type annotation if present
        value (str): Assigned value representation
    """

# Inheritance resolution
"""AutoAPI resolves inheritance relationships including:
- Method Resolution Order (MRO) for complex hierarchies
- Inherited method and attribute documentation
- Base class cross-references
- Abstract method identification
"""

# Cross-references
"""Objects maintain relationships through:
- Parent-child relationships in object tree
- Import tracking for external references  
- Type annotation resolution for parameters/returns
- Decorator application tracking
"""

# Typical object hierarchy:
"""
PythonPackage
├── PythonModule
│   ├── PythonClass
│   │   ├── PythonMethod
│   │   ├── PythonProperty
│   │   └── PythonAttribute
│   ├── PythonFunction
│   └── PythonData
└── PythonModule (submodule)
    └── ...
"""

def get_context_data(self):
    """
    Common context data provided to all templates:
    
    Returns:
        dict: Template context including:
            - obj: The object being rendered
            - name: Object name
            - qual_name: Fully qualified name
            - id: Unique identifier
            - docstring: Parsed docstring
            - children: Child objects
            - imported: Import status
            - inherited: Inheritance status
            - signature: Function/method signature
            - parameters: Parameter documentation
            - returns: Return type information
    """

# Object-specific templates:
"""
- package.rst: Package documentation template
- module.rst: Module documentation template
- class.rst: Class documentation template
- function.rst: Function documentation template
- method.rst: Method documentation template
- property.rst: Property documentation template
- attribute.rst: Attribute documentation template
- data.rst: Data documentation template
- exception.rst: Exception documentation template
- index.rst: Main index template
"""

def _format_args(args_info, include_annotations=True, ignore_self=None):
    """
    Format function arguments for display in documentation.
    
    Args:
        args_info (list[ArgInfo]): Function parameter information
        include_annotations (bool): Whether to show type annotations
        ignore_self (str): Parameter to exclude (typically 'self' or 'cls')
        
    Returns:
        str: Formatted argument string for signatures
        
    Handles:
    - Regular parameters: name, name: type, name=default
    - *args and **kwargs parameters
    - Type annotations from PEP 484/526
    - Default value representations
    """

# Accessing object hierarchy
for package in mapper.objects:
    print(f"Package: {package.name}")
    for module in package.children:
        print(f"  Module: {module.name}")
        for obj in module.children:
            if isinstance(obj, PythonClass):
                print(f"    Class: {obj.name}")
                for method in obj.children:
                    if isinstance(method, PythonMethod):
                        print(f"      Method: {method.name}")

# Rendering objects
content = obj.render(
    sphinx_version="7.4.0",
    autoapi_options=["members", "show-inheritance"]
)