Source Code Parsing and Analysis

class Parser:
    """
    Main parser for Python source code using astroid static analysis.
    
    The Parser converts Python source files into structured data without
    requiring code execution or imports, making it safe for documenting
    packages with complex dependencies.
    """
    
    def parse_file(self, file_path: str):
        """
        Parse a single Python source file.
        
        Args:
            file_path (str): Absolute path to Python file to parse
            
        Returns:
            list: List of parsed Python objects from the file
            
        Raises:
            astroid.AstroidError: If file cannot be parsed
        """
    
    def parse_file_in_namespace(self, file_path: str, dir_root: str):
        """
        Parse a file within a namespace context for proper import resolution.
        
        Args:
            file_path (str): Path to file being parsed
            dir_root (str): Root directory for namespace resolution
            
        Returns:
            list: Parsed objects with proper namespace context
            
        This method ensures proper module path resolution for packages
        and nested modules.
        """
    
    def parse(self, node):
        """
        Parse an astroid AST node into AutoAPI objects.
        
        Args:
            node: Astroid AST node to parse
            
        Returns:
            list: AutoAPI objects representing the parsed node
            
        Handles all Python constructs: modules, classes, functions,
        methods, properties, attributes, and data.
        """

from autoapi._parser import Parser

# Module-level parsing
"""Extracts module docstrings, imports, and all module-level definitions."""

# Class parsing with inheritance
"""Parses class definitions including:
- Base classes and inheritance hierarchy
- Class docstrings and decorators
- All class methods and properties
- Class-level attributes and data
- Nested classes
"""

# Function and method parsing
"""Extracts function information including:
- Function signatures with type annotations
- Parameter names, types, and default values
- Return type annotations
- Decorators applied to functions
- Docstrings with parameter documentation
"""

# Property parsing
"""Handles property decorators and descriptors:
- @property decorated methods
- Getter, setter, deleter methods
- Property docstrings
"""

# Data and attribute parsing
"""Extracts module and class-level data:
- Variable assignments with type annotations
- Constants and configuration values
- Import statements and aliases
"""

def parse_assign(self, node):
    """
    Parse assignment statements including type annotations.
    
    Args:
        node: astroid.Assign or astroid.AnnAssign node
        
    Returns:
        list: PythonData or PythonAttribute objects
        
    Handles:
    - Simple assignments: x = value
    - Annotated assignments: x: int = value
    - Multiple assignments: a, b = values
    - Class and instance attributes
    """

def parse_annassign(self, node):
    """
    Parse annotated assignment statements (PEP 526).
    
    Args:
        node: astroid.AnnAssign node
        
    Returns:
        list: Parsed objects with type information
        
    Extracts type annotations for variables without requiring imports.
    """

def _prepare_docstring(doc):
    """
    Prepare a docstring for documentation rendering.
    
    Args:
        doc (str): Raw docstring from source code
        
    Returns:
        str: Formatted docstring ready for Sphinx processing
        
    Applies Sphinx docstring utilities:
    - Normalizes indentation
    - Handles reStructuredText formatting
    - Preserves code blocks and examples
    """

class ArgInfo:
    """
    Named tuple for structured function argument information.
    
    Fields:
        prefix (str): Argument prefix ('', '*', '**')
        name (str): Parameter name
        annotation (str): Type annotation if present
        default_value (str): Default value if present
    """

def _format_args(args_info, include_annotations=True, ignore_self=None):
    """
    Format function arguments for display in documentation.
    
    Args:
        args_info: List of ArgInfo objects
        include_annotations (bool): Whether to include type annotations
        ignore_self (str): Parameter name to ignore (typically 'self')
        
    Returns:
        str: Formatted argument string for function signatures
    """

def resolve_import_alias(name, import_names):
    """
    Resolve aliased import names to their original names.
    
    Args:
        name (str): Name to resolve
        import_names (dict): Mapping of aliases to original names
        
    Returns:
        str: Resolved name or original if no alias found
    """

def get_full_import_name(import_from, name):
    """
    Get full import path from ImportFrom node.
    
    Args:
        import_from: astroid.ImportFrom node
        name (str): Imported name
        
    Returns:
        str: Full dotted import path
    """

def resolve_qualname(node, basename):
    """
    Resolve fully qualified names for nested objects.
    
    Args:
        node: astroid node
        basename (str): Base name for qualification
        
    Returns:
        str: Fully qualified name including module path
    """

def get_assign_value(node):
    """
    Extract assignment values from AST nodes.
    
    Args:
        node: astroid assignment node
        
    Returns:
        str: String representation of assigned value
        
    Handles constants, expressions, and complex values safely.
    """

def get_assign_annotation(node):
    """
    Get type annotations from assignment statements.
    
    Args:
        node: astroid assignment node
        
    Returns:
        str: Type annotation string or None
    """

def get_const_value(node):
    """
    Extract constant values from AST nodes.
    
    Args:
        node: astroid node containing constant
        
    Returns:
        str: String representation of constant value
        
    Safely extracts string, number, and boolean constants.
    """

def is_constructor(node):
    """
    Check if a node represents a constructor method.
    
    Args:
        node: astroid method node
        
    Returns:
        bool: True if node is __init__ or __new__ method
    """

def is_functional_namedtuple(node):
    """
    Check if a node represents a functional namedtuple definition.
    
    Args:
        node: astroid assignment node
        
    Returns:
        bool: True if assignment creates namedtuple via function call
    """

# Syntax errors in source files
"""Parser logs syntax errors and continues processing other files."""

# Import resolution failures  
"""Unresolvable imports are noted but don't halt documentation generation."""

# Complex type annotations
"""Advanced typing constructs are captured as strings when full resolution isn't possible."""

# Encoding issues
"""Source files with encoding problems are handled gracefully."""

from autoapi._parser import Parser

# Create parser instance
parser = Parser()

# Parse a single file
objects = parser.parse_file('/path/to/module.py')

# Parse file with namespace context
objects = parser.parse_file_in_namespace(
    '/path/to/package/module.py',
    '/path/to/package'
)

# Objects contain structured data ready for documentation generation
for obj in objects:
    print(f"{obj.name}: {obj.type}")