tba-concrete-capability 0.4.0.dev2__py3-none-any.whl

tba_concrete_capability/__init__.py

@@ -0,0 +1,205 @@
+from __future__ import annotations
+
+import inspect
+import time
+from collections.abc import Mapping
+from dataclasses import asdict, replace
+
+from tba_bases_capability import CapabilityBase
+from tba_primitives_identity.clock import utc_now_iso
+from tba_primitives_identity.primitives import new_opaque_id, new_prefixed_id
+from tba_contracts_identity.capabilities import (
+    CapabilityCallContext,
+    CapabilityCallable,
+    CapabilityCallResult,
+    CapabilityContextError,
+    CapabilityDeadlineExceededError,
+    CapabilityDefinition,
+    CapabilityDelegationCycleError,
+    CapabilityOperation,
+    CapabilityOperationNotFoundError,
+    CapabilityOperationUnavailableError,
+    CapabilityState,
+    CapabilityStateProvider,
+    ICapability,
+)
+
+
+class Capability(CapabilityBase):
+    """Neutral generic capability with only explicitly supplied configuration."""
+
+    def __init__(
+        self,
+        definition: CapabilityDefinition,
+        /,
+        *,
+        operations: Mapping[str, CapabilityOperation],
+        attributes: Mapping[str, object] | None = None,
+        state: CapabilityState | CapabilityStateProvider | None = None,
+    ) -> None:
+        if not definition.capability_id.strip():
+            raise ValueError("capability_id is required")
+        if not definition.version.strip():
+            raise ValueError("capability version is required")
+        if not operations:
+            raise ValueError("at least one capability operation is required")
+        normalized_operations: dict[str, CapabilityOperation] = {}
+        for name, operation in operations.items():
+            if not name.strip():
+                raise ValueError("capability operation name is required")
+            if not isinstance(operation, CapabilityOperation):
+                raise TypeError(f"invalid capability operation: {name}")
+            if operation.target is not None and not callable(operation.target):
+                raise TypeError(f"capability operation target must be callable: {name}")
+            if operation.required and operation.target is None:
+                raise NotImplementedError(
+                    f"required capability operation is not implemented: {name}"
+                )
+            normalized_operations[name] = operation
+        self._capability_definition = definition
+        self._capability_operations = normalized_operations
+        self._capability_attributes = dict(attributes or {})
+        if state is None:
+            self._capability_state_provider: CapabilityStateProvider = CapabilityState
+        elif isinstance(state, CapabilityState):
+            self._capability_state_provider = lambda state=state: state
+        elif callable(state):
+            self._capability_state_provider = state
+        else:
+            raise TypeError("capability state must be a CapabilityState or state provider")
+
+    def definition(self) -> CapabilityDefinition:
+        return self._capability_definition
+
+    def operations(self) -> Mapping[str, CapabilityOperation]:
+        return dict(self._capability_operations)
+
+    def attributes(self) -> Mapping[str, object]:
+        return dict(self._capability_attributes)
+
+    def callables(self) -> Mapping[str, CapabilityCallable]:
+        return {
+            name: operation.target
+            for name, operation in self._capability_operations.items()
+            if operation.target is not None
+        }
+
+    def state(self) -> CapabilityState:
+        state = self._capability_state_provider()
+        if not isinstance(state, CapabilityState):
+            raise TypeError("capability state provider must return CapabilityState")
+        return state
+
+    def capability_report(self) -> dict[str, object]:
+        """Return the complete, operator-inspectable effective capability set."""
+        report: dict[str, object] = dict(asdict(self._capability_definition))
+        report["operations"] = tuple(self._capability_operations)
+        report["bound_operations"] = tuple(sorted(self.callables()))
+        report["delegated_operations"] = tuple(
+            sorted(
+                name
+                for name, operation in self._capability_operations.items()
+                if operation.target is not None and operation.delegated
+            )
+        )
+        report["optional_operations"] = tuple(
+            sorted(
+                name
+                for name, operation in self._capability_operations.items()
+                if not operation.required
+            )
+        )
+        report["unavailable_optional_operations"] = tuple(
+            sorted(
+                name
+                for name, operation in self._capability_operations.items()
+                if not operation.required and operation.target is None
+            )
+        )
+        report["state"] = asdict(self.state())
+        return report
+
+    async def call(
+        self,
+        operation: str,
+        *args: object,
+        context: CapabilityCallContext | None = None,
+        **kwargs: object,
+    ) -> CapabilityCallResult:
+        try:
+            operation_definition = self._capability_operations[operation]
+        except KeyError as exc:
+            raise CapabilityOperationNotFoundError(
+                f"unknown capability operation: {operation}"
+            ) from exc
+        target = operation_definition.target
+        if target is None:
+            raise CapabilityOperationUnavailableError(
+                f"unbound optional capability operation: {operation}"
+            )
+        active = context or CapabilityCallContext(call_id=new_opaque_id())
+        capability_id = self._capability_definition.capability_id
+        if active.capability_id not in {None, capability_id}:
+            raise CapabilityContextError(
+                "call context capability_id does not match target capability"
+            )
+        if active.operation not in {None, operation}:
+            raise CapabilityContextError(
+                "call context operation does not match target operation"
+            )
+        active = replace(
+            active,
+            capability_id=capability_id,
+            operation=operation,
+        )
+        if active.deadline is not None and time.time() > active.deadline:
+            raise CapabilityDeadlineExceededError(
+                "capability call deadline exceeded"
+            )
+        value = target(*args, **kwargs)
+        if inspect.isawaitable(value):
+            value = await value
+        return CapabilityCallResult(
+            value=value,
+            capability_id=self._capability_definition.capability_id,
+            operation=operation,
+            call_id=active.call_id,
+            delegated=operation_definition.delegated,
+            context=active,
+        )
+
+    async def subcall(
+        self,
+        capability: ICapability,
+        operation: str,
+        *args: object,
+        context: CapabilityCallContext,
+        authority: tuple[str, ...] | None = None,
+        **kwargs: object,
+    ) -> CapabilityCallResult:
+        target_capability_id = capability.definition().capability_id
+        delegation_chain = context.delegation_chain + (
+            self._capability_definition.capability_id,
+        )
+        if target_capability_id in delegation_chain:
+            raise CapabilityDelegationCycleError(
+                "capability delegation cycle detected"
+            )
+        child_authority = context.authority if authority is None else authority
+        if not set(child_authority).issubset(context.authority):
+            raise CapabilityContextError(
+                "delegated authority must narrow or preserve parent authority"
+            )
+        child = replace(
+            context,
+            parent_call_id=context.call_id,
+            call_id=new_opaque_id(),
+            capability_id=target_capability_id,
+            operation=operation,
+            delegation_chain=delegation_chain,
+            authority=tuple(child_authority),
+        )
+        return await capability.call(operation, *args, context=child, **kwargs)
+
+
+__all__ = ["Capability", "new_prefixed_id", "utc_now_iso"]

