usecaseapi 1.0.0__py3-none-any.whl

usecaseapi/__init__.py

@@ -0,0 +1,50 @@
+"""Public package exports for UseCaseAPI."""
+
+from __future__ import annotations
+
+from .api import Binding, Caller, CallRecord, UseCaseAPI
+from .contracts import Contract, UseCase, UseCaseRef, define_usecase
+from .docs import render_markdown, render_mermaid
+from .errors import (
+    ContractDefinitionError,
+    DuplicateUseCaseError,
+    InvalidHandlerError,
+    MissingBindingError,
+    UndeclaredUseCaseDependencyError,
+    UndeclaredUseCaseError,
+    UseCaseAPIError,
+    UseCaseError,
+)
+from .model import Model
+from .scaffold import ScaffoldOptions, ScaffoldResult, scaffold_usecase
+from .snapshot import ContractDiff, diff_snapshots, load_snapshot, snapshot_from_api, write_snapshot
+
+__all__ = [
+    "Binding",
+    "CallRecord",
+    "Caller",
+    "Contract",
+    "ContractDefinitionError",
+    "ContractDiff",
+    "DuplicateUseCaseError",
+    "InvalidHandlerError",
+    "MissingBindingError",
+    "Model",
+    "ScaffoldOptions",
+    "ScaffoldResult",
+    "UndeclaredUseCaseDependencyError",
+    "UndeclaredUseCaseError",
+    "UseCase",
+    "UseCaseAPI",
+    "UseCaseAPIError",
+    "UseCaseError",
+    "UseCaseRef",
+    "define_usecase",
+    "diff_snapshots",
+    "load_snapshot",
+    "render_markdown",
+    "render_mermaid",
+    "scaffold_usecase",
+    "snapshot_from_api",
+    "write_snapshot",
+]

usecaseapi/api.py

