orchestrata_ultimate.session.kg_sync._ast_helpers

Reference › orchestrata_ultimate › session › kg_sync › _ast_helpers

Static helpers for reading Python syntax trees, shared by the code and trace stages. _extract_trace_decorator pulls the traceability data out of a decorator call, _decorator_name returns a decorator's name, and _is_top_level tells whether a node sits at module level. _stage_code uses them when it parses classes and functions, and the trace stage in _stage_specs_traces uses the data they produce.

At a glance

Class diagram

Dependency diagram

API

Classes

_AstHelpersMixin

Line 11

Static AST helpers shared across code/trace parsing stages.

Source

Permalink: https://gitlab.com/MSamy/orchestrata-ultimate-architecture/-/blob/a4cbc2bdf/src/orchestrata_ultimate/session/kg_sync/_ast_helpers.py

# mypy: ignore-errors
"""Static AST helper methods for the KG syncer.

Pure functions (exposed as ``@staticmethod``) for extracting trace
metadata and inspecting AST nodes. Mixed into ``KnowledgeGraphSyncer``.
"""

import ast


class _AstHelpersMixin:
    """Static AST helpers shared across code/trace parsing stages."""

    @staticmethod
    def _extract_trace_decorator(call_node: ast.Call) -> dict | None:
        """Extract spec/reqs from a @traces(...) decorator AST node."""
        func = call_node.func
        if isinstance(func, ast.Name) and func.id == "traces":
            pass
        elif isinstance(func, ast.Attribute) and func.attr == "traces":
            pass
        else:
            return None
        spec = ""
        reqs: list[str] = []
        for kw in call_node.keywords:
            if kw.arg == "spec" and isinstance(kw.value, ast.Constant):
                spec = str(kw.value.value)
            elif kw.arg == "reqs" and isinstance(kw.value, ast.List):
                reqs = [
                    elt.value
                    for elt in kw.value.elts
                    if isinstance(elt, ast.Constant) and isinstance(elt.value, str)
                ]
        return {"spec": spec, "reqs": reqs} if reqs else None

    @staticmethod
    def _decorator_name(node: ast.expr) -> str:
        """Extract decorator name from AST node."""
        if isinstance(node, ast.Name):
            return node.id
        elif isinstance(node, ast.Attribute):
            return node.attr
        elif isinstance(node, ast.Call):
            return _AstHelpersMixin._decorator_name(node.func)
        return ""

    @staticmethod
    def _is_top_level(node: ast.AST, tree: ast.Module) -> bool:
        """Check if a function node is at module top level."""
        return node in tree.body