pi-durable-python 1.3.0__py3-none-any.whl

pi_durable/tasks.py

@@ -0,0 +1,89 @@
+"""Executable durable task definitions.
+
+The Session only needs the definition's initial checkpoint and persisted identity; the Harness
+later schedules the phase map. Keeping the token here, in the kernel layer, lets transactions
+create tasks without importing the harness.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any, Generic, TypeVar
+
+InputT = TypeVar("InputT")
+S = TypeVar("S")
+R = TypeVar("R")
+H = TypeVar("H")
+
+
+@dataclass(frozen=True, slots=True)
+class TaskDefinition(Generic[InputT, S, R, H]):
+    """Definition fields persisted and used when a task is created or recovered."""
+
+    name: str
+    version: int
+    initial: Callable[[InputT], S]
+    phases: Mapping[str, Any]
+    abort: Callable[..., Any]
+    migrate: Callable[..., Any] | None = None
+    hooks: H | None = None
+
+    def __getitem__(self, key: str) -> Any:
+        return getattr(self, key)
+
+
+@dataclass(frozen=True, slots=True)
+class Task(Generic[InputT, S, R, H]):
+    """Typed executable task token."""
+
+    definition: TaskDefinition[InputT, S, R, H]
+
+
+def _values(definition: Mapping[str, Any] | None, kwargs: Mapping[str, Any]) -> dict[str, Any]:
+    values = dict(definition or {})
+    values.update(kwargs)
+    return values
+
+
+def define_task(
+    definition: Mapping[str, Any] | None = None,
+    /,
+    **kwargs: Any,
+) -> Task[Any, Any, Any, Any]:
+    """Define an executable task; register it later with a Harness registry."""
+
+    values = _values(definition, kwargs)
+    name = values.get("name")
+    if not isinstance(name, str) or not name:
+        raise TypeError("Task name must be a non-empty string")
+    version = values.get("version")
+    if not isinstance(version, int) or isinstance(version, bool) or version < 1:
+        raise TypeError(f"Task {name} version must be a positive integer")
+    initial = values.get("initial")
+    if not callable(initial):
+        raise TypeError(f"Task {name} requires an initial() function")
+    phases = values.get("phases")
+    if not isinstance(phases, Mapping):
+        raise TypeError(f"Task {name} requires a phases mapping")
+    abort = values.get("abort")
+    if not callable(abort):
+        raise TypeError(f"Task {name} requires an abort() function")
+    migrate = values.get("migrate")
+    if migrate is not None and not callable(migrate):
+        raise TypeError(f"Task {name} migrate must be callable")
+    return Task(
+        TaskDefinition(
+            name=name,
+            version=version,
+            initial=initial,
+            phases=phases,
+            abort=abort,
+            migrate=migrate,
+            hooks=values.get("hooks"),
+        )
+    )
+
+
+
+__all__ = ["Task", "TaskDefinition", "define_task"]

pi_durable/testing/__init__.py

@@ -0,0 +1,41 @@
+"""Conformance and test helpers for storage backends.
+
+The suite is runner independent: :func:`create_storage_conformance` returns cases and
+:func:`register_storage_conformance` registers them with a Vitest/Jest-compatible runner.
+Benchmark helpers are deliberately excluded (see ``PARITY.md``).
+"""
+
+from .assertions import create_expect_assertions
+from .env_conformance import create_env_conformance
+from .runner import register_env_conformance, register_storage_conformance
+from .storage_conformance import create_storage_conformance
+from .types import (
+    EnvConformanceAssertions,
+    EnvConformanceCase,
+    EnvConformanceOptions,
+    EnvConformanceProvider,
+    ExpectLike,
+    StorageConformanceAssertions,
+    StorageConformanceCase,
+    StorageConformanceOptions,
+    StorageConformanceProvider,
+    StorageConformanceRunner,
+)
+
+__all__ = [
+    "EnvConformanceAssertions",
+    "EnvConformanceCase",
+    "EnvConformanceOptions",
+    "EnvConformanceProvider",
+    "ExpectLike",
+    "StorageConformanceAssertions",
+    "StorageConformanceCase",
+    "StorageConformanceOptions",
+    "StorageConformanceProvider",
+    "StorageConformanceRunner",
+    "create_env_conformance",
+    "create_expect_assertions",
+    "create_storage_conformance",
+    "register_env_conformance",
+    "register_storage_conformance",
+]

pi_durable/testing/assertions.py

@@ -0,0 +1,44 @@
+"""Adapter from a Vitest/Jest-style ``expect`` to the conformance assertion vocabulary.
+
+The adapter imports neither runner: it calls the snake_case matcher operations of a compatible
+``expect`` callable, so translated suites can supply pytest-backed assertions without changing
+the conformance cases.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable
+
+from .types import ExpectLike, StorageConformanceAssertions
+
+
+class _Assertions:
+    def __init__(self, expect: ExpectLike) -> None:
+        self._expect = expect
+
+    def ok(self, value: object, message: str | None = None) -> None:
+        self._expect(value, message).to_be_truthy()
+
+    def strict_equal(self, actual: object, expected: object) -> None:
+        self._expect(actual, None).to_be(expected)
+
+    def deep_equal(self, actual: object, expected: object) -> None:
+        self._expect(actual, None).to_equal(expected)
+
+    def partial_deep_equal(self, actual: object, expected: object) -> None:
+        self._expect(actual, None).to_match_object(expected)
+
+    def greater_than(self, actual: float, expected: float) -> None:
+        self._expect(actual, None).to_be_greater_than(expected)
+
+    async def rejects(self, operation: Awaitable[object], message_includes: str) -> None:
+        await self._expect(operation, None).rejects.to_throw(message_includes)
+
+
+def create_expect_assertions(expect: ExpectLike) -> StorageConformanceAssertions:
+    """Adapt a runner's ``expect`` to :class:`StorageConformanceAssertions` without importing it."""
+
+    return _Assertions(expect)
+
+
+__all__ = ["create_expect_assertions"]