topkit 0.2.0a3__py3-none-any.whl

TopKit/errors.py

@@ -0,0 +1,138 @@
+"""Failures and diagnostics.
+
+Every failure names the semantic law it violates. A language profile may
+map these to its own exception types, but must keep them distinct.
+
+Three failures also carry the name of the check that failed, as a
+subclass: ``TagPreconditionError.Is_A_Caster`` is raised when the
+Precondition declared as ``Is_A_Caster`` refuses, so a program writes
+``except Precondition.Is_A_Caster:`` and reads its own words back.
+"""
+
+from __future__ import annotations
+
+
+class _Named(type):
+    """Metaclass for failures that name the check that failed.
+
+    ``Failure.Name`` is the subclass raised when the check called ``Name``
+    fails. A subclass exists only for a name that was declared, so a
+    misspelt handler is an AttributeError at the ``except``, not a handler
+    that never fires.
+    """
+
+    def __getattr__(
+            cls,
+            name: str,
+            ) -> type:
+        names = cls.__dict__.get("_names")
+
+        if names is None or name.startswith("_"):
+            raise AttributeError(name)
+
+        try:
+            return names[name]
+        except KeyError:
+            raise AttributeError(
+                    f"{cls.__name__} has no {name!r}: no {cls._kind} called"
+                    f" {name!r} has been declared"
+                    ) from None
+
+    def Named(
+            cls,
+            name: str,
+            ) -> type:
+        """The subclass raised when the check called ``name`` fails.
+
+        Made once per name, when the check is declared.
+        """
+
+        names = cls.__dict__["_names"]
+
+        if name not in names:
+            names[name] = type(
+                    name,
+                    (cls,),
+                    {
+                        "__module__": cls.__module__,
+                        "__qualname__": f"{cls.__qualname__}.{name}",
+                        "name": name,
+                        },
+                    )
+
+        return names[name]
+
+
+class TagError(Exception):
+    """Base failure for TopKit."""
+
+
+class TagDeclarationError(TagError):
+    """A Tag declaration is invalid (bad mark combination, bad signature)."""
+
+
+class TagCompositionError(TagError):
+    """Contributions cannot form a coherent Overlay, or a Record cannot
+    be materialized, or a teardown failed."""
+
+
+class TagResolutionError(TagError):
+    """A required Underlay, Tag view, or contribution is unavailable."""
+
+
+class TagRogueAccessError(TagResolutionError):
+    """A Rogue Agent reached a published member of a Tag it has left.
+
+    A published member answers members only (STEP-SPEC-10). The failure
+    says what happened in TOP's own words: an access, from a Rogue Agent.
+    It is a TOP failure and nothing else, so it is never swallowed by a
+    lower layer asking a different question.
+    """
+
+
+class TagPreconditionError(TagError, metaclass=_Named):
+    """A Precondition refused the Tagging. Nothing committed.
+
+    ``TagPreconditionError.Name`` is the subclass raised for the
+    Precondition declared as ``Name``; ``error.name`` is that name.
+    """
+
+    _kind = "Precondition"
+    _names: dict[str, type] = {}
+    name: str | None = None
+
+
+class TagImprintError(TagError, metaclass=_Named):
+    """An Imprint failed after the Tag applied. The Tag stays.
+
+    ``TagImprintError.Name`` is the subclass raised for the Imprint
+    declared as ``Name``; ``error.name`` is that name.
+    """
+
+    _kind = "Imprint"
+    _names: dict[str, type] = {}
+    name: str | None = None
+
+
+class TagPostconditionError(TagError, metaclass=_Named):
+    """A Postcondition found the finished Tagging defective. The Tag stays.
+
+    ``TagPostconditionError.Name`` is the subclass raised for the
+    Postcondition declared as ``Name``; ``error.name`` is that name.
+    """
+
+    _kind = "Postcondition"
+    _names: dict[str, type] = {}
+    name: str | None = None
+
+
+class TagContractError(TagError):
+    """A condition yielded a non-boolean (truthy/falsy) value."""
+
+
+class TagOverwriteWarning(UserWarning):
+    """An independent Tag replaced a visible contribution."""
+
+
+class TagContractWarning(UserWarning):
+    """A Shape weakened a Base Postcondition without @Underlay."""

TopKit/fields.py

