topkit 0.2.0a3__py3-none-any.whl

TopKit/tags.py

@@ -0,0 +1,251 @@
+"""The public TOP types: Tag and its metaclass.
+
+TOP borrows the language's own syntax for Tag-level acts and leaves the
+Tag's dotted namespace to the program:
+
+    Wizard(charlie)               apply (Bases first)
+    charlie in Wizard             active membership, sound or defective
+    "Deprecated" in Wizard        a keyword: the Tag carries the Flag Pin Deprecated
+    Wizard in charlie             the same, from the Agent's side
+    "Wizard" in charlie           the same, by name
+    isinstance(charlie, Wizard)   ever a member ("ever a Wizard, always a Wizard")
+    for w in Wizard               the sound population
+    if Wizard                     is there a sound Wizard at all?
+    for w in ~Wizard              the defective population
+    Wizard[:]                     everyone: the whole Field
+    Wizard[charlie]               the Agent-bound view
+    del Wizard[charlie]           leave the Field (Rip)
+    Form(Wizard)                  the Base-first closure, as Tags
+    f"{Wizard:form}"              the same, as text
+
+A Tag marked @Pin applies to Tags (STEP-SPEC-9); the pinned Tag is then
+an Agent in every spelling above: Rare(Wizard), Wizard in Rare,
+for tag in Rare, Rare[Wizard], del Rare[Wizard], f"{Wizard:pins}".
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from typing import Iterator
+
+from .access import _view_of
+from .contracts import _holds
+from .declarations import _MISSING
+from .declarations import _check_pin_bases
+from .declarations import _is_pin
+from .declarations import _name_checks
+from .errors import TagCompositionError
+from .fields import _Field
+from .fields import _Partition
+from .geometry import _form_of
+from .geometry import _is_tag
+from .lifecycle import _rip
+from .state import Tagged
+from .state import _name_of
+from .state import _state_of
+from .transactions import _apply
+
+
+class MetaTag(type):
+    """Metaclass of every Tag: the Tag-level acts, in language syntax."""
+
+    def __new__(
+            meta,
+            name: str,
+            bases: tuple[type, ...],
+            namespace: dict[str, Any],
+            **kwargs: Any,
+            ) -> "MetaTag":
+        namespace.setdefault(
+                "_topkit_field",
+                _Field(),
+                )
+        _name_checks(namespace)
+
+        tag = super().__new__(
+                meta,
+                name,
+                bases,
+                namespace,
+                **kwargs,
+                )
+        _check_pin_bases(tag)
+
+        return tag
+
+    def __call__(
+            tag,
+            target: object = _MISSING,
+            /,
+            **inputs: Any,
+            ) -> object:
+        if target is _MISSING:
+            raise TypeError(
+                    f"{tag.__name__} is a Tag: apply it to a Target,"
+                    f" {tag.__name__}(target)"
+                    )
+
+        if _is_pin(tag):
+            _check_pin_target(
+                    tag,
+                    target,
+                    )
+        elif isinstance(target, type):
+            raise TypeError(
+                    f"{tag.__name__} is applied to objects, not classes"
+                    )
+
+        return _apply(
+                target,
+                tag,
+                inputs,
+                )
+
+    def __contains__(
+            tag,
+            candidate: object,
+            ) -> bool:
+        """``agent in Wizard``: membership. ``"Deprecated" in Wizard``: a
+        keyword among the Tag's Flag Pins; a string is never a member."""
+
+        if isinstance(candidate, str):
+            from .access import _keyword
+
+            return _keyword(
+                    tag,
+                    candidate,
+                    )
+
+        state = _state_of(candidate)
+
+        return (
+                state is not None
+                and tag in state.active
+                )
+
+    def __instancecheck__(
+            tag,
+            candidate: object,
+            ) -> bool:
+        state = _state_of(candidate)
+
+        if state is not None and tag in state.ever:
+            return True
+
+        return super().__instancecheck__(candidate)
+
+    def _sound(
+            tag,
+            ) -> _Partition:
+        return _Partition(
+                tag._topkit_field,
+                _holds,
+                "sound",
+                )
+
+    def __iter__(
+            tag,
+            ) -> Iterator[object]:
+        return iter(tag._sound())
+
+    def __len__(
+            tag,
+            ) -> int:
+        return len(tag._sound())
+
+    def __bool__(
+            tag,
+            ) -> bool:
+        return bool(tag._sound())
+
+    def __invert__(
+            tag,
+            ) -> _Partition:
+        return ~tag._sound()
+
+    def __getitem__(
+            tag,
+            key: Any,
+            ) -> Any:
+        if isinstance(key, slice):
+            if key != slice(None):
+                raise TypeError(
+                        "Tag[:] is the whole Field; positional slices have"
+                        " no meaning for a population"
+                        )
+
+            return tag._topkit_field
+
+        return _view_of(
+                key,
+                tag,
+                )
+
+    def __delitem__(
+            tag,
+            agent: object,
+            ) -> None:
+        _rip(
+                agent,
+                tag,
+                )
+
+    def __format__(
+            tag,
+            spec: str,
+            ) -> str:
+        if spec == "":
+            return str(tag)
+
+        if spec == "form":
+            return " → ".join(
+                    member.__name__
+                    for member in _form_of(tag)
+                    )
+
+        if spec == "pins":
+            from .queries import Tags
+
+            return ", ".join(
+                    pin.__name__
+                    for pin in Tags(tag)
+                    )
+
+        if spec == "contract":
+            from .contracts import Contract
+
+            return Contract.Display(tag)
+
+        raise ValueError(
+                f"unknown format spec {spec!r} for a Tag; use 'form',"
+                " 'pins', or 'contract'"
+                )
+
+
+def _check_pin_target(
+        pin: type,
+        target: object,
+        ) -> None:
+    if not _is_tag(target):
+        raise TagCompositionError(
+                f"{pin.__name__} is a Pin: apply it to a Tag, not to"
+                f" {_name_of(target)}"
+                )
+
+    if target in _form_of(pin):
+        raise TagCompositionError(
+                f"{pin.__name__} cannot pin itself"
+                )
+
+
+class Tag(metaclass=MetaTag):
+    """A semantic category. Subclass it; its members are its contributions."""
+
+    __slots__ = ()
+
+
+__all__ = [
+        "MetaTag",
+        "Tag",
+        "Tagged",
+        ]

