orchestrata_tools.models.ast_models

Reference › orchestrata_tools › models › ast_models

This module holds the unified AST data classes that every analyzer, generator and review engine in orchestrata_tools works on. They describe a Python codebase as extracted by the AST serializer and are filled by json_loader or source_parser. They are close to, but simpler than, the model in orchestrata_ast.models: they have no body hashes, line spans, env accesses or argv literals, and imports carry no scope information.

The classes nest from the top:

• ASTCodebase has the name, root path, modules, the inheritance and dependency graphs, and totals. As used elsewhere in the package it exposes flattened views such as all_classes, all_methods, all_functions and all_imports.
• ModuleInfo has classes, functions, imports, module variables, docstring and __all__ exports, with class_count, function_count and method_count properties.
• ClassInfo has bases, decorators, methods (MethodInfo), class variables (ClassVarInfo), flags for abstract, dataclass, pydantic, protocol and enum, inner classes and properties such as public_methods and method_count.
• MethodInfo and FunctionInfo carry async and kind flags, decorators, parameters (ParamInfo), return type, docstring and the calls made. is_public, is_special, fully_qualified_name and method_path give naming helpers.
• ImportInfo records the module, imported names, alias and relative level.

At a glance

Class diagram

Dependency diagram

Truncated at 25 nodes: showing 0 of 0 imports and 24 of 25 importers.

API

Classes

ParamInfo (dataclass)

Decorators: dataclass · Line 16

A method/function parameter.

MethodInfo (dataclass)

Decorators: dataclass · Line 26

A method inside a class.

FunctionInfo (dataclass)

Decorators: dataclass · Line 72

A standalone function at module level.

ClassVarInfo (dataclass)

Decorators: dataclass · Line 102

A class variable.

ClassInfo (dataclass)

Decorators: dataclass · Line 111

A class definition.

ImportInfo (dataclass)

Decorators: dataclass · Line 145

An import statement.

ModuleInfo (dataclass)

Decorators: dataclass · Line 157

A Python module.

ASTCodebase (dataclass)

Decorators: dataclass · Line 184

A complete codebase represented as AST.

Source

Permalink: https://gitlab.com/MSamy/orchestrata-ultimate-architecture/-/blob/a4cbc2bdf/src/orchestrata_tools/models/ast_models.py

"""Unified AST data models for orchestrata_tools.

These models represent the complete structure of a Python codebase
as extracted by the AST serializer. They are used by all analyzers,
generators, and review engines in the orchestrata_tools package.
"""

from __future__ import annotations

import itertools
from dataclasses import dataclass, field
from typing import Any


@dataclass
class ParamInfo:
    """A method/function parameter."""

    name: str
    type_annotation: str | None = None
    default: str | None = None
    kind: str = "positional"  # positional, keyword, var_positional, var_keyword


@dataclass
class MethodInfo:
    """A method inside a class."""

    name: str
    qualified_name: str
    module_path: str
    file_path: str
    line: int
    is_async: bool = False
    is_method: bool = True
    is_classmethod: bool = False
    is_staticmethod: bool = False
    is_property: bool = False
    is_abstract: bool = False
    decorators: list[str] = field(default_factory=list)
    parameters: list[ParamInfo] = field(default_factory=list)
    return_type: str | None = None
    docstring: str | None = None
    class_name: str = ""
    calls: list[str] = field(default_factory=list)

    @property
    def is_public(self) -> bool:
        return not self.name.startswith("_")

    @property
    def is_special(self) -> bool:
        return self.name.startswith("__") and self.name.endswith("__")

    @property
    def fully_qualified_name(self) -> str:
        """Fully qualified name: module_path.class_name.method_name.

        Guaranteed unique across the codebase.
        """
        if self.class_name:
            return f"{self.module_path}.{self.class_name}.{self.name}"
        return f"{self.module_path}.{self.name}"

    @property
    def method_path(self) -> str:
        """Alias for fully_qualified_name."""
        return self.fully_qualified_name


@dataclass
class FunctionInfo:
    """A standalone function at module level."""

    name: str
    qualified_name: str
    module_path: str
    file_path: str
    line: int
    is_async: bool = False
    decorators: list[str] = field(default_factory=list)
    parameters: list[ParamInfo] = field(default_factory=list)
    return_type: str | None = None
    docstring: str | None = None

    @property
    def is_public(self) -> bool:
        return not self.name.startswith("_")

    @property
    def fully_qualified_name(self) -> str:
        """Fully qualified name: module_path.function_name."""
        return f"{self.module_path}.{self.name}"

    @property
    def method_path(self) -> str:
        """Alias for fully_qualified_name."""
        return self.fully_qualified_name


@dataclass
class ClassVarInfo:
    """A class variable."""

    name: str
    type_annotation: str | None = None
    default: str | None = None


@dataclass
class ClassInfo:
    """A class definition."""

    name: str
    qualified_name: str
    module_path: str
    file_path: str
    line: int
    bases: list[str] = field(default_factory=list)
    decorators: list[str] = field(default_factory=list)
    methods: list[MethodInfo] = field(default_factory=list)
    class_vars: list[ClassVarInfo] = field(default_factory=list)
    docstring: str | None = None
    is_abstract: bool = False
    is_dataclass: bool = False
    is_pydantic: bool = False
    is_protocol: bool = False
    is_enum: bool = False
    inner_classes: list[ClassInfo] = field(default_factory=list)

    @property
    def public_methods(self) -> list[MethodInfo]:
        return [m for m in self.methods if m.is_public]

    @property
    def method_count(self) -> int:
        return len(self.methods)

    @property
    def property_methods(self) -> list[MethodInfo]:
        return [m for m in self.methods if m.is_property]


@dataclass
class ImportInfo:
    """An import statement."""

    module: str = ""
    names: list[str] = field(default_factory=list)
    alias: str | None = None
    is_from: bool = False
    is_relative: bool = False
    level: int = 0


@dataclass
class ModuleInfo:
    """A Python module."""

    path: str
    file_path: str
    line_count: int = 0
    classes: list[ClassInfo] = field(default_factory=list)
    functions: list[FunctionInfo] = field(default_factory=list)
    imports: list[ImportInfo] = field(default_factory=list)
    module_vars: list[dict[str, Any]] = field(default_factory=list)
    docstring: str | None = None
    all_exports: list[str] = field(default_factory=list)

    @property
    def class_count(self) -> int:
        return len(self.classes)

    @property
    def function_count(self) -> int:
        return len(self.functions)

    @property
    def method_count(self) -> int:
        return sum(len(c.methods) for c in self.classes)


@dataclass
class ASTCodebase:
    """A complete codebase represented as AST."""

    name: str
    root_path: str
    modules: list[ModuleInfo] = field(default_factory=list)
    inheritance_graph: dict[str, list[str]] = field(default_factory=dict)
    dependency_graph: dict[str, list[str]] = field(default_factory=dict)
    total_classes: int = 0
    total_functions: int = 0
    total_methods: int = 0
    total_loc: int = 0

    @property
    def all_classes(self) -> list[ClassInfo]:
        return list(itertools.chain.from_iterable(mod.classes for mod in self.modules))

    @property
    def all_methods(self) -> list[MethodInfo]:
        return list(
            itertools.chain.from_iterable(
                cls.methods for mod in self.modules for cls in mod.classes
            )
        )

    @property
    def all_functions(self) -> list[FunctionInfo]:
        return list(
            itertools.chain.from_iterable(mod.functions for mod in self.modules)
        )

    @property
    def all_imports(self) -> list[ImportInfo]:
        return list(itertools.chain.from_iterable(mod.imports for mod in self.modules))