pyinto 0.0.1__py3-none-any.whl

pyinto/__init__.py

@@ -0,0 +1,15 @@
+"""pyinto 0.0.1: experimental Python-AST-to-Construct pipeline."""
+
+from pyinto.api import convert, realize
+from pyinto.constructs import Construct, ConstructError, Program
+from pyinto.frontend import PythonFrontend, UnsupportedPython
+
+__all__ = [
+    "Construct",
+    "ConstructError",
+    "Program",
+    "PythonFrontend",
+    "UnsupportedPython",
+    "convert",
+    "realize",
+]

pyinto/admission.py

@@ -0,0 +1,154 @@
+"""Target-neutral admission contracts owned by Construct providers.
+
+Providers declare each concrete Construct, including those whose current
+realization admission requirements are empty. A Target Pack merely declares
+which concrete obligation keys it supports; it cannot invent or waive them.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+from types import MappingProxyType
+
+from pyinto.constructs.base import Construct
+from pyinto.constructs.types import ConstructError
+
+
+@dataclass(frozen=True)
+class AdmissionRule:
+    """A provider-defined, Target-independent group of semantic obligations.
+
+    A contract ending in ``.*`` declares an *open family* of concrete names.
+    This never authorizes a Target to use wildcard ``supports`` declarations.
+    """
+
+    name: str
+    constructs: tuple[type[Construct], ...]
+    guarded_fields: frozenset[str]
+    contracts: frozenset[str]
+    resolve: Callable[[Construct], frozenset[str]]
+
+
+@dataclass(frozen=True)
+class AdmissionDeclaration:
+    """Explicit provider-owned admission policy for one *exact* Construct type.
+
+    An empty ``rules`` tuple is an intentional declaration that no additional
+    runtime admission keys have yet been established for this Construct, NOT a
+    claim that arbitrary Target recipes preserve its semantics.
+    """
+
+    construct: type[Construct]
+    rules: tuple[AdmissionRule, ...] = ()
+
+
+def _matches_contract(name: str, declared: frozenset[str]) -> bool:
+    return name in declared or any(
+        token.endswith(".*") and name.startswith(token[:-1]) for token in declared
+    )
+
+
+def collect_contracts(
+    node: Construct, rules: Iterable[AdmissionRule]
+) -> frozenset[str]:
+    """Extract only explicit, provider-defined obligations, without inference."""
+    required: set[str] = set()
+    for rule in rules:
+        if type(node) in rule.constructs:
+            names = rule.resolve(node)
+            if not all(_matches_contract(name, rule.contracts) for name in names):
+                raise ValueError(f"Admission rule {rule.name} emitted undeclared key")
+            required.update(names)
+    return frozenset(required)
+
+
+class AdmissionRegistry:
+    """Immutable provider catalog, independent of any selected Target Pack.
+
+    Exact type registration ensures that subclassing a known Construct never
+    silently inherits an admission policy that did not examine its new fields.
+    """
+
+    def __init__(self, declarations: Iterable[AdmissionDeclaration] = ()) -> None:
+        policies: dict[type[Construct], tuple[AdmissionRule, ...]] = {}
+        rule_names: dict[str, AdmissionRule] = {}
+        for declaration in declarations:
+            cls = declaration.construct
+            if not isinstance(cls, type) or not issubclass(cls, Construct):
+                raise TypeError("Admission declaration requires a Construct type")
+            if cls in policies:
+                raise ValueError(f"Duplicate Construct admission: {cls.__name__}")
+            if len({rule.name for rule in declaration.rules}) != len(declaration.rules):
+                raise ValueError("Duplicate admission rule names")
+            for rule in declaration.rules:
+                if cls not in rule.constructs:
+                    raise ValueError(
+                        f"Admission rule {rule.name} does not cover {cls.__name__}"
+                    )
+                if not rule.name or not rule.contracts or not rule.constructs:
+                    raise ValueError("Invalid admission rule declaration")
+                if not rule.guarded_fields <= set(
+                    getattr(cls, "__dataclass_fields__", {})
+                ):
+                    raise ValueError(
+                        f"Admission rule {rule.name} guards unknown fields"
+                    )
+                other = rule_names.setdefault(rule.name, rule)
+                if other is not rule:
+                    raise ValueError("Duplicate admission rule names")
+            policies[cls] = declaration.rules
+        self._policies = MappingProxyType(policies)
+
+    @property
+    def declarations(self) -> tuple[AdmissionDeclaration, ...]:
+        return tuple(
+            AdmissionDeclaration(cls, rules) for cls, rules in self._policies.items()
+        )
+
+    def require_baseline(self, baseline: AdmissionRegistry) -> None:
+        """Require an unchanged provider-owned baseline, allowing additions.
+
+        This check is independent of any particular Interface. It is used by
+        the Host to protect its Language Construct policies from replacement.
+        """
+        for cls, rules in baseline._policies.items():
+            if cls not in self._policies or self._policies[cls] != rules:
+                raise ValueError(
+                    f"Missing or replaced baseline Construct admission: {cls.__name__}"
+                )
+
+    def extend(self, declarations: Iterable[AdmissionDeclaration]) -> AdmissionRegistry:
+        """Provider-only extension. Existing policies cannot be replaced."""
+        return AdmissionRegistry((*self.declarations, *tuple(declarations)))
+
+    def _rules_for(self, node: Construct) -> tuple[AdmissionRule, ...]:
+        try:
+            return self._policies[type(node)]
+        except KeyError as exc:
+            raise ConstructError(
+                f"Unregistered Construct admission: {type(node).__name__}"
+            ) from exc
+
+    def check_tree(self, root: Construct) -> None:
+        """Reject undeclared children even if a Template ignores their Slots.
+
+        This is an inventory check, not a requirement that all children are
+        realized. Whether omission preserves meaning remains a separate issue.
+        """
+        visited: set[int] = set()
+        pending: list[object] = [root]
+        while pending:
+            item = pending.pop()
+            if isinstance(item, Construct):
+                if id(item) in visited:
+                    continue
+                visited.add(id(item))
+                self._rules_for(item)
+                pending.extend(item.parts().values())
+            elif isinstance(item, (tuple, list)):
+                pending.extend(item)
+
+    def required_contracts(self, node: Construct) -> frozenset[str]:
+        """Fail closed on unregistered concrete Construct types."""
+        return collect_contracts(node, self._rules_for(node))

pyinto/analysis/__init__.py

@@ -0,0 +1,5 @@
+"""Read-only analysis of existing, target-independent Constructs."""
+
+from pyinto.analysis.closures import lexical_captures
+
+__all__ = ["lexical_captures"]

pyinto/analysis/closures.py

@@ -0,0 +1,83 @@
+"""Derive *static* free lexical bindings without a Closure Construct.
+
+No source is executed and no runtime closure object is created.  Captures are
+symbol declarations, not per-invocation environments.  The latter, including
+escaping values and distinct calls of one factory, remains a Realization duty.
+"""
+
+from __future__ import annotations
+
+from pyinto.constructs import (
+    Construct,
+    ConstructError,
+    FunctionCall,
+    FunctionDefinition,
+    Reference,
+    Symbol,
+)
+
+
+def lexical_captures(definition: FunctionDefinition) -> tuple[Symbol, ...]:
+    """Find direct non-module lexical dependencies of one function body.
+
+    A captured Symbol belongs to a strict enclosing function scope.  Function
+    declaration references (including direct calls to an enclosing function)
+    use their existing stable ``FunctionSignature.value_symbol``.  The result
+    contains each declaration once, in first-use order, preserving *identity*.
+
+    Nested function bodies are excluded: each function's own captures can be
+    inspected separately.  A Realization that needs transitively retained
+    environments must analyze the nested definitions and their escape paths;
+    this function does not infer liveness or allocate runtime frames.
+    """
+    if not isinstance(definition, FunctionDefinition):
+        raise TypeError("lexical_captures requires a FunctionDefinition")
+
+    current_scope = (*definition.signature.scope, definition.signature.name)
+    try:
+        own_value_symbol = definition.signature.value_symbol
+    except ConstructError:
+        own_value_symbol = None
+    seen: set[int] = set()
+    result: list[Symbol] = []
+
+    def consider(symbol: Symbol) -> None:
+        owner = symbol.scope
+        if (
+            not owner  # Module-level bindings are not captured lexical locals.
+            or len(owner) >= len(current_scope)
+            or current_scope[: len(owner)] != owner
+            or symbol is own_value_symbol
+        ):
+            return
+        key = id(symbol)
+        if key not in seen:
+            seen.add(key)
+            result.append(symbol)
+
+    def visit(item: object) -> None:
+        if isinstance(item, FunctionDefinition):
+            # Child definitions have their own frame and capture set.
+            return
+        if isinstance(item, Reference):
+            consider(item.symbol)
+        if isinstance(item, FunctionCall):
+            signature = item.signature
+            if signature is not definition.signature:
+                # An unshaped Port function can still be directly called.
+                # Its declaration is already available through the signature.
+                try:
+                    symbol = signature.value_symbol
+                except ConstructError:
+                    symbol = None
+                if symbol is not None:
+                    consider(symbol)
+        if isinstance(item, Construct):
+            for child in item.parts().values():
+                visit(child)
+        elif isinstance(item, (tuple, list)):
+            for child in item:
+                visit(child)
+
+    visit(definition.body)
+    return tuple(result)

pyinto/api.py

@@ -0,0 +1,62 @@
+"""Public conversion entrances; Constructs are independent of Realization."""
+
+from __future__ import annotations
+
+from pyinto.admission import AdmissionRegistry
+from pyinto.constructs import Construct
+from pyinto.frontend import PythonFrontend
+from pyinto.interface_mapping.registry import InterfaceMappingRegistry
+from pyinto.intrinsics import IntrinsicRegistry
+from pyinto.realizations.host import RealizationHost
+from pyinto.realizations.registry import RealizationRegistry
+
+
+def realize(
+    program: Construct,
+    *,
+    realizations: RealizationRegistry,
+    admission: AdmissionRegistry | None = None,
+) -> object:
+    """Realize an existing Model with an explicitly selected Target Pack.
+
+    Construct trees are never modified. No target is selected implicitly.
+    """
+    if not isinstance(program, Construct):
+        raise TypeError("A Construct is required")
+    if not isinstance(realizations, RealizationRegistry):
+        raise TypeError("A validated RealizationRegistry is required")
+    if admission is not None and not isinstance(admission, AdmissionRegistry):
+        raise TypeError("An AdmissionRegistry is required")
+    return RealizationHost(realizations, admission=admission).run(program)
+
+
+def convert(
+    source: str,
+    *,
+    realizations: RealizationRegistry,
+    interface_mappings: InterfaceMappingRegistry | None = None,
+    intrinsics: IntrinsicRegistry | None = None,
+    admission: AdmissionRegistry | None = None,
+) -> object:
+    """Normalize Python text, then request the selected Target's artifact."""
+    if not isinstance(source, str):
+        raise TypeError("Python source must be a string")
+    if not isinstance(realizations, RealizationRegistry):
+        raise TypeError("A validated RealizationRegistry is required")
+    if interface_mappings is not None and not isinstance(
+        interface_mappings, InterfaceMappingRegistry
+    ):
+        raise TypeError(
+            "An InterfaceMappingRegistry is required for interface_mappings"
+        )
+    if intrinsics is not None and not isinstance(intrinsics, IntrinsicRegistry):
+        raise TypeError("An IntrinsicRegistry is required")
+    return realize(
+        PythonFrontend(
+            interface_mappings=interface_mappings, intrinsics=intrinsics
+        ).parse(source),
+        realizations=realizations,
+        admission=admission
+        if admission is not None
+        else (interface_mappings.admission if interface_mappings is not None else None),
+    )