TopKit/transactions.py

@@ -0,0 +1,474 @@
+"""Applying a Tag: the tagging sequence and its call boundary.
+
+Once for the whole call:
+
+    1. Gate: the Preconditions visible in the composed Form of this call
+       inspect the incoming Agent. A Shape's override wins over its Base's.
+
+For each Tag in the Form (Bases first), in order:
+
+    2. Its Records are built (each may read the value already stored).
+    3. Commit: membership, Overlay, runtime type.
+    4. Its Imprints run.
+
+Once for the whole call:
+
+    5. Every visible Postcondition is checked.
+
+A failure in 1 or 2 rolls the whole call back: the Agent is exactly as it
+was, including Bases pulled in by this call. A failure in 4 or 5 raises
+but the Tags stay: the product left the line, defective, to be repaired
+or Ripped.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+import warnings
+
+from .contracts import _evaluate
+from .declarations import _Declarations
+from .declarations import _declarations_of
+from .declarations import _protocol_inputs
+from .errors import TagCompositionError
+from .errors import TagError
+from .errors import TagImprintError
+from .errors import TagPostconditionError
+from .errors import TagPreconditionError
+from .geometry import _form_of
+from .overlay import _install
+from .overlay import _materialize
+from .state import STATE
+from .state import Tagged
+from .state import _Snapshot
+from .state import _State
+from .state import _bind_to
+from .state import _namespace_of
+from .state import _rebind_all
+from .state import _restore_namespace
+from .state import _runtime_type_for
+from .state import _state_for
+from .state import _state_of
+
+
+def _apply(
+        agent: object,
+        tag: type,
+        inputs: dict[str, Any],
+        ) -> object:
+    """Apply ``tag`` and its missing Bases to ``agent`` as one call."""
+
+    entry_namespace = dict(_namespace_of(agent) or {})
+    entry_state = _state_of(agent)
+    entry_copy = entry_state.Copy() if entry_state is not None else None
+    entry_tags = tuple(entry_state.active) if entry_state is not None else ()
+    entry_class = type(agent)
+
+    try:
+        state = _state_for(agent)
+        pending = [
+                member
+                for member in _form_of(tag)
+                if member not in state.active
+                ]
+
+        if pending:
+            if any(
+                    _declarations_of(member).preconditions
+                    for member in pending
+                    ):
+                _gate(
+                        agent,
+                        state,
+                        pending,
+                        inputs,
+                        )
+
+            for member in pending:
+                _apply_one(
+                        agent,
+                        member,
+                        inputs,
+                        )
+
+            _inspect(agent)
+    except (TagImprintError, TagPostconditionError):
+        raise
+    except BaseException:
+        _rollback(
+                agent,
+                entry_namespace,
+                entry_copy,
+                entry_tags,
+                entry_class,
+                )
+        raise
+
+    return agent
+
+
+def _rollback(
+        agent: object,
+        entry_namespace: dict[str, Any],
+        entry_copy: _State | None,
+        entry_tags: tuple[type, ...],
+        entry_class: type,
+        ) -> None:
+    current = _state_of(agent)
+
+    if current is not None:
+        for tag in current.active:
+            if tag not in entry_tags:
+                tag._topkit_field.Remove(agent)
+
+    _restore_namespace(
+            agent,
+            entry_namespace,
+            )
+    namespace = _namespace_of(agent)
+
+    if namespace is None:
+        return
+
+    if entry_copy is not None:
+        namespace[STATE] = entry_copy
+    else:
+        namespace.pop(STATE, None)
+
+    if type(agent) is not entry_class:
+        agent.__class__ = entry_class
+
+
+def _gate(
+        agent: object,
+        state: _State,
+        pending: list[type],
+        inputs: dict[str, Any],
+        ) -> None:
+    """Inspect the incoming materials once, against the Form as it will be.
+
+    Every pending Tag is laid over a scratch copy so that a Shape's
+    Precondition overrides (relaxes) its Base's, and so that declaration
+    errors and collisions surface before anything changes.
+    """
+
+    scratch = state.Copy()
+    names: list[str] = []
+
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+
+        for tag in pending:
+            declarations = _declarations_of(tag)
+
+            _install(
+                    scratch,
+                    tag,
+                    declarations,
+                    )
+
+            for name, _function in declarations.preconditions:
+                if name not in names:
+                    names.append(name)
+
+    state.composing += 1
+
+    try:
+        _evaluate(
+                (
+                    (name, scratch.preconditions[name])
+                    for name in names
+                    if name in scratch.preconditions
+                    ),
+                agent,
+                inputs,
+                TagPreconditionError,
+                "Precondition",
+                )
+    finally:
+        state.composing -= 1
+
+
+def _apply_one(
+        agent: object,
+        tag: type,
+        inputs: dict[str, Any],
+        ) -> None:
+    # The state is laid over in place: the call boundary (_apply) holds the
+    # entry copy that a Record failure rolls back to, and nothing reads the
+    # new Overlay before commit binds it on the Agent.
+    state = _state_for(agent)
+    declarations = _declarations_of(tag)
+    deleted_before = set(state.deleted)
+    state.composing += 1
+
+    try:
+        _install(
+                state,
+                tag,
+                declarations,
+                )
+
+        _materialize(
+                agent,
+                declarations,
+                deleted_before,
+                inputs,
+                )
+
+        _commit(
+                agent,
+                state,
+                deleted_before,
+                tag,
+                declarations,
+                )
+
+        try:
+            _imprint(
+                    agent,
+                    declarations,
+                    inputs,
+                    )
+        finally:
+            state.snapshots[tag] = _snapshot(
+                    agent,
+                    state,
+                    )
+    finally:
+        state.composing -= 1
+
+
+def _inspect(
+        agent: object,
+        ) -> None:
+    """Quality check of the finished product: every visible Postcondition."""
+
+    state = _state_of(agent)
+    state.composing += 1
+
+    try:
+        _evaluate(
+                state.postconditions.items(),
+                agent,
+                {},
+                TagPostconditionError,
+                "Postcondition",
+                )
+    finally:
+        state.composing -= 1
+
+
+def _commit(
+        agent: object,
+        state: _State,
+        deleted_before: set[str],
+        tag: type,
+        declarations: _Declarations,
+        ) -> None:
+    namespace = _namespace_of(agent)
+
+    for name in state.deleted - deleted_before:
+        namespace.pop(name, None)
+
+    state.active.append(tag)
+    state.ever.add(tag)
+
+    if declarations.secrets:
+        # A first secret turns every bound Action into a composing one.
+        _rebind_all(
+                agent,
+                state,
+                )
+    else:
+        for name, _function in declarations.actions:
+            if name in state.actions:
+                _bind_to(
+                        agent,
+                        state,
+                        name,
+                        )
+
+        for name, _operation, public in declarations.operations:
+            if public and name in state.actions:
+                _bind_to(
+                        agent,
+                        state,
+                        name,
+                        )
+
+    if _needs_new_type(
+            agent,
+            declarations,
+            ):
+        next_type = _runtime_type_for(state)
+    else:
+        next_type = type(agent)
+
+    if type(agent) is not next_type:
+        try:
+            agent.__class__ = next_type
+        except TypeError as error:
+            raise TagCompositionError(
+                    f"{type(agent).__name__} cannot be actualized in place"
+                    ) from error
+
+    tag._topkit_field.Add(agent)
+
+    if state.pinned is not None and declarations.published:
+        _publish_to_field(
+                state.pinned,
+                declarations.published,
+                )
+
+
+def _publish_to_field(
+        pinned: type,
+        names: frozenset[str],
+        ) -> None:
+    """A Pin's @Public members reach the pinned Tag's Field: every present
+    Agent receives them now as the Tag's own published Reports and
+    Operations; every future Agent through the Tag's declarations. The
+    whole Field is checked on copies first, so no Agent is touched unless
+    all can be."""
+
+    from .declarations import _scan_cache
+    from .overlay import _adapter
+
+    state = _state_of(pinned)
+    _scan_cache.pop(pinned, None)   # the Tag's declarations grew
+    agents = list(pinned[:])
+    plans: list[tuple[object, _State]] = []
+
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")   # the real pass warns once
+
+        for agent in agents:
+            candidate = _state_of(agent).Copy()
+            _publish_into(
+                    candidate,
+                    pinned,
+                    state,
+                    names,
+                    _adapter,
+                    )
+            plans.append(
+                    (
+                        agent,
+                        candidate,
+                        )
+                    )
+
+    for agent, candidate in plans:
+        agent_state = _state_of(agent)
+        _publish_into(
+                agent_state,
+                pinned,
+                state,
+                names,
+                _adapter,
+                )
+
+        for name in names:
+            if name in agent_state.actions:
+                _bind_to(
+                        agent,
+                        agent_state,
+                        name,
+                        )
+
+        next_type = _runtime_type_for(agent_state)
+
+        if type(agent) is not next_type:
+            agent.__class__ = next_type
+
+
+def _publish_into(
+        agent_state: _State,
+        pinned: type,
+        state: _State,
+        names: frozenset[str],
+        adapter: Any,
+        ) -> None:
+    from .overlay import _install_action
+
+    for name in names:
+        if name in state.records:
+            agent_state.reports[name] = (pinned, None)
+            agent_state.published.add(name)
+        elif name in state.actions:
+            _install_action(
+                    agent_state,
+                    pinned,
+                    name,
+                    adapter(pinned, name, state.actions[name]),
+                    )
+
+
+def _needs_new_type(
+        agent: object,
+        declarations: _Declarations,
+        ) -> bool:
+    """Only type-level facts change the runtime type: the first tagging,
+    deletions, secrets, published Reports, dunder Actions, a first Post."""
+
+    if not isinstance(agent, Tagged):
+        return True
+
+    return bool(
+            declarations.deletions
+            or declarations.secrets
+            or declarations.dunders
+            or declarations.postconditions
+            or any(public for _name, _value, public in declarations.reports)
+            )
+
+
+def _imprint(
+        agent: object,
+        declarations: _Declarations,
+        inputs: dict[str, Any],
+        ) -> None:
+    for name, imprint in declarations.imprints:
+        try:
+            imprint(
+                    agent,
+                    **_protocol_inputs(imprint, inputs, 1),
+                    )
+        except TagError:
+            raise
+        except Exception as error:
+            raise TagImprintError.Named(name)(
+                    f"Imprint {imprint.__qualname__} failed:"
+                    f" {type(error).__name__}: {error}"
+                    ) from error
+
+
+def _snapshot(
+        agent: object,
+        state: _State,
+        ) -> _Snapshot:
+    namespace = _namespace_of(agent)
+    records = {
+            name: namespace[name]
+            for name in state.records
+            if name in namespace
+            }
+
+    for name in state.records:
+        if name in state.secret_values:
+            records[name] = state.secret_values[name]
+
+    reports = {
+            name: (origin, getattr(origin, name))
+            for name, (origin, _report) in state.reports.items()
+            }
+
+    return _Snapshot(
+            actions=dict(state.actions),
+            records=records,
+            reports=reports,
+            operations=dict(state.operations),
+            deleted=frozenset(state.deleted),
+            secrets=frozenset(state.secrets),
+            )