astichi 0.1.0__py3-none-any.whl

astichi/__init__.py

@@ -0,0 +1,17 @@
+"""astichi — AST composition for ahead-of-time Python codegen."""
+
+__version__ = "0.1.0"
+
+from astichi.builder import build
+from astichi.frontend import compile
+from astichi.model import Composable, ComposableDescription, ComposableHole, TargetAddress
+
+__all__ = [
+    "__version__",
+    "Composable",
+    "ComposableDescription",
+    "ComposableHole",
+    "TargetAddress",
+    "build",
+    "compile",
+]

astichi/ast_provenance.py

@@ -0,0 +1,131 @@
+"""AST source location (lineno / col_offset) propagation for synthetic nodes.
+
+Astichi constructs many `ast.AST` nodes programmatically.  Those nodes must
+inherit line/column information from the authored subtree they replace or from
+an immediate surrounding node so diagnostics and downstream passes can anchor
+errors without reading implementation code.
+
+Policy:
+
+- After building a fresh subtree, call :func:`propagate_ast_source_locations`
+  with a *donor* that already carries a valid ``lineno`` (typically the hole,
+  insert site, or a copied authored node).
+- :func:`ast.fix_missing_locations` fills remaining gaps inside the subtree.
+"""
+
+from __future__ import annotations
+
+import ast
+from collections.abc import Iterator
+from typing import TypeGuard
+
+ASTICHI_SRC_FILE_ATTR = "_astichi_src_file"
+
+# `ast.type_param` exists on Python 3.12+; omit when absent (e.g. older runtimes).
+_located: list[type] = [
+    ast.stmt,
+    ast.expr,
+    ast.excepthandler,
+    ast.pattern,
+]
+if hasattr(ast, "type_param"):
+    _located.append(ast.type_param)
+_AST_LOCATION_TYPES: tuple[type, ...] = tuple(_located)
+
+
+def requires_ast_source_location(node: ast.AST) -> bool:
+    """Whether *node* should carry ``lineno`` for user-facing provenance."""
+    return isinstance(node, _AST_LOCATION_TYPES)
+
+
+def _lineno_ok(node: ast.AST) -> TypeGuard[ast.AST]:
+    lo = getattr(node, "lineno", None)
+    return isinstance(lo, int) and lo >= 1
+
+
+def has_valid_ast_source_location(node: ast.AST) -> bool:
+    """Return True if *node* has a usable ``lineno`` (and is a located kind)."""
+    if not requires_ast_source_location(node):
+        return True
+    return _lineno_ok(node)
+
+
+def iter_nodes_missing_ast_source_location(tree: ast.AST) -> Iterator[ast.AST]:
+    """Yield located AST nodes that lack a valid ``lineno``."""
+    for node in ast.walk(tree):
+        if requires_ast_source_location(node) and not _lineno_ok(node):
+            yield node
+
+
+def first_ast_source_location_donor(tree: ast.AST) -> ast.AST | None:
+    """Return the first node in *tree* that already has a valid ``lineno``."""
+    for node in ast.walk(tree):
+        if _lineno_ok(node):
+            return node
+    return None
+
+
+def astichi_source_file(node: ast.AST) -> str | None:
+    """Return Astichi's private source-file metadata for *node*, if present."""
+    value = getattr(node, ASTICHI_SRC_FILE_ATTR, None)
+    return value if isinstance(value, str) else None
+
+
+def attach_astichi_source_file(tree: ast.AST, file_name: str) -> None:
+    """Attach Astichi source-file metadata to every node in *tree*."""
+    for node in ast.walk(tree):
+        setattr(node, ASTICHI_SRC_FILE_ATTR, file_name)
+
+
+def copy_astichi_location(target: ast.AST, source: ast.AST) -> ast.AST:
+    """Copy Python and Astichi source location from *source* to *target*."""
+    ast.copy_location(target, source)
+    src_file = astichi_source_file(source)
+    if src_file is not None:
+        setattr(target, ASTICHI_SRC_FILE_ATTR, src_file)
+    return target
+
+
+def propagate_astichi_source_file(root: ast.AST, donor: ast.AST | None) -> None:
+    """Fill missing Astichi source-file metadata on *root* from *donor*."""
+    if donor is None:
+        return
+    src_file = astichi_source_file(donor)
+    if src_file is None:
+        return
+    for node in ast.walk(root):
+        if astichi_source_file(node) is None:
+            setattr(node, ASTICHI_SRC_FILE_ATTR, src_file)
+
+
+def propagate_ast_source_locations(root: ast.AST, donor: ast.AST | None) -> None:
+    """Attach line/column info to *root* and its descendants.
+
+    If *donor* has a valid ``lineno``, copy it onto *root* with
+    :func:`ast.copy_location` (when supported), then run
+    :func:`ast.fix_missing_locations` on *root*.
+
+    If *donor* is missing or has no line, only :func:`ast.fix_missing_locations`
+    runs (best-effort defaults — callers should prefer a real donor).
+    """
+    if isinstance(root, ast.Module):
+        ast.fix_missing_locations(root)
+        propagate_astichi_source_file(root, donor)
+        return
+    if donor is not None and _lineno_ok(donor):
+        try:
+            copy_astichi_location(root, donor)
+        except (TypeError, ValueError):
+            pass
+    ast.fix_missing_locations(root)
+    propagate_astichi_source_file(root, donor)
+
+
+def assert_tree_has_ast_source_locations(tree: ast.AST) -> None:
+    """Raise ``AssertionError`` if any located node lacks a valid ``lineno``."""
+    missing = tuple(iter_nodes_missing_ast_source_location(tree))
+    if missing:
+        kinds = ", ".join(sorted({type(n).__name__ for n in missing}))
+        raise AssertionError(
+            f"{len(missing)} AST node(s) lack source location (lineno): {kinds}"
+        )

