usecaseapi 1.0.0__py3-none-any.whl

usecaseapi/docs.py

@@ -0,0 +1,88 @@
+"""Markdown and Mermaid renderers for registered usecase contracts."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .api import UseCaseAPI
+from .contracts import UseCaseRef
+
+
+def render_markdown(api: UseCaseAPI[Any]) -> str:
+    """Render registered usecases as human-readable Markdown."""
+    bindings = {binding.ref.key: binding for binding in api.bindings}
+    lines: list[str] = ["# UseCaseAPI Contracts", ""]
+    for ref in sorted(api.contracts, key=lambda item: item.key):
+        contract = ref.contract
+        lines.extend(
+            [
+                f"## {contract.name} v{contract.version}",
+                "",
+                f"Key: `{contract.key}`",
+                f"Protocol: `{ref.protocol.__module__}.{ref.protocol.__qualname__}`",
+                f"Input: `{contract.input.__module__}.{contract.input.__qualname__}`",
+                f"Output: `{contract.output.__module__}.{contract.output.__qualname__}`",
+                f"Stable: `{contract.stable}`",
+                f"Deprecated: `{contract.deprecated}`",
+            ]
+        )
+        if contract.superseded_by:
+            lines.append(f"Superseded by: `{contract.superseded_by}`")
+        if contract.description:
+            lines.extend(["", contract.description])
+        lines.extend(["", "### Raises", ""])
+        if contract.raises:
+            for error_type in contract.raises:
+                lines.append(
+                    f"- `{error_type.__module__}.{error_type.__qualname__}` "
+                    f"(`{getattr(error_type, 'code', '')}`)"
+                )
+        else:
+            lines.append("- None declared")
+        if contract.known_errors:
+            lines.extend(["", "### Known leaf errors", ""])
+            for error_type in contract.known_errors:
+                lines.append(
+                    f"- `{error_type.__module__}.{error_type.__qualname__}` "
+                    f"(`{getattr(error_type, 'code', '')}`)"
+                )
+        lines.extend(["", "### Declared uses", ""])
+        binding = bindings.get(ref.key)
+        if binding is not None and binding.uses:
+            for use_key in sorted(binding.uses):
+                lines.append(f"- `{use_key}`")
+        else:
+            lines.append("- None")
+        lines.extend(["", "### Input fields", ""])
+        _append_model_fields(lines, ref, kind="input")
+        lines.extend(["", "### Output fields", ""])
+        _append_model_fields(lines, ref, kind="output")
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def render_mermaid(api: UseCaseAPI[Any]) -> str:
+    """Render declared usecase dependencies as a Mermaid graph."""
+    lines = ["flowchart TD"]
+    for ref in sorted(api.contracts, key=lambda item: item.key):
+        node = _node_id(ref.key)
+        lines.append(f'  {node}["{ref.key}"]')
+    for binding in sorted(api.bindings, key=lambda item: item.ref.key):
+        source = _node_id(binding.ref.key)
+        for use_key in sorted(binding.uses):
+            lines.append(f"  {source} --> {_node_id(use_key)}")
+    return "\n".join(lines) + "\n"
+
+
+def _append_model_fields(lines: list[str], ref: UseCaseRef[Any, Any], *, kind: str) -> None:
+    model_type = ref.contract.input if kind == "input" else ref.contract.output
+    if not model_type.model_fields:
+        lines.append("- No fields")
+        return
+    for name, field in model_type.model_fields.items():
+        annotation = field.annotation
+        lines.append(f"- `{name}`: `{annotation!r}`")
+
+
+def _node_id(key: str) -> str:
+    return "uc_" + "".join(character if character.isalnum() else "_" for character in key)

usecaseapi/errors.py

@@ -0,0 +1,75 @@
+"""Framework and domain error classes used by UseCaseAPI."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import Any, ClassVar
+
+
+class UseCaseAPIError(Exception):
+    """Base class for framework-level errors raised by UseCaseAPI."""
+
+
+class ContractDefinitionError(UseCaseAPIError):
+    """Raised when a contract definition is invalid."""
+
+
+class DuplicateUseCaseError(UseCaseAPIError):
+    """Raised when the same usecase key is registered twice in an invalid way."""
+
+
+class MissingBindingError(UseCaseAPIError):
+    """Raised when a usecase is called without a registered implementation binding."""
+
+
+class InvalidHandlerError(UseCaseAPIError):
+    """Raised when a bound handler does not match its contract."""
+
+
+class UndeclaredUseCaseDependencyError(UseCaseAPIError):
+    """Raised when a usecase calls another usecase that was not declared in ``uses``."""
+
+    def __init__(self, *, caller_key: str, callee_key: str) -> None:
+        """Create an undeclared dependency error for a caller and callee pair."""
+        self.caller_key = caller_key
+        self.callee_key = callee_key
+        super().__init__(f"{caller_key!r} attempted to call undeclared dependency {callee_key!r}")
+
+
+class UndeclaredUseCaseError(UseCaseAPIError):
+    """Raised when a handler leaks a domain error outside its declared raises contract."""
+
+    def __init__(self, *, usecase_key: str, error: UseCaseError) -> None:
+        """Create an undeclared domain error wrapper."""
+        self.usecase_key = usecase_key
+        self.error = error
+        super().__init__(
+            f"{usecase_key!r} raised undeclared usecase error "
+            f"{type(error).__module__}.{type(error).__qualname__}"
+        )
+
+
+class UseCaseError(Exception):
+    """Base class for domain errors that are part of a usecase contract.
+
+    UseCaseAPI deliberately models domain failures as real Python exceptions.
+    This preserves normal exception hierarchy behavior, stack traces, ``except`` /
+    ``except*`` handling, and ExceptionGroup semantics.
+    """
+
+    code: ClassVar[str] = "usecase.error"
+
+    @property
+    def details(self) -> Mapping[str, Any]:
+        """Public attributes attached to this domain exception."""
+        return MappingProxyType(dict(self.__dict__))
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-friendly representation useful for docs, logs, or catalogs."""
+        return {
+            "type": f"{type(self).__module__}.{type(self).__qualname__}",
+            "code": self.code,
+            "message": str(self),
+            "details": dict(self.details),
+        }

usecaseapi/model.py

@@ -0,0 +1,15 @@
+"""Pydantic model base class exported by UseCaseAPI."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class Model(BaseModel):
+    """Base model for UseCaseAPI input and output objects.
+
+    The default configuration is intentionally strict and immutable-ish:
+    unknown fields are rejected and model instances are frozen.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)

usecaseapi/scaffold.py

@@ -0,0 +1,298 @@
+"""Scaffold versioned usecase contracts, implementations, and tests."""
+
+from __future__ import annotations
+
+import re
+
+from dataclasses import dataclass
+from pathlib import Path
+
+_USECASE_NAME = re.compile(r"^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$")
+_VERSION_FILE = re.compile(r"^v([1-9][0-9]*)\.py$")
+
+
+@dataclass(frozen=True, slots=True)
+class ScaffoldResult:
+    """Files planned or created by the scaffold command."""
+
+    files: tuple[Path, ...]
+    skipped: tuple[Path, ...] = ()
+    version: int = 1
+
+
+@dataclass(frozen=True, slots=True)
+class ScaffoldOptions:
+    """Options for creating a versioned usecase skeleton.
+
+    ``version=None`` means "create the next available major version". If
+    ``from_version`` is set and ``version`` is omitted, the target version is
+    ``from_version + 1`` and the previous contract is copied forward with the
+    contract metadata updated.
+    """
+
+    name: str
+    version: int | None = None
+    from_version: int | None = None
+    contracts_root: Path = Path("app/contracts")
+    implementations_root: Path = Path("app/usecases")
+    tests_root: Path = Path("tests")
+    contracts_package: str = "app.contracts"
+    implementations_package: str = "app.usecases"
+    force: bool = False
+    dry_run: bool = False
+    create_implementation: bool = True
+    create_tests: bool = True
+    create_init: bool = True
+
+
+def scaffold_usecase(options: ScaffoldOptions) -> ScaffoldResult:
+    """Create contract, implementation, and optional test files for one usecase."""
+    _validate_options(options)
+    parts = options.name.split(".")
+    domain_parts = parts[:-1]
+    usecase_name = parts[-1]
+    version = _resolve_version(options, domain_parts=domain_parts, usecase_name=usecase_name)
+    if options.from_version is not None and options.from_version >= version:
+        raise ValueError("from_version must be lower than target version")
+
+    class_name = _camel(usecase_name)
+    constant_name = usecase_name.upper()
+
+    contract_dir = options.contracts_root / Path(*domain_parts) / usecase_name
+    contract_file = contract_dir / f"v{version}.py"
+    implementation_file = options.implementations_root / Path(*domain_parts) / f"{usecase_name}.py"
+    test_file = options.tests_root / f"test_{'_'.join(parts)}_v{version}.py"
+
+    contract_module = ".".join(
+        [options.contracts_package, *domain_parts, usecase_name, f"v{version}"]
+    )
+    implementation_module = ".".join([options.implementations_package, *domain_parts, usecase_name])
+
+    if options.from_version is None:
+        contract_content = _contract_template(
+            name=options.name,
+            version=version,
+            class_name=class_name,
+            constant_name=constant_name,
+        )
+    else:
+        previous_contract_file = contract_dir / f"v{options.from_version}.py"
+        contract_content = _copy_contract_template(
+            previous_contract_file,
+            from_version=options.from_version,
+            target_version=version,
+        )
+
+    created: list[Path] = []
+    skipped: list[Path] = []
+
+    _write_file(contract_file, contract_content, force=options.force, dry_run=options.dry_run)
+    created.append(contract_file)
+
+    if options.create_implementation:
+        implementation_content = _implementation_template(
+            contract_module=contract_module,
+            class_name=class_name,
+        )
+        if implementation_file.exists() and not options.force:
+            skipped.append(implementation_file)
+        else:
+            _write_file(
+                implementation_file,
+                implementation_content,
+                force=options.force,
+                dry_run=options.dry_run,
+            )
+            created.append(implementation_file)
+
+    if options.create_tests:
+        _write_file(
+            test_file,
+            _test_template(
+                contract_module=contract_module,
+                implementation_module=implementation_module,
+                class_name=class_name,
+                constant_name=constant_name,
+                name=options.name,
+                version=version,
+            ),
+            force=options.force,
+            dry_run=options.dry_run,
+        )
+        created.append(test_file)
+
+    if options.create_init and not options.dry_run:
+        _ensure_init_files(contract_file.parent, stop_at=options.contracts_root.parent)
+        if options.create_implementation:
+            _ensure_init_files(
+                implementation_file.parent,
+                stop_at=options.implementations_root.parent,
+            )
+
+    return ScaffoldResult(files=tuple(created), skipped=tuple(skipped), version=version)
+
+
+def _validate_options(options: ScaffoldOptions) -> None:
+    if options.version is not None and options.version < 1:
+        raise ValueError("version must be >= 1")
+    if options.from_version is not None and options.from_version < 1:
+        raise ValueError("from_version must be >= 1")
+    if _USECASE_NAME.fullmatch(options.name) is None:
+        raise ValueError("usecase name must look like 'domain.use_case'")
+
+
+def _resolve_version(
+    options: ScaffoldOptions,
+    *,
+    domain_parts: list[str],
+    usecase_name: str,
+) -> int:
+    if options.version is not None:
+        return options.version
+    if options.from_version is not None:
+        return options.from_version + 1
+
+    contract_dir = options.contracts_root / Path(*domain_parts) / usecase_name
+    versions: list[int] = []
+    if contract_dir.exists():
+        for child in contract_dir.iterdir():
+            match = _VERSION_FILE.fullmatch(child.name)
+            if match is not None:
+                versions.append(int(match.group(1)))
+    if not versions:
+        return 1
+    return max(versions) + 1
+
+
+def _write_file(path: Path, content: str, *, force: bool, dry_run: bool) -> None:
+    if path.exists() and not force:
+        raise FileExistsError(f"{path} already exists; pass force=True to overwrite")
+    if dry_run:
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content)
+
+
+def _copy_contract_template(
+    previous_contract_file: Path,
+    *,
+    from_version: int,
+    target_version: int,
+) -> str:
+    if not previous_contract_file.exists():
+        raise FileNotFoundError(f"previous contract file does not exist: {previous_contract_file}")
+
+    content = previous_contract_file.read_text()
+    content, count = re.subn(
+        rf"(\bversion\s*=\s*){from_version}\b",
+        rf"\g<1>{target_version}",
+        content,
+    )
+    if count == 0:
+        raise ValueError(
+            f"could not find version={from_version} in {previous_contract_file}; "
+            "pass --version with a fresh scaffold instead"
+        )
+    content = content.replace(f" v{from_version}", f" v{target_version}")
+    content = content.replace(f"@v{from_version}", f"@v{target_version}")
+    return content
+
+
+def _ensure_init_files(directory: Path, *, stop_at: Path) -> None:
+    current = directory
+    while True:
+        init_file = current / "__init__.py"
+        if not init_file.exists():
+            init_file.write_text("")
+        if current == stop_at or current.parent == current:
+            break
+        current = current.parent
+
+
+def _camel(value: str) -> str:
+    return "".join(part.capitalize() for part in value.split("_"))
+
+
+def _contract_template(*, name: str, version: int, class_name: str, constant_name: str) -> str:
+    error_name = f"{class_name}Error"
+    return f'''from __future__ import annotations
+
+from typing import ClassVar, Protocol
+
+from usecaseapi import Contract, Model, UseCase, UseCaseError, UseCaseRef, define_usecase
+
+
+class Input(Model):
+    """Input for {name} v{version}."""
+
+
+class Output(Model):
+    """Output for {name} v{version}."""
+
+
+class {error_name}(UseCaseError):
+    """Base domain error for {name} v{version}."""
+
+    code: ClassVar[str] = "{name}"
+
+
+class {class_name}(UseCase[Input, Output], Protocol):
+    """Contract Protocol for {name} v{version}."""
+
+    async def __call__(self, input: Input, /) -> Output:
+        ...
+
+
+{constant_name}: UseCaseRef[Input, Output] = define_usecase(
+    {class_name},
+    Contract(
+        name="{name}",
+        version={version},
+        input=Input,
+        output=Output,
+        raises=({error_name},),
+        known_errors=(),
+    ),
+)
+'''
+
+
+def _implementation_template(*, contract_module: str, class_name: str) -> str:
+    return f"""from __future__ import annotations
+
+from {contract_module} import Input, Output, {class_name}
+
+
+class {class_name}Impl:
+    async def __call__(self, input: Input, /) -> Output:
+        raise NotImplementedError("Implement {class_name}Impl.__call__")
+
+
+_impl: {class_name} = {class_name}Impl()
+"""
+
+
+def _test_template(
+    *,
+    contract_module: str,
+    implementation_module: str,
+    class_name: str,
+    constant_name: str,
+    name: str,
+    version: int,
+) -> str:
+    return f'''from __future__ import annotations
+
+from {contract_module} import {class_name}, {constant_name}
+from {implementation_module} import {class_name}Impl
+
+
+def test_{constant_name.lower()}_contract_metadata() -> None:
+    assert {constant_name}.contract.name == "{name}"
+    assert {constant_name}.contract.version == {version}
+
+
+def test_{constant_name.lower()}_implementation_matches_protocol() -> None:
+    _impl: {class_name} = {class_name}Impl()
+    assert _impl is not None
+'''

usecaseapi/snapshot.py

@@ -0,0 +1,173 @@
+"""Snapshot serialization and diffing for UseCaseAPI contract catalogs."""
+
+from __future__ import annotations
+
+import json
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, cast
+
+from .api import UseCaseAPI
+from .contracts import UseCaseRef
+from .errors import UseCaseError
+
+
+def exception_to_dict(error_type: type[UseCaseError]) -> dict[str, Any]:
+    """Serialize exception class metadata for catalogs and snapshots."""
+    parents: list[str] = []
+    for parent in error_type.__mro__[1:]:
+        if parent is Exception or parent is BaseException or parent is object:
+            break
+        parents.append(f"{parent.__module__}.{parent.__qualname__}")
+    return {
+        "type": f"{error_type.__module__}.{error_type.__qualname__}",
+        "code": getattr(error_type, "code", ""),
+        "parents": parents,
+    }
+
+
+def ref_to_dict(ref: UseCaseRef[Any, Any], *, uses: tuple[str, ...] = ()) -> dict[str, Any]:
+    """Serialize a usecase reference and contract metadata."""
+    contract = ref.contract
+    return {
+        "key": contract.key,
+        "name": contract.name,
+        "version": contract.version,
+        "protocol": f"{ref.protocol.__module__}.{ref.protocol.__qualname__}",
+        "input": {
+            "type": f"{contract.input.__module__}.{contract.input.__qualname__}",
+            "schema": contract.input.model_json_schema(),
+        },
+        "output": {
+            "type": f"{contract.output.__module__}.{contract.output.__qualname__}",
+            "schema": contract.output.model_json_schema(),
+        },
+        "raises": [exception_to_dict(error_type) for error_type in contract.raises],
+        "known_errors": [exception_to_dict(error_type) for error_type in contract.known_errors],
+        "stable": contract.stable,
+        "deprecated": contract.deprecated,
+        "superseded_by": contract.superseded_by,
+        "description": contract.description,
+        "tags": list(contract.tags),
+        "uses": list(uses),
+    }
+
+
+def snapshot_from_api(api: UseCaseAPI[Any]) -> dict[str, Any]:
+    """Build a JSON-serializable snapshot from a UseCaseAPI instance."""
+    uses_by_key = {binding.ref.key: tuple(sorted(binding.uses)) for binding in api.bindings}
+    return {
+        "schema_version": 1,
+        "usecases": [
+            ref_to_dict(ref, uses=uses_by_key.get(ref.key, ()))
+            for ref in sorted(api.contracts, key=lambda item: item.key)
+        ],
+    }
+
+
+def write_snapshot(api: UseCaseAPI[Any], path: str | Path) -> None:
+    """Write a stable JSON snapshot to disk."""
+    payload = snapshot_from_api(api)
+    Path(path).write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n")
+
+
+def load_snapshot(path: str | Path) -> dict[str, Any]:
+    """Load a snapshot from disk."""
+    payload = json.loads(Path(path).read_text())
+    if not isinstance(payload, dict):
+        raise ValueError("snapshot must be a JSON object")
+    return cast(dict[str, Any], payload)
+
+
+@dataclass(frozen=True, slots=True)
+class ContractDiff:
+    """Result of comparing two snapshots."""
+
+    breaking: tuple[str, ...]
+    warnings: tuple[str, ...]
+    additions: tuple[str, ...]
+
+    @property
+    def has_breaking_changes(self) -> bool:
+        """Whether the diff contains at least one breaking change."""
+        return bool(self.breaking)
+
+    def to_dict(self) -> dict[str, list[str]]:
+        """Return a JSON-friendly diff payload."""
+        return {
+            "breaking": list(self.breaking),
+            "warnings": list(self.warnings),
+            "additions": list(self.additions),
+        }
+
+
+def diff_snapshots(old: Mapping[str, Any], new: Mapping[str, Any]) -> ContractDiff:
+    """Diff snapshots with conservative breaking-change detection."""
+    old_cases = _index_usecases(old)
+    new_cases = _index_usecases(new)
+    breaking: list[str] = []
+    warnings: list[str] = []
+    additions: list[str] = []
+
+    for key in sorted(set(old_cases) - set(new_cases)):
+        breaking.append(f"removed usecase {key}")
+    for key in sorted(set(new_cases) - set(old_cases)):
+        additions.append(f"added usecase {key}")
+
+    for key in sorted(set(old_cases) & set(new_cases)):
+        old_case = old_cases[key]
+        new_case = new_cases[key]
+        if old_case.get("input") != new_case.get("input"):
+            breaking.append(f"changed input schema for {key}")
+        if old_case.get("output") != new_case.get("output"):
+            breaking.append(f"changed output schema for {key}")
+        old_raises = _error_codes(old_case.get("raises"))
+        new_raises = _error_codes(new_case.get("raises"))
+        removed_raises = sorted(old_raises - new_raises)
+        if removed_raises:
+            breaking.append(f"removed declared errors for {key}: {', '.join(removed_raises)}")
+        old_uses = set(_string_list(old_case.get("uses")))
+        new_uses = set(_string_list(new_case.get("uses")))
+        removed_uses = sorted(old_uses - new_uses)
+        if removed_uses:
+            warnings.append(f"removed declared uses for {key}: {', '.join(removed_uses)}")
+        if old_case.get("deprecated") is False and new_case.get("deprecated") is True:
+            warnings.append(f"deprecated usecase {key}")
+    return ContractDiff(
+        breaking=tuple(breaking),
+        warnings=tuple(warnings),
+        additions=tuple(additions),
+    )
+
+
+def _index_usecases(snapshot: Mapping[str, Any]) -> dict[str, Mapping[str, Any]]:
+    usecases = snapshot.get("usecases", [])
+    if not isinstance(usecases, list):
+        raise ValueError("snapshot.usecases must be a list")
+    indexed: dict[str, Mapping[str, Any]] = {}
+    for item in usecases:
+        if not isinstance(item, dict):
+            raise ValueError("snapshot usecase must be an object")
+        key = item.get("key")
+        if not isinstance(key, str):
+            raise ValueError("snapshot usecase key must be a string")
+        indexed[key] = item
+    return indexed
+
+
+def _error_codes(value: object) -> set[str]:
+    if not isinstance(value, list):
+        return set()
+    codes: set[str] = set()
+    for item in value:
+        if isinstance(item, dict) and isinstance(item.get("code"), str):
+            codes.add(cast(str, item["code"]))
+    return codes
+
+
+def _string_list(value: object) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    return [item for item in value if isinstance(item, str)]