@@ -0,0 +1,165 @@
+"""Fields: the population of Agents carrying a Tag.
+
+A Field never keeps an Agent alive. Membership is indexed by identity so
+registration and removal are constant-time. Iterating a Tag gives the
+sound population (every visible Postcondition holds), ``~Tag`` the
+defective one, ``Tag[:]`` everyone.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+from typing import Iterator
+import weakref
+
+from .errors import TagCompositionError
+
+
+class _Field:
+    """Whole population of one Tag, weakly held, in application order."""
+
+    def __init__(
+            field,
+            ) -> None:
+        field._members: dict[int, weakref.ReferenceType[object]] = {}
+
+    def Add(
+            field,
+            agent: object,
+            ) -> None:
+        key = id(agent)
+
+        if key in field._members:
+            return
+
+        try:
+            reference = weakref.ref(
+                    agent,
+                    lambda expired, key=key: field._Forget(key, expired),
+                    )
+        except TypeError as error:
+            raise TagCompositionError(
+                    "Tagged Agents must support weak references for Fields"
+                    ) from error
+
+        field._members[key] = reference
+
+    def Remove(
+            field,
+            agent: object,
+            ) -> None:
+        field._members.pop(id(agent), None)
+
+    def _Forget(
+            field,
+            key: int,
+            expired: weakref.ReferenceType[object],
+            ) -> None:
+        if field._members.get(key) is expired:
+            del field._members[key]
+
+    def __contains__(
+            field,
+            agent: object,
+            ) -> bool:
+        reference = field._members.get(id(agent))
+
+        return (
+                reference is not None
+                and reference() is agent
+                )
+
+    def __iter__(
+            field,
+            ) -> Iterator[object]:
+        live = [
+                agent
+                for agent in (
+                    reference()
+                    for reference in list(field._members.values())
+                    )
+                if agent is not None
+                ]
+
+        return iter(live)
+
+    def __len__(
+            field,
+            ) -> int:
+        return sum(
+                1
+                for reference in list(field._members.values())
+                if reference() is not None
+                )
+
+    def __bool__(
+            field,
+            ) -> bool:
+        return any(
+                reference() is not None
+                for reference in list(field._members.values())
+                )
+
+
+class _Partition:
+    """One half of a Field: the Agents for which ``holds`` is True."""
+
+    def __init__(
+            partition,
+            field: _Field,
+            holds: Callable[[object], bool],
+            label: str,
+            ) -> None:
+        partition._field = field
+        partition._holds = holds
+        partition._label = label
+
+    def __iter__(
+            partition,
+            ) -> Iterator[object]:
+        return (
+                agent
+                for agent in partition._field
+                if partition._holds(agent)
+                )
+
+    def __contains__(
+            partition,
+            agent: object,
+            ) -> bool:
+        return (
+                agent in partition._field
+                and partition._holds(agent)
+                )
+
+    def __len__(
+            partition,
+            ) -> int:
+        return sum(
+                1
+                for _ in partition
+                )
+
+    def __bool__(
+            partition,
+            ) -> bool:
+        return any(
+                True
+                for _ in partition
+                )
+
+    def __invert__(
+            partition,
+            ) -> "_Partition":
+        holds = partition._holds
+
+        return _Partition(
+                partition._field,
+                lambda agent: not holds(agent),
+                "defective" if partition._label == "sound" else "sound",
+                )
+
+    def __repr__(
+            partition,
+            ) -> str:
+        return f"<{partition._label} Field>"

TopKit/geometry.py

@@ -0,0 +1,120 @@
+"""Geometry: how Tags relate. A Base forms into a Shape.
+
+The Form of a Tag is its ordered, duplicate-free, Base-first closure,
+ending with the Tag itself. Applying a Tag follows its Form.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable
+from weakref import WeakKeyDictionary
+
+
+_tag_types: tuple[type, type] | None = None
+_form_cache: "WeakKeyDictionary[type, tuple[type, ...]]" = WeakKeyDictionary()
+
+
+def _is_tag(
+        candidate: object,
+        ) -> bool:
+    global _tag_types
+
+    if _tag_types is None:
+        from .tags import MetaTag
+        from .tags import Tag
+
+        _tag_types = (MetaTag, Tag)
+
+    meta, root = _tag_types
+
+    return (
+            isinstance(candidate, meta)
+            and candidate is not root
+            )
+
+
+def _direct_bases(
+        tag: type,
+        ) -> tuple[type, ...]:
+    """The Bases a Tag declares directly, in declaration order."""
+
+    return tuple(
+            base
+            for base in tag.__bases__
+            if _is_tag(base)
+            )
+
+
+def _form_of(
+        tag: type,
+        ) -> tuple[type, ...]:
+    """Base-first closure of one Tag: every required Base once, then the Tag."""
+
+    cached = _form_cache.get(tag)
+
+    if cached is not None:
+        return cached
+
+    form: list[type] = []
+
+    def Visit(
+            candidate: type,
+            ) -> None:
+        for base in _direct_bases(candidate):
+            Visit(base)
+
+        if candidate not in form:
+            form.append(candidate)
+
+    Visit(tag)
+
+    result = tuple(form)
+    _form_cache[tag] = result
+
+    return result
+
+
+def _leaves(
+        active: Iterable[type],
+        ) -> tuple[type, ...]:
+    """Active Tags that no other active Tag specializes."""
+
+    active = tuple(active)
+
+    return tuple(
+            candidate
+            for candidate in active
+            if not any(
+                    other is not candidate
+                    and issubclass(other, candidate)
+                    for other in active
+                    )
+            )
+
+
+def _requiring_shapes(
+        tag: type,
+        active: Iterable[type],
+        ) -> tuple[type, ...]:
+    """Active Shapes that still require ``tag`` as a Base."""
+
+    return tuple(
+            other
+            for other in active
+            if (
+                other is not tag
+                and issubclass(other, tag)
+                )
+            )
+
+
+def _related(
+        one: type,
+        other: type,
+        ) -> bool:
+    """True when one Tag is a Base or Shape of the other."""
+
+    return (
+            issubclass(one, other)
+            or issubclass(other, one)
+            )