astichi/asttools/__init__.py

@@ -0,0 +1,40 @@
+"""AST helper utilities for Astichi."""
+
+from astichi.asttools.shapes import (
+    BLOCK,
+    IDENTIFIER,
+    NAMED_VARIADIC,
+    PARAMETER,
+    POSITIONAL_VARIADIC,
+    SCALAR_EXPR,
+    MarkerShape,
+)
+from astichi.asttools.imports import (
+    import_alias_binding_name,
+    import_statement_binding_names,
+)
+from astichi.asttools.inserts import (
+    has_astichi_insert_decorator,
+    is_astichi_insert_call,
+    is_astichi_insert_shell,
+    is_expression_insert_call,
+)
+from astichi.asttools.scopes import AstichiScope, AstichiScopeMap
+
+__all__ = [
+    "AstichiScope",
+    "AstichiScopeMap",
+    "BLOCK",
+    "IDENTIFIER",
+    "NAMED_VARIADIC",
+    "PARAMETER",
+    "POSITIONAL_VARIADIC",
+    "SCALAR_EXPR",
+    "MarkerShape",
+    "has_astichi_insert_decorator",
+    "import_alias_binding_name",
+    "import_statement_binding_names",
+    "is_astichi_insert_call",
+    "is_astichi_insert_shell",
+    "is_expression_insert_call",
+]

astichi/asttools/imports.py

@@ -0,0 +1,47 @@
+"""Helpers for Python import-statement binding names."""
+
+from __future__ import annotations
+
+import ast
+
+
+def import_alias_binding_name(
+    alias: ast.alias,
+    *,
+    from_import: bool,
+    include_star: bool = False,
+) -> str | None:
+    """Return the local name bound by one ordinary Python import alias."""
+    if from_import:
+        if alias.name == "*" and not include_star:
+            return None
+        return alias.asname or alias.name
+    return alias.asname or alias.name.split(".")[0]
+
+
+def import_statement_binding_names(
+    node: ast.Import | ast.ImportFrom,
+    *,
+    include_star: bool = False,
+) -> tuple[str, ...]:
+    """Return the local binding names introduced by an import statement."""
+    names: list[str] = []
+    if isinstance(node, ast.Import):
+        for alias in node.names:
+            name = import_alias_binding_name(
+                alias,
+                from_import=False,
+                include_star=include_star,
+            )
+            if name is not None:
+                names.append(name)
+        return tuple(names)
+    for alias in node.names:
+        name = import_alias_binding_name(
+            alias,
+            from_import=True,
+            include_star=include_star,
+        )
+        if name is not None:
+            names.append(name)
+    return tuple(names)

astichi/asttools/inserts.py