pyinto/constructs/__init__.py

@@ -0,0 +1,224 @@
+"""Target-neutral Construct Model, organized by semantic responsibility.
+
+Modules contain the definitions; this namespace gathers the Model vocabulary.
+"""
+
+from .base import (
+    Construct,
+    Value,
+)
+from .classes import (
+    ClassDefinition,
+    ClassMethodCall,
+    ClassReceiverCreation,
+    ClassReference,
+    ClassSignature,
+    FieldDefinition,
+    FieldInitialize,
+    FieldRead,
+    FieldWrite,
+    InstanceCreation,
+    MethodCall,
+    MethodDispatch,
+)
+from .collections import (
+    DictElement,
+    DictElementAssign,
+    DictEntry,
+    DictValue,
+    ListElement,
+    ListElementAssign,
+    ListValue,
+    Membership,
+    SliceValue,
+    TupleElement,
+    TupleValue,
+)
+from .control import (
+    SUPPORTED_EXCEPTION_NAMES,
+    Assign,
+    Block,
+    Branch,
+    Break,
+    Call,
+    ContextEntry,
+    Continue,
+    ExceptHandler,
+    ExpressionStatement,
+    For,
+    Initialize,
+    IterationEntry,
+    Pass,
+    Program,
+    Raise,
+    Range,
+    Try,
+    UnpackAssign,
+    While,
+    With,
+)
+from .formatting import FormattedString, PrintValues
+from .functions import (
+    FunctionCall,
+    FunctionDefinition,
+    FunctionSignature,
+    FunctionValueCall,
+    LambdaValue,
+    Parameter,
+    Return,
+)
+from .intrinsic import (
+    IntrinsicCall,
+    IntrinsicDefinition,
+    IntrinsicListType,
+    IntrinsicTypeVar,
+)
+from .operations import (
+    Absolute,
+    Arithmetic,
+    BooleanAggregate,
+    BooleanNot,
+    BooleanOperation,
+    Comparison,
+    ComparisonChain,
+    Extremum,
+    FloatingArithmetic,
+    FloatingComparison,
+    FloatingUnary,
+    IntegerSum,
+    IntegerTrueDivision,
+    IntegerUnary,
+    Length,
+    StringComparison,
+    StringConcat,
+    StringContains,
+    StringElement,
+    StringRepeat,
+)
+from .types import (
+    CallableType,
+    ConstructError,
+    DictType,
+    Identifier,
+    InstanceType,
+    ListType,
+    MethodKind,
+    ParameterRole,
+    PortType,
+    Symbol,
+    TupleType,
+    ValueKind,
+    ValueType,
+)
+from .updates import AugAssign, AugAssignMode
+from .values import (
+    BooleanLiteral,
+    ConditionalExpression,
+    FloatingLiteral,
+    Literal,
+    NoneLiteral,
+    Reference,
+)
+
+__all__ = [
+    "SUPPORTED_EXCEPTION_NAMES",
+    "Absolute",
+    "Arithmetic",
+    "Assign",
+    "AugAssign",
+    "AugAssignMode",
+    "Block",
+    "BooleanAggregate",
+    "BooleanLiteral",
+    "BooleanNot",
+    "BooleanOperation",
+    "Branch",
+    "Break",
+    "Call",
+    "CallableType",
+    "ClassDefinition",
+    "ClassMethodCall",
+    "ClassReceiverCreation",
+    "ClassReference",
+    "ClassSignature",
+    "Comparison",
+    "ComparisonChain",
+    "ConditionalExpression",
+    "Construct",
+    "ConstructError",
+    "ContextEntry",
+    "Continue",
+    "DictElement",
+    "DictElementAssign",
+    "DictEntry",
+    "DictType",
+    "DictValue",
+    "ExceptHandler",
+    "ExpressionStatement",
+    "Extremum",
+    "FieldDefinition",
+    "FieldInitialize",
+    "FieldRead",
+    "FieldWrite",
+    "FloatingArithmetic",
+    "FloatingComparison",
+    "FloatingLiteral",
+    "FloatingUnary",
+    "For",
+    "FormattedString",
+    "FunctionCall",
+    "FunctionDefinition",
+    "FunctionSignature",
+    "FunctionValueCall",
+    "Identifier",
+    "Initialize",
+    "InstanceCreation",
+    "InstanceType",
+    "IntegerSum",
+    "IntegerTrueDivision",
+    "IntegerUnary",
+    "IntrinsicCall",
+    "IntrinsicDefinition",
+    "IntrinsicListType",
+    "IntrinsicTypeVar",
+    "IterationEntry",
+    "LambdaValue",
+    "Length",
+    "ListElement",
+    "ListElementAssign",
+    "ListType",
+    "ListValue",
+    "Literal",
+    "Membership",
+    "MethodCall",
+    "MethodDispatch",
+    "MethodKind",
+    "NoneLiteral",
+    "Parameter",
+    "ParameterRole",
+    "Pass",
+    "PortType",
+    "PrintValues",
+    "Program",
+    "Raise",
+    "Range",
+    "Reference",
+    "Return",
+    "SliceValue",
+    "StringComparison",
+    "StringConcat",
+    "StringContains",
+    "StringElement",
+    "StringRepeat",
+    "Symbol",
+    "Try",
+    "TupleElement",
+    "TupleType",
+    "TupleValue",
+    "UnpackAssign",
+    "Value",
+    "ValueKind",
+    "ValueType",
+    "While",
+    "With",
+]