@@ -0,0 +1,289 @@
+"""Runtime registry and caller implementation for UseCaseAPI contracts."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+
+from collections.abc import Awaitable, Callable, Iterable, Sequence
+from dataclasses import dataclass, field
+from typing import Any, TypeVar, cast, get_type_hints
+
+from .contracts import InputT, OutputT, UseCase, UseCaseRef
+from .errors import (
+    DuplicateUseCaseError,
+    InvalidHandlerError,
+    MissingBindingError,
+    UndeclaredUseCaseDependencyError,
+    UndeclaredUseCaseError,
+    UseCaseError,
+)
+
+ContextT = TypeVar("ContextT")
+
+HandlerFactory = Callable[["Caller[Any]"], UseCase[Any, Any]]
+
+
+@dataclass(frozen=True, slots=True)
+class Binding[ContextT]:
+    """A runtime connection between a contract token and an implementation factory."""
+
+    ref: UseCaseRef[Any, Any]
+    factory: Callable[[Caller[ContextT]], UseCase[Any, Any]]
+    uses: frozenset[str] = field(default_factory=frozenset)
+    description: str | None = None
+    tags: tuple[str, ...] = field(default_factory=tuple)
+
+
+@dataclass(frozen=True, slots=True)
+class CallRecord:
+    """One edge observed during runtime calls."""
+
+    caller_key: str | None
+    callee_key: str
+
+
+class UseCaseAPI[ContextT]:
+    """Registry and contract runtime for same-process usecase calls.
+
+    This class is not a DI container. It keeps contract bindings and creates
+    ``Caller`` objects for contexts that are supplied by the host application.
+    """
+
+    def __init__(
+        self,
+        *,
+        strict_dependencies: bool = True,
+        strict_errors: bool = True,
+        validate_handlers: bool = True,
+    ) -> None:
+        """Create a registry with dependency, error, and handler validation options."""
+        self.strict_dependencies = strict_dependencies
+        self.strict_errors = strict_errors
+        self.validate_handlers = validate_handlers
+        self._contracts: dict[str, UseCaseRef[Any, Any]] = {}
+        self._bindings: dict[str, Binding[ContextT]] = {}
+        self._validated_handler_types: set[tuple[str, type[Any]]] = set()
+
+    def register(self, *refs: UseCaseRef[Any, Any]) -> UseCaseAPI[ContextT]:
+        """Register contracts without binding implementations yet."""
+        for ref in refs:
+            existing = self._contracts.get(ref.key)
+            if existing is not None and existing is not ref:
+                raise DuplicateUseCaseError(f"duplicate usecase contract {ref.key!r}")
+            self._contracts[ref.key] = ref
+        return self
+
+    def bind(
+        self,
+        ref: UseCaseRef[InputT, OutputT],
+        factory: Callable[[Caller[ContextT]], UseCase[InputT, OutputT]],
+        *,
+        uses: Iterable[UseCaseRef[Any, Any]] = (),
+        replace: bool = False,
+        description: str | None = None,
+        tags: Sequence[str] = (),
+    ) -> UseCaseAPI[ContextT]:
+        """Bind a contract token to an implementation factory.
+
+        ``factory`` receives the current ``Caller`` and returns a callable object
+        that structurally conforms to the contract Protocol.
+        """
+        self.register(ref)
+        if ref.key in self._bindings and not replace:
+            raise DuplicateUseCaseError(f"duplicate binding for {ref.key!r}")
+        use_keys = frozenset(use_ref.key for use_ref in uses)
+        for use_ref in uses:
+            self.register(use_ref)
+        self._bindings[ref.key] = Binding(
+            ref=ref,
+            factory=cast(Callable[[Caller[ContextT]], UseCase[Any, Any]], factory),
+            uses=use_keys,
+            description=description,
+            tags=tuple(tags),
+        )
+        return self
+
+    def caller(self, context: ContextT) -> Caller[ContextT]:
+        """Create a caller for a host-application context."""
+        return Caller(api=self, context=context, current_key=None, records=[])
+
+    def validate(self, *, require_handlers: bool = True) -> None:
+        """Validate registry-level consistency.
+
+        Handler signatures are validated lazily when a factory produces a handler,
+        because UseCaseAPI deliberately does not own construction lifecycles.
+        """
+        if require_handlers:
+            missing = sorted(set(self._contracts) - set(self._bindings))
+            if missing:
+                raise MissingBindingError("missing usecase bindings: " + ", ".join(missing))
+        for binding in self._bindings.values():
+            unknown_uses = sorted(binding.uses - set(self._contracts))
+            if unknown_uses:
+                raise MissingBindingError(
+                    f"binding {binding.ref.key!r} declares unknown uses: " + ", ".join(unknown_uses)
+                )
+
+    @property
+    def contracts(self) -> tuple[UseCaseRef[Any, Any], ...]:
+        """Registered contract references in insertion order."""
+        return tuple(self._contracts.values())
+
+    @property
+    def bindings(self) -> tuple[Binding[ContextT], ...]:
+        """Registered implementation bindings in insertion order."""
+        return tuple(self._bindings.values())
+
+    def _get_binding(self, ref: UseCaseRef[Any, Any]) -> Binding[ContextT]:
+        return self._get_binding_by_key(ref.key)
+
+    def _get_binding_by_key(self, key: str) -> Binding[ContextT]:
+        binding = self._bindings.get(key)
+        if binding is None:
+            raise MissingBindingError(f"missing binding for {key!r}")
+        return binding
+
+    def _validate_handler(self, ref: UseCaseRef[Any, Any], handler: UseCase[Any, Any]) -> None:
+        handler_type = type(handler)
+        cache_key = (ref.key, handler_type)
+        if cache_key in self._validated_handler_types:
+            return
+        target = _callable_target(handler)
+        if not inspect.iscoroutinefunction(target):
+            raise InvalidHandlerError(f"handler for {ref.key!r} must be async")
+
+        signature = inspect.signature(target)
+        positional_parameters = [
+            parameter
+            for parameter in signature.parameters.values()
+            if parameter.kind
+            in (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD)
+        ]
+        if len(positional_parameters) != 1:
+            raise InvalidHandlerError(
+                f"handler for {ref.key!r} must accept exactly one positional input"
+            )
+        parameter = positional_parameters[0]
+        hints = get_type_hints(target)
+        input_hint = hints.get(parameter.name, parameter.annotation)
+        output_hint = hints.get("return", signature.return_annotation)
+        if input_hint is inspect.Signature.empty:
+            raise InvalidHandlerError(f"handler for {ref.key!r} must annotate input")
+        if output_hint is inspect.Signature.empty:
+            raise InvalidHandlerError(f"handler for {ref.key!r} must annotate return")
+        if input_hint is not ref.contract.input:
+            raise InvalidHandlerError(
+                f"handler for {ref.key!r} input annotation must be "
+                f"{ref.contract.input.__name__}, got {input_hint!r}"
+            )
+        if output_hint is not ref.contract.output:
+            raise InvalidHandlerError(
+                f"handler for {ref.key!r} return annotation must be "
+                f"{ref.contract.output.__name__}, got {output_hint!r}"
+            )
+        self._validated_handler_types.add(cache_key)
+
+
+class Caller[ContextT]:
+    """Context-bound caller used to invoke usecase contracts."""
+
+    def __init__(
+        self,
+        *,
+        api: UseCaseAPI[ContextT],
+        context: ContextT,
+        current_key: str | None,
+        records: list[CallRecord],
+    ) -> None:
+        """Create a context-bound caller used by the registry internals."""
+        self._api = api
+        self.context = context
+        self._current_key = current_key
+        self._records = records
+
+    async def call(self, ref: UseCaseRef[InputT, OutputT], input: InputT, /) -> OutputT:
+        """Call a usecase by contract token."""
+        if self._current_key is not None and self._api.strict_dependencies:
+            parent = self._api._get_binding_by_key(self._current_key)
+            if ref.key not in parent.uses:
+                raise UndeclaredUseCaseDependencyError(
+                    caller_key=self._current_key,
+                    callee_key=ref.key,
+                )
+
+        binding = self._api._get_binding(ref)
+        self._records.append(CallRecord(caller_key=self._current_key, callee_key=ref.key))
+        child_caller = Caller(
+            api=self._api,
+            context=self.context,
+            current_key=ref.key,
+            records=self._records,
+        )
+        handler = binding.factory(child_caller)
+        if self._api.validate_handlers:
+            self._api._validate_handler(ref, handler)
+
+        try:
+            result = handler(input)
+            if not inspect.isawaitable(result):
+                raise InvalidHandlerError(f"handler for {ref.key!r} did not return an awaitable")
+            output = await result
+        except Exception as exc:
+            self._validate_exception(ref, exc)
+            raise
+
+        if not isinstance(output, ref.contract.output):
+            raise InvalidHandlerError(
+                f"handler for {ref.key!r} returned {type(output).__name__}, "
+                f"expected {ref.contract.output.__name__}"
+            )
+        return output
+
+    async def gather(self, *awaitables: Awaitable[Any]) -> tuple[Any, ...]:
+        """Run multiple usecase calls concurrently and preserve ExceptionGroup semantics."""
+        results: list[Any] = [None] * len(awaitables)
+
+        async def run_one(index: int, awaitable: Awaitable[Any]) -> None:
+            results[index] = await awaitable
+
+        async with asyncio.TaskGroup() as task_group:
+            for index, awaitable in enumerate(awaitables):
+                task_group.create_task(run_one(index, awaitable))
+        return tuple(results)
+
+    @property
+    def records(self) -> tuple[CallRecord, ...]:
+        """Runtime call records captured by this caller."""
+        return tuple(self._records)
+
+    def _validate_exception(self, ref: UseCaseRef[Any, Any], exc: BaseException) -> None:
+        if not self._api.strict_errors:
+            return
+        undeclared = _find_undeclared_usecase_error(exc, ref.contract.raises)
+        if undeclared is not None:
+            raise UndeclaredUseCaseError(usecase_key=ref.key, error=undeclared) from exc
+
+
+def _callable_target(handler: UseCase[Any, Any]) -> Callable[..., Any]:
+    if inspect.isfunction(handler) or inspect.ismethod(handler):
+        return cast(Callable[..., Any], handler)
+    if not callable(handler):
+        raise InvalidHandlerError(f"handler {handler!r} is not callable")
+    return cast(Callable[..., Any], handler.__call__)
+
+
+def _find_undeclared_usecase_error(
+    exc: BaseException,
+    declared: tuple[type[UseCaseError], ...],
+) -> UseCaseError | None:
+    if isinstance(exc, UseCaseError):
+        if declared and isinstance(exc, declared):
+            return None
+        return exc
+    if isinstance(exc, BaseExceptionGroup):
+        for nested in exc.exceptions:
+            found = _find_undeclared_usecase_error(nested, declared)
+            if found is not None:
+                return found
+    return None

usecaseapi/cli.py

@@ -0,0 +1,182 @@
+"""Command-line interface for inspecting and scaffolding UseCaseAPI projects."""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import json
+
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any, cast
+
+from .api import UseCaseAPI
+from .docs import render_markdown, render_mermaid
+from .scaffold import ScaffoldOptions, scaffold_usecase
+from .snapshot import diff_snapshots, load_snapshot, snapshot_from_api
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the command-line interface and return a process exit code."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    command = cast(str, args.command)
+    if command == "scaffold":
+        return _cmd_scaffold(args)
+    if command == "inspect":
+        return _cmd_inspect(args)
+    if command == "snapshot":
+        return _cmd_snapshot(args)
+    if command == "docs":
+        return _cmd_docs(args)
+    if command == "graph":
+        return _cmd_graph(args)
+    if command == "diff":
+        return _cmd_diff(args)
+    if command == "check":
+        return _cmd_check(args)
+    parser.print_help()
+    return 2
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="usecaseapi")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    scaffold = subparsers.add_parser("scaffold", help="create a versioned usecase skeleton")
+    scaffold.add_argument("name", help="contract name, e.g. orders.place_order")
+    version_group = scaffold.add_mutually_exclusive_group()
+    version_group.add_argument("--version", type=int, default=None, help="target major version")
+    version_group.add_argument(
+        "--next",
+        action="store_true",
+        help="create the next available major version",
+    )
+    scaffold.add_argument(
+        "--from-version",
+        type=int,
+        default=None,
+        help="copy an existing contract version and bump metadata",
+    )
+    scaffold.add_argument("--contracts-root", default="app/contracts")
+    scaffold.add_argument("--implementations-root", default="app/usecases")
+    scaffold.add_argument("--tests-root", default="tests")
+    scaffold.add_argument("--contracts-package", default="app.contracts")
+    scaffold.add_argument("--implementations-package", default="app.usecases")
+    scaffold.add_argument("--force", action="store_true")
+    scaffold.add_argument("--dry-run", action="store_true")
+    scaffold.add_argument("--no-implementation", action="store_true")
+    scaffold.add_argument("--no-tests", action="store_true")
+    scaffold.add_argument("--no-init", action="store_true")
+
+    for name in ("inspect", "snapshot", "docs", "graph", "check"):
+        sub = subparsers.add_parser(name, help=f"{name} a UseCaseAPI instance")
+        sub.add_argument("app", help="import path like 'myapp.composition:usecases'")
+        if name in {"snapshot", "docs", "graph"}:
+            sub.add_argument("--output", "-o", default=None)
+
+    diff = subparsers.add_parser("diff", help="compare two UseCaseAPI snapshots")
+    diff.add_argument("old")
+    diff.add_argument("new")
+    diff.add_argument("--json", action="store_true")
+
+    return parser
+
+
+def _cmd_scaffold(args: argparse.Namespace) -> int:
+    result = scaffold_usecase(
+        ScaffoldOptions(
+            name=cast(str, args.name),
+            version=None if cast(bool, args.next) else cast(int | None, args.version),
+            from_version=cast(int | None, args.from_version),
+            contracts_root=Path(cast(str, args.contracts_root)),
+            implementations_root=Path(cast(str, args.implementations_root)),
+            tests_root=Path(cast(str, args.tests_root)),
+            contracts_package=cast(str, args.contracts_package),
+            implementations_package=cast(str, args.implementations_package),
+            force=cast(bool, args.force),
+            dry_run=cast(bool, args.dry_run),
+            create_implementation=not cast(bool, args.no_implementation),
+            create_tests=not cast(bool, args.no_tests),
+            create_init=not cast(bool, args.no_init),
+        )
+    )
+    print(f"scaffolded version: v{result.version}")
+    for file_path in result.files:
+        print(f"created: {file_path}")
+    for file_path in result.skipped:
+        print(f"skipped: {file_path}")
+    return 0
+
+
+def _cmd_inspect(args: argparse.Namespace) -> int:
+    api = _load_api(cast(str, args.app))
+    print(json.dumps(snapshot_from_api(api), ensure_ascii=False, indent=2))
+    return 0
+
+
+def _cmd_snapshot(args: argparse.Namespace) -> int:
+    api = _load_api(cast(str, args.app))
+    payload = json.dumps(snapshot_from_api(api), ensure_ascii=False, indent=2) + "\n"
+    _write_or_print(payload, cast(str | None, args.output))
+    return 0
+
+
+def _cmd_docs(args: argparse.Namespace) -> int:
+    api = _load_api(cast(str, args.app))
+    _write_or_print(render_markdown(api), cast(str | None, args.output))
+    return 0
+
+
+def _cmd_graph(args: argparse.Namespace) -> int:
+    api = _load_api(cast(str, args.app))
+    _write_or_print(render_mermaid(api), cast(str | None, args.output))
+    return 0
+
+
+def _cmd_check(args: argparse.Namespace) -> int:
+    api = _load_api(cast(str, args.app))
+    api.validate(require_handlers=True)
+    print("UseCaseAPI check passed")
+    return 0
+
+
+def _cmd_diff(args: argparse.Namespace) -> int:
+    diff = diff_snapshots(load_snapshot(cast(str, args.old)), load_snapshot(cast(str, args.new)))
+    if cast(bool, args.json):
+        print(json.dumps(diff.to_dict(), ensure_ascii=False, indent=2))
+    else:
+        for label, items in (
+            ("Breaking", diff.breaking),
+            ("Warnings", diff.warnings),
+            ("Additions", diff.additions),
+        ):
+            print(label + ":")
+            if items:
+                for item in items:
+                    print(f"  - {item}")
+            else:
+                print("  - none")
+    return 1 if diff.has_breaking_changes else 0
+
+
+def _load_api(import_path: str) -> UseCaseAPI[Any]:
+    module_name, separator, attribute_name = import_path.partition(":")
+    if not separator or not module_name or not attribute_name:
+        raise ValueError("app import path must look like 'module:attribute'")
+    module = importlib.import_module(module_name)
+    value = getattr(module, attribute_name)
+    if not isinstance(value, UseCaseAPI):
+        raise TypeError(f"{import_path!r} is not a UseCaseAPI instance")
+    return value
+
+
+def _write_or_print(content: str, output: str | None) -> None:
+    if output is None:
+        print(content, end="")
+        return
+    Path(output).write_text(content)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

usecaseapi/contracts.py

@@ -0,0 +1,103 @@
+"""Contract metadata and typed usecase references."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol, TypeVar, runtime_checkable
+
+from .errors import ContractDefinitionError, UseCaseError
+from .model import Model
+
+InputT = TypeVar("InputT", bound=Model)
+OutputT = TypeVar("OutputT", bound=Model)
+UseCaseInputT = TypeVar("UseCaseInputT", bound=Model, contravariant=True)
+UseCaseOutputT = TypeVar("UseCaseOutputT", bound=Model, covariant=True)
+
+
+@runtime_checkable
+class UseCase(Protocol[UseCaseInputT, UseCaseOutputT]):
+    """Structural protocol for a same-process usecase implementation."""
+
+    async def __call__(self, input: UseCaseInputT, /) -> UseCaseOutputT:
+        """Run the usecase."""
+
+
+@dataclass(frozen=True, slots=True)
+class Contract[InputT: Model, OutputT: Model]:
+    """Runtime metadata for a Protocol-first usecase contract."""
+
+    name: str
+    version: int
+    input: type[InputT]
+    output: type[OutputT]
+    raises: tuple[type[UseCaseError], ...] = ()
+    known_errors: tuple[type[UseCaseError], ...] = ()
+    stable: bool = True
+    deprecated: bool = False
+    superseded_by: str | None = None
+    description: str | None = None
+    tags: tuple[str, ...] = field(default_factory=tuple)
+
+    def __post_init__(self) -> None:
+        """Validate contract metadata after dataclass initialization."""
+        if not self.name or not self.name.strip():
+            raise ContractDefinitionError("contract name must not be empty")
+        if self.version < 1:
+            raise ContractDefinitionError("contract version must be >= 1")
+        if not issubclass(self.input, Model):
+            raise ContractDefinitionError("contract input must inherit usecaseapi.Model")
+        if not issubclass(self.output, Model):
+            raise ContractDefinitionError("contract output must inherit usecaseapi.Model")
+        for error_type in (*self.raises, *self.known_errors):
+            if not issubclass(error_type, UseCaseError):
+                raise ContractDefinitionError(
+                    "contract errors must inherit usecaseapi.UseCaseError"
+                )
+        if self.raises:
+            for error_type in self.known_errors:
+                if not any(issubclass(error_type, declared) for declared in self.raises):
+                    raise ContractDefinitionError(
+                        f"known error {error_type.__qualname__} is not covered by raises"
+                    )
+
+    @property
+    def key(self) -> str:
+        """Stable contract key in ``name@vN`` form."""
+        return f"{self.name}@v{self.version}"
+
+
+@dataclass(frozen=True, slots=True)
+class UseCaseRef[InputT: Model, OutputT: Model]:
+    """Typed token used to call and bind a usecase contract."""
+
+    protocol: type[Any]
+    contract: Contract[InputT, OutputT]
+
+    @property
+    def key(self) -> str:
+        """Stable contract key in ``name@vN`` form."""
+        return self.contract.key
+
+    @property
+    def name(self) -> str:
+        """Contract name without the version suffix."""
+        return self.contract.name
+
+    @property
+    def version(self) -> int:
+        """Contract major version."""
+        return self.contract.version
+
+    def __repr__(self) -> str:
+        """Return a compact debug representation."""
+        return f"UseCaseRef({self.key})"
+
+
+def define_usecase[InputT: Model, OutputT: Model](
+    protocol: type[Any],
+    contract: Contract[InputT, OutputT],
+) -> UseCaseRef[InputT, OutputT]:
+    """Create a typed token for a usecase Protocol and its contract metadata."""
+    if protocol is object:
+        raise ContractDefinitionError("protocol must be a concrete Protocol class")
+    return UseCaseRef(protocol=protocol, contract=contract)