@@ -0,0 +1,33 @@
+"""Predicates for internal ``astichi_insert`` surfaces."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+import ast
+
+
+def is_astichi_insert_call(node: ast.AST) -> bool:
+    """Whether ``node`` is a direct ``astichi_insert(...)`` call."""
+    return (
+        isinstance(node, ast.Call)
+        and isinstance(node.func, ast.Name)
+        and node.func.id == "astichi_insert"
+    )
+
+
+def is_expression_insert_call(node: ast.AST) -> bool:
+    """Whether ``node`` is expression-form ``astichi_insert(target, payload)``."""
+    return is_astichi_insert_call(node) and len(node.args) == 2
+
+
+def has_astichi_insert_decorator(decorators: Iterable[ast.expr]) -> bool:
+    """Whether a decorator list contains direct ``@astichi_insert(...)``."""
+    return any(is_astichi_insert_call(decorator) for decorator in decorators)
+
+
+def is_astichi_insert_shell(node: ast.AST) -> bool:
+    """Whether ``node`` is a class/def decorated by ``astichi_insert(...)``."""
+    return (
+        isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef))
+        and has_astichi_insert_decorator(node.decorator_list)
+    )

astichi/asttools/scopes.py

@@ -0,0 +1,157 @@
+"""Astichi owner-scope mapping helpers."""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass, field
+
+from astichi.asttools.inserts import (
+    is_astichi_insert_shell,
+    is_expression_insert_call,
+)
+
+
+@dataclass(eq=False)
+class AstichiScope:
+    """Astichi owner-scope identity for one AST owner root."""
+
+    root: ast.AST
+    label: str
+    parent: "AstichiScope | None" = None
+    _node_ids: set[int] = field(default_factory=set, repr=False, compare=False)
+
+    @property
+    def root_id(self) -> int:
+        return id(self.root)
+
+    def owns(self, node: ast.AST) -> bool:
+        return id(node) in self._node_ids
+
+    def is_root(self, node: ast.AST) -> bool:
+        return id(node) == self.root_id
+
+
+class AstichiScopeMap:
+    """Per-node Astichi owner-scope lookup."""
+
+    def __init__(self, tree: ast.Module) -> None:
+        self.root = AstichiScope(root=tree, label="module body", parent=None)
+        self._by_id: dict[int, AstichiScope] = {}
+        self._nested_python_root_by_id: dict[int, ast.AST] = {}
+        self._walk(tree, self.root, nested_python_root=None)
+
+    @classmethod
+    def from_tree(cls, tree: ast.Module) -> "AstichiScopeMap":
+        return cls(tree)
+
+    def scope_for(self, node: ast.AST) -> AstichiScope:
+        return self._by_id.get(id(node), self.root)
+
+    def parent_scope_for(self, scope: AstichiScope) -> AstichiScope | None:
+        return scope.parent
+
+    def nested_python_root_for(self, node: ast.AST) -> ast.AST | None:
+        return self._nested_python_root_by_id.get(id(node))
+
+    def _record(
+        self,
+        node: ast.AST,
+        scope: AstichiScope,
+        *,
+        nested_python_root: ast.AST | None,
+    ) -> None:
+        self._by_id[id(node)] = scope
+        scope._node_ids.add(id(node))
+        if nested_python_root is not None:
+            self._nested_python_root_by_id[id(node)] = nested_python_root
+
+    def _walk(
+        self,
+        node: ast.AST,
+        scope: AstichiScope,
+        *,
+        nested_python_root: ast.AST | None,
+    ) -> None:
+        self._record(node, scope, nested_python_root=nested_python_root)
+        if isinstance(node, ast.Module):
+            for child in node.body:
+                self._walk(child, scope, nested_python_root=None)
+            return
+        if is_expression_insert_call(node):
+            # Intentional ownership widening over the historical boundary-only
+            # mapper: expression-insert payloads are Astichi scopes too.
+            self._walk(node.func, scope, nested_python_root=nested_python_root)
+            self._walk(node.args[0], scope, nested_python_root=nested_python_root)
+            payload_scope = AstichiScope(
+                root=node,
+                label="expression insert payload",
+                parent=scope,
+            )
+            self._walk(node.args[1], payload_scope, nested_python_root=None)
+            for keyword in node.keywords:
+                self._walk(keyword, scope, nested_python_root=nested_python_root)
+            return
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            is_shell = is_astichi_insert_shell(node)
+            body_scope = scope
+            body_nested_root = node if not is_shell else None
+            if is_shell:
+                body_scope = AstichiScope(
+                    root=node,
+                    label=f"shell {node.name!r} body",
+                    parent=scope,
+                )
+            for decorator in node.decorator_list:
+                self._walk(decorator, scope, nested_python_root=nested_python_root)
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                # Preserve pre-refactor asymmetry: shell args/defaults are
+                # body-owned, while decorators/returns remain outer-owned.
+                self._walk_arguments(
+                    node.args,
+                    body_scope,
+                    nested_python_root=body_nested_root,
+                )
+                if node.returns is not None:
+                    self._walk(
+                        node.returns,
+                        scope,
+                        nested_python_root=nested_python_root,
+                    )
+            if isinstance(node, ast.ClassDef):
+                # Preserve pre-refactor behavior: class bases/keywords are
+                # evaluated in the outer scope, not the shell body scope.
+                for base in node.bases:
+                    self._walk(base, scope, nested_python_root=nested_python_root)
+                for keyword in node.keywords:
+                    self._walk(keyword, scope, nested_python_root=nested_python_root)
+            for child in node.body:
+                self._walk(
+                    child,
+                    body_scope,
+                    nested_python_root=body_nested_root,
+                )
+            return
+        for child in ast.iter_child_nodes(node):
+            self._walk(child, scope, nested_python_root=nested_python_root)
+
+    def _walk_arguments(
+        self,
+        args: ast.arguments,
+        scope: AstichiScope,
+        *,
+        nested_python_root: ast.AST | None,
+    ) -> None:
+        self._record(args, scope, nested_python_root=nested_python_root)
+        for argument in (
+            list(args.posonlyargs)
+            + list(args.args)
+            + list(args.kwonlyargs)
+        ):
+            self._walk(argument, scope, nested_python_root=nested_python_root)
+        if args.vararg is not None:
+            self._walk(args.vararg, scope, nested_python_root=nested_python_root)
+        if args.kwarg is not None:
+            self._walk(args.kwarg, scope, nested_python_root=nested_python_root)
+        for default in args.defaults + args.kw_defaults:
+            if default is not None:
+                self._walk(default, scope, nested_python_root=nested_python_root)

astichi/asttools/shapes.py

@@ -0,0 +1,86 @@
+"""Shape semantics for Astichi marker usage."""
+
+from __future__ import annotations
+
+from abc import ABC
+
+
+class MarkerShape(ABC):
+    """Behavior-bearing marker usage shape."""
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+
+    def is_scalar_expr(self) -> bool:
+        return False
+
+    def is_positional_variadic(self) -> bool:
+        return False
+
+    def is_named_variadic(self) -> bool:
+        return False
+
+    def is_block(self) -> bool:
+        return False
+
+    def is_identifier(self) -> bool:
+        return False
+
+    def is_parameter(self) -> bool:
+        return False
+
+
+class _ScalarExprShape(MarkerShape):
+    def __init__(self) -> None:
+        super().__init__("scalar_expr")
+
+    def is_scalar_expr(self) -> bool:
+        return True
+
+
+class _PositionalVariadicShape(MarkerShape):
+    def __init__(self) -> None:
+        super().__init__("positional_variadic")
+
+    def is_positional_variadic(self) -> bool:
+        return True
+
+
+class _NamedVariadicShape(MarkerShape):
+    def __init__(self) -> None:
+        super().__init__("named_variadic")
+
+    def is_named_variadic(self) -> bool:
+        return True
+
+
+class _BlockShape(MarkerShape):
+    def __init__(self) -> None:
+        super().__init__("block")
+
+    def is_block(self) -> bool:
+        return True
+
+
+class _IdentifierShape(MarkerShape):
+    def __init__(self) -> None:
+        super().__init__("identifier")
+
+    def is_identifier(self) -> bool:
+        return True
+
+
+class _ParameterShape(MarkerShape):
+    def __init__(self) -> None:
+        super().__init__("parameter")
+
+    def is_parameter(self) -> bool:
+        return True
+
+
+SCALAR_EXPR = _ScalarExprShape()
+POSITIONAL_VARIADIC = _PositionalVariadicShape()
+NAMED_VARIADIC = _NamedVariadicShape()
+BLOCK = _BlockShape()
+IDENTIFIER = _IdentifierShape()
+PARAMETER = _ParameterShape()

astichi/builder/__init__.py

@@ -0,0 +1,35 @@
+"""Mutable builder graph and handle surfaces for Astichi."""
+
+from astichi.builder.api import build
+from astichi.builder.graph import (
+    AdditiveEdge,
+    BuilderGraph,
+    EdgeSourceOverlay,
+    IdentifierBinding,
+    InstanceRecord,
+    TargetRef,
+)
+from astichi.builder.handles import (
+    AddProxy,
+    AddToTargetProxy,
+    BindIdentifierProxy,
+    BuilderHandle,
+    InstanceHandle,
+    TargetHandle,
+)
+
+__all__ = [
+    "AddProxy",
+    "AddToTargetProxy",
+    "AdditiveEdge",
+    "BindIdentifierProxy",
+    "BuilderGraph",
+    "BuilderHandle",
+    "EdgeSourceOverlay",
+    "IdentifierBinding",
+    "InstanceHandle",
+    "InstanceRecord",
+    "TargetHandle",
+    "TargetRef",
+    "build",
+]

astichi/builder/api.py

@@ -0,0 +1,10 @@
+"""Public builder entrypoints for Astichi."""
+
+from __future__ import annotations
+
+from astichi.builder.handles import BuilderHandle
+
+
+def build() -> BuilderHandle:
+    """Create a new Astichi builder."""
+    return BuilderHandle()