TopKit/lifecycle.py

@@ -0,0 +1,220 @@
+"""Lifecycle: Rip, teardown, Scope, and exit protocols.
+
+Rip ends active membership. Contributions are sticky: Actions and Records
+stay on the Agent (a Rogue Agent) unless the Tag's @Rip teardowns change
+them. Ripping a Base is refused while an active Shape still requires it.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Any
+from typing import Iterator
+import atexit
+import weakref
+
+from .declarations import _parameters_of
+from .declarations import _takes_underlay
+from .errors import TagCompositionError
+from .errors import TagError
+from .errors import TagResolutionError
+from .geometry import _requiring_shapes
+from .state import _Originals
+from .state import _State
+from .state import _state_of
+
+
+def _rip(
+        agent: object,
+        tag: type,
+        ) -> object:
+    state = _state_of(agent)
+
+    if state is None or tag not in state.active:
+        raise TagResolutionError(
+                f"{tag.__name__} is not active on this Agent"
+                )
+
+    blocking = _requiring_shapes(
+            tag,
+            state.active,
+            )
+
+    if blocking:
+        names = ", ".join(
+                shape.__name__
+                for shape in blocking
+                )
+
+        raise TagCompositionError(
+                f"{tag.__name__} is required by active Shape(s): {names}"
+                )
+
+    state.active.remove(tag)
+    tag._topkit_field.Remove(agent)
+
+    _teardown(
+            agent,
+            state,
+            tag,
+            )
+
+    return agent
+
+
+def _teardown(
+        agent: object,
+        state: _State,
+        tag: type,
+        ) -> None:
+    """Run every @Rip teardown of ``tag`` once, then report failures."""
+
+    teardowns = state.rips.pop(tag, ())
+    failures: list[tuple[str, Exception]] = []
+    state.composing += 1
+
+    try:
+        for teardown in teardowns:
+            try:
+                _call_teardown(
+                        teardown,
+                        agent,
+                        state,
+                        )
+            except Exception as error:
+                failures.append(
+                        (
+                            teardown.__name__,
+                            error,
+                            )
+                        )
+    finally:
+        state.composing -= 1
+
+    if failures:
+        names = ", ".join(
+                name
+                for name, _error in failures
+                )
+
+        raise TagCompositionError(
+                f"{tag.__name__} teardown failed in: {names}"
+                ) from failures[0][1]
+
+
+def _teardown_all(
+        agent: object,
+        ) -> None:
+    """Best-effort teardown of every still-active Tag (finalizer, exit)."""
+
+    state = _state_of(agent)
+
+    if state is None:
+        return
+
+    for tag in reversed(list(state.active)):
+        for teardown in state.rips.pop(tag, ()):
+            try:
+                _call_teardown(
+                        teardown,
+                        agent,
+                        state,
+                        )
+            except Exception:
+                pass
+
+
+def _call_teardown(
+        teardown: Any,
+        agent: object,
+        state: _State,
+        ) -> None:
+    """Run one @Rip teardown. On a pinned Tag, a teardown that declares a
+    seat after the receiver (and after its Underlay, if it takes one)
+    receives the Tag's original declarations, so un-patching is
+    ``tag.Control = original.Control``."""
+
+    if state.pinned is None:
+        teardown(agent)
+        return
+
+    declared = getattr(
+            teardown,
+            "__wrapped__",
+            teardown,
+            )
+    seats = _parameters_of(declared).positional
+    receiver_seats = 2 if _takes_underlay(declared) else 1
+
+    if seats > receiver_seats:
+        teardown(
+                agent,
+                _Originals(state.originals),
+                )
+    else:
+        teardown(agent)
+
+
+@contextmanager
+def Scope(
+        agent: object,
+        *tags: type,
+        **inputs: Any,
+        ) -> Iterator[object]:
+    """Apply Tags for a block and Rip them, in reverse, on exit, even if
+    the block raises. The guaranteed teardown path."""
+
+    applied: list[type] = []
+
+    try:
+        for tag in tags:
+            tag(
+                    agent,
+                    **inputs,
+                    )
+            applied.append(tag)
+
+        yield agent
+    finally:
+        for tag in reversed(applied):
+            try:
+                _rip(
+                        agent,
+                        tag,
+                        )
+            except TagError:
+                pass
+
+
+_exit_registry: list[weakref.ReferenceType[object]] = []
+
+
+def At_Exit(
+        agent: object,
+        ) -> object:
+    """Also run the Agent's teardowns at normal interpreter exit.
+
+    Registration is weak: it never keeps the Agent alive.
+    """
+
+    _exit_registry[:] = [
+            reference
+            for reference in _exit_registry
+            if reference() is not None
+            ]
+    _exit_registry.append(
+            weakref.ref(agent)
+            )
+
+    return agent
+
+
+def _run_exit_protocols() -> None:
+    for reference in _exit_registry:
+        agent = reference()
+
+        if agent is not None:
+            _teardown_all(agent)
+
+
+atexit.register(_run_exit_protocols)