tba_concrete_capability/py.typed

@@ -0,0 +1 @@
+

tba_concrete_capability-0.4.0.dev2.dist-info/METADATA

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: tba-concrete-capability
+Version: 0.4.0.dev2
+Summary: Neutral generic capability implementation for TBA identity.
+License-Expression: Apache-2.0
+Requires-Python: >=3.10,<3.15
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: tba-bases-capability (==0.4.0.dev2)
+Requires-Dist: tba-contracts-identity (==0.4.0.dev2)
+Requires-Dist: tba-primitives-identity (==0.4.0.dev2)
+Description-Content-Type: text/markdown
+
+# tba-concrete-capability
+
+Layer-10 neutral `Capability`. Authors provide a `CapabilityDefinition` and one
+mapping of names to `CapabilityOperation` objects. Required operations must have
+callable targets at construction. Optional operations may be present without a
+target and are reported as unavailable. State is supplied as a fixed
+`CapabilityState` or a live state provider.
+
+The package has no implicit providers, persistence, policies, retries, timeouts,
+namespaces, or environment-derived settings.
+

tba_concrete_capability-0.4.0.dev2.dist-info/RECORD

@@ -0,0 +1,5 @@
+tba_concrete_capability/__init__.py,sha256=83wZXpKStQM6pieqfD_ZYKStgWUPzwVFvmhUKTBN9kU,8091
+tba_concrete_capability/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+tba_concrete_capability-0.4.0.dev2.dist-info/METADATA,sha256=yWixd6wipc153Nab3olUGeUsmhKGZ_dyFErno218i2Y,1212
+tba_concrete_capability-0.4.0.dev2.dist-info/WHEEL,sha256=L-WvLdSBvJWHXv5zrQxDvNRnIgoBzLUpcbuiw19KCuQ,88
+tba_concrete_capability-0.4.0.dev2.dist-info/RECORD,,

tba_concrete_capability-0.4.0.dev2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.5.0
+Root-Is-Purelib: true
+Tag: py3-none-any