python-durable 0.1.0__py3-none-any.whl

durable/__init__.py

@@ -0,0 +1,51 @@
+"""
+durable — lightweight workflow durability for Python.
+
+Make any async workflow resumable after crashes with just a decorator.
+Backed by SQLite out of the box; swap in any Store subclass for production.
+
+Quick start:
+
+    from durable import Workflow
+    from durable.backoff import exponential
+
+    wf = Workflow("my-app")
+
+    @wf.task(retries=3, backoff=exponential(base=2, max=60))
+    async def fetch_data(url: str) -> dict:
+        async with httpx.AsyncClient() as client:
+            return (await client.get(url)).json()
+
+    @wf.task
+    async def save_result(data: dict) -> None:
+        await db.insert(data)
+
+    @wf.workflow(id="pipeline-{source}")
+    async def run_pipeline(source: str) -> None:
+        data = await fetch_data(f"https://api.example.com/{source}")
+        await save_result(data)
+
+    # First call: runs all steps and checkpoints each one.
+    # If it crashes and you call it again with the same args,
+    # completed steps are replayed from SQLite instantly.
+    await run_pipeline(source="users")
+"""
+
+from .backoff import BackoffStrategy, constant, exponential, linear
+from .context import RunContext
+from .store import InMemoryStore, SQLiteStore, Store
+from .workflow import Workflow
+
+__all__ = [
+    "Workflow",
+    "Store",
+    "SQLiteStore",
+    "InMemoryStore",
+    "RunContext",
+    "BackoffStrategy",
+    "exponential",
+    "constant",
+    "linear",
+]
+
+__version__ = "0.1.0"

durable/backoff.py

@@ -0,0 +1,40 @@
+"""
+Backoff strategies for task retries.
+
+Usage:
+    exponential(base=2, max=60)   → 2s, 4s, 8s, 16s... capped at 60s
+    constant(5)                   → always 5s
+    linear(start=2, step=3)       → 2s, 5s, 8s, 11s...
+"""
+
+from typing import Callable
+
+# A strategy takes the attempt number (0-indexed) and returns seconds to wait.
+BackoffStrategy = Callable[[int], float]
+
+
+def exponential(base: float = 2.0, max: float = 60.0) -> BackoffStrategy:
+    """Exponential backoff: base^attempt, capped at max seconds."""
+
+    def strategy(attempt: int) -> float:
+        return min(base**attempt, max)
+
+    return strategy
+
+
+def constant(seconds: float) -> BackoffStrategy:
+    """Always wait the same number of seconds."""
+
+    def strategy(attempt: int) -> float:
+        return seconds
+
+    return strategy
+
+
+def linear(start: float = 1.0, step: float = 1.0) -> BackoffStrategy:
+    """Linearly increasing wait: start, start+step, start+2*step..."""
+
+    def strategy(attempt: int) -> float:
+        return start + step * attempt
+
+    return strategy

durable/context.py

@@ -0,0 +1,39 @@
+"""
+RunContext holds the state of a single workflow execution.
+
+It's stored in a ContextVar so it propagates implicitly through async call chains —
+tasks can read it without the caller threading it through manually (same pattern
+as pydantic-ai's RunContext / dependency injection).
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .store import Store
+
+
+@dataclass
+class RunContext:
+    run_id: str
+    workflow_id: str
+    store: "Store"
+
+    # Tracks how many times each step name has been used so we can
+    # auto-generate unique, deterministic step IDs without the user needing
+    # to think about it.  e.g. fetch_user called twice → "fetch_user", "fetch_user#1"
+    _counters: dict[str, int] = field(default_factory=lambda: defaultdict(int))
+
+    def next_step_id(self, name: str) -> str:
+        count = self._counters[name]
+        self._counters[name] += 1
+        return name if count == 0 else f"{name}#{count}"
+
+
+# The single active run for the current async task / coroutine tree.
+# set() returns a Token you can use to reset later (important for nesting).
+_active_run: ContextVar[RunContext | None] = ContextVar("_active_run", default=None)

durable/store.py

@@ -0,0 +1,198 @@
+"""
+Storage backends for durable step checkpoints.
+
+Default: SQLiteStore (zero deps beyond aiosqlite).
+Override by passing any Store subclass to Workflow(db=...).
+
+Schema is intentionally minimal — two tables:
+  runs  → track lifecycle of a workflow execution
+  steps → store serialized results keyed by (run_id, step_id)
+"""
+
+from __future__ import annotations
+
+import json
+from abc import ABC, abstractmethod
+from typing import Any
+
+import aiosqlite
+
+# We wrap every stored value in {"v": ...} so we can distinguish
+# "step not found" (None) from "step completed and returned None" ({"v": null}).
+_WRAP_KEY = "v"
+
+
+def _wrap(value: Any) -> str:
+    return json.dumps({_WRAP_KEY: value})
+
+
+def _unwrap(raw: str) -> Any:
+    return json.loads(raw)[_WRAP_KEY]
+
+
+class Store(ABC):
+    """Abstract base — implement this to use Postgres, Redis, etc."""
+
+    @abstractmethod
+    async def setup(self) -> None:
+        """Called once before the store is used. Create tables, connect pools, etc."""
+
+    @abstractmethod
+    async def get_step(self, run_id: str, step_id: str) -> tuple[bool, Any]:
+        """Return (found, value). found=False means the step hasn't run yet."""
+
+    @abstractmethod
+    async def set_step(
+        self, run_id: str, step_id: str, result: Any, attempt: int = 1
+    ) -> None:
+        """Persist a completed step result."""
+
+    @abstractmethod
+    async def mark_run_done(self, run_id: str) -> None:
+        """Mark the whole workflow run as successfully completed."""
+
+    @abstractmethod
+    async def mark_run_failed(self, run_id: str, error: str) -> None:
+        """Mark the run as failed with an error message."""
+
+
+_SENTINEL = object()
+
+
+class InMemoryStore(Store):
+    """
+    Dict-backed store — no persistence, no dependencies.
+
+    Useful for testing, short-lived scripts, and development where you don't
+    need crash recovery across process restarts.
+    """
+
+    def __init__(self) -> None:
+        self._steps: dict[tuple[str, str], Any] = {}
+        self._runs: dict[str, str] = {}
+
+    async def setup(self) -> None:
+        pass
+
+    async def get_step(self, run_id: str, step_id: str) -> tuple[bool, Any]:
+        value = self._steps.get((run_id, step_id), _SENTINEL)
+        if value is _SENTINEL:
+            return False, None
+        return True, value
+
+    async def set_step(
+        self, run_id: str, step_id: str, result: Any, attempt: int = 1
+    ) -> None:
+        self._steps[(run_id, step_id)] = result
+
+    async def mark_run_done(self, run_id: str) -> None:
+        self._runs[run_id] = "done"
+
+    async def mark_run_failed(self, run_id: str, error: str) -> None:
+        self._runs[run_id] = "failed"
+
+
+class SQLiteStore(Store):
+    """
+    Default store backed by a local SQLite file via aiosqlite.
+
+    Works great for local dev, single-process services, CLIs, and scripts.
+    For production or multi-process workloads, swap in a Postgres/Redis store.
+    """
+
+    def __init__(self, path: str = "durable.db") -> None:
+        self.path = path
+        self._ready = False
+
+    async def setup(self) -> None:
+        if self._ready:
+            return
+        async with aiosqlite.connect(self.path) as db:
+            await db.executescript("""
+                CREATE TABLE IF NOT EXISTS runs (
+                    run_id      TEXT PRIMARY KEY,
+                    workflow_id TEXT NOT NULL,
+                    status      TEXT NOT NULL DEFAULT 'running',
+                    error       TEXT,
+                    created_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                    updated_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+                );
+
+                CREATE TABLE IF NOT EXISTS steps (
+                    run_id     TEXT NOT NULL,
+                    step_id    TEXT NOT NULL,
+                    result     TEXT NOT NULL,
+                    attempt    INTEGER NOT NULL DEFAULT 1,
+                    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                    PRIMARY KEY (run_id, step_id)
+                );
+            """)
+            await db.commit()
+        self._ready = True
+
+    async def get_step(self, run_id: str, step_id: str) -> tuple[bool, Any]:
+        async with aiosqlite.connect(self.path) as db:
+            async with db.execute(
+                "SELECT result FROM steps WHERE run_id = ? AND step_id = ?",
+                (run_id, step_id),
+            ) as cursor:
+                row = await cursor.fetchone()
+                if row is None:
+                    return False, None
+                return True, _unwrap(row[0])
+
+    async def set_step(
+        self, run_id: str, step_id: str, result: Any, attempt: int = 1
+    ) -> None:
+        async with aiosqlite.connect(self.path) as db:
+            await db.execute(
+                """
+                INSERT INTO steps (run_id, step_id, result, attempt)
+                VALUES (?, ?, ?, ?)
+                ON CONFLICT(run_id, step_id) DO UPDATE
+                    SET result = excluded.result, attempt = excluded.attempt
+                """,
+                (run_id, step_id, _wrap(result), attempt),
+            )
+            await db.commit()
+
+    async def _upsert_run(
+        self, run_id: str, workflow_id: str, status: str, error: str | None = None
+    ) -> None:
+        async with aiosqlite.connect(self.path) as db:
+            await db.execute(
+                """
+                INSERT INTO runs (run_id, workflow_id, status, error)
+                VALUES (?, ?, ?, ?)
+                ON CONFLICT(run_id) DO UPDATE
+                    SET status = excluded.status,
+                        error  = excluded.error,
+                        updated_at = CURRENT_TIMESTAMP
+                """,
+                (run_id, workflow_id, status, error),
+            )
+            await db.commit()
+
+    async def mark_run_done(self, run_id: str) -> None:
+        async with aiosqlite.connect(self.path) as db:
+            await db.execute(
+                "UPDATE runs SET status = 'done', updated_at = CURRENT_TIMESTAMP WHERE run_id = ?",
+                (run_id,),
+            )
+            await db.commit()
+
+    async def mark_run_failed(self, run_id: str, error: str) -> None:
+        async with aiosqlite.connect(self.path) as db:
+            await db.execute(
+                "UPDATE runs SET status = 'failed', error = ?, updated_at = CURRENT_TIMESTAMP WHERE run_id = ?",
+                (error, run_id),
+            )
+            await db.commit()
+
+    async def ensure_run(self, run_id: str, workflow_id: str) -> None:
+        async with aiosqlite.connect(self.path) as db:
+            await db.execute(
+                "INSERT OR IGNORE INTO runs (run_id, workflow_id, status) VALUES (?, ?, 'running')",
+                (run_id, workflow_id),
+            )
+            await db.commit()

durable/workflow.py

@@ -0,0 +1,338 @@
+"""
+Core Workflow class — the single object developers interact with.
+
+    wf = Workflow("my-app")          # defaults to SQLite at ./durable.db
+    wf = Workflow("my-app", db="sqlite:///jobs.db")
+    wf = Workflow("my-app", db=MyPostgresStore())
+
+Then decorate tasks and workflows:
+
+    @wf.task
+    async def my_task(x: int) -> str: ...
+
+    @wf.task(retries=5, backoff=exponential(base=2, max=30))
+    async def flaky_task(url: str) -> dict: ...
+
+    @wf.workflow(id="job-{job_id}")
+    async def my_workflow(job_id: str) -> None:
+        result = await my_task(42)
+        ...
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import inspect
+import logging
+import re
+from typing import Any, Callable, ParamSpec, TypeVar, overload
+
+from .backoff import BackoffStrategy, exponential
+from .context import RunContext, _active_run
+from .store import SQLiteStore, Store
+
+log = logging.getLogger("durable")
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+# Matches "{param_name}" in workflow id templates
+_TEMPLATE_RE = re.compile(r"\{(\w+)\}")
+
+
+def _format_run_id(template: str, bound: inspect.BoundArguments) -> str:
+    """Replace {param} placeholders with actual argument values."""
+    args = {**bound.arguments}
+    # Flatten **kwargs into the top-level dict if present
+    for k, v in list(args.items()):
+        if isinstance(v, dict) and k not in _TEMPLATE_RE.findall(template):
+            args.update(v)
+    return template.format_map(args)
+
+
+class _TaskWrapper:
+    """
+    Wraps an async function with checkpoint + retry logic.
+
+    Behaves like the original coroutine function — fully typed, awaitable,
+    introspectable. The durable magic only activates when called inside an
+    active workflow run (i.e. a RunContext is set in the ContextVar).
+
+    Outside a workflow, it just executes normally — great for testing.
+    """
+
+    def __init__(
+        self,
+        fn: Callable[..., Any],
+        *,
+        step_name: str,
+        retries: int,
+        backoff: BackoffStrategy,
+    ) -> None:
+        self._fn = fn
+        self._step_name = step_name
+        self._retries = retries
+        self._backoff = backoff
+        # Preserve the original function's metadata for IDE / tooling support
+        functools.update_wrapper(self, fn)
+
+    async def __call__(
+        self, *args: Any, step_id: str | None = None, **kwargs: Any
+    ) -> Any:
+        ctx = _active_run.get()
+
+        if ctx is None:
+            # Called outside a workflow — run as a plain async function.
+            log.debug(
+                "[durable] %s called outside workflow context, running directly",
+                self._step_name,
+            )
+            return await self._fn(*args, **kwargs)
+
+        sid = step_id or ctx.next_step_id(self._step_name)
+        found, cached = await ctx.store.get_step(ctx.run_id, sid)
+
+        if found:
+            log.debug(
+                "[durable] ↩  %s (step=%s) — replayed from store", self._step_name, sid
+            )
+            return cached
+
+        return await self._execute_with_retry(ctx, sid, args, kwargs)
+
+    async def _execute_with_retry(
+        self, ctx: RunContext, sid: str, args: tuple, kwargs: dict
+    ) -> Any:
+        last_exc: Exception | None = None
+
+        for attempt in range(self._retries + 1):
+            if attempt > 0:
+                wait = self._backoff(attempt - 1)
+                log.warning(
+                    "[durable] ↻  %s (step=%s) attempt %d/%d — retrying in %.1fs",
+                    self._step_name,
+                    sid,
+                    attempt,
+                    self._retries,
+                    wait,
+                )
+                await asyncio.sleep(wait)
+
+            try:
+                result = await self._fn(*args, **kwargs)
+                await ctx.store.set_step(ctx.run_id, sid, result, attempt + 1)
+                log.debug("[durable] ✓  %s (step=%s)", self._step_name, sid)
+                return result
+
+            except Exception as exc:
+                last_exc = exc
+                log.warning(
+                    "[durable] ✗  %s (step=%s) attempt %d failed: %s",
+                    self._step_name,
+                    sid,
+                    attempt + 1,
+                    exc,
+                )
+
+        raise last_exc  # type: ignore[misc]
+
+    def __repr__(self) -> str:
+        return f"<DurableTask '{self._step_name}' retries={self._retries}>"
+
+
+class Workflow:
+    """
+    The main entry point for the durable library.
+
+    Create one per application (or one per logical domain):
+
+        wf = Workflow("orders", db="sqlite:///orders.db")
+
+    Then use @wf.task and @wf.workflow to make your code durable.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        db: str | Store = "durable.db",
+        default_retries: int = 3,
+        default_backoff: BackoffStrategy = exponential(),
+    ) -> None:
+        self.name = name
+        self._default_retries = default_retries
+        self._default_backoff = default_backoff
+        self._store = self._build_store(db)
+        self._initialized = False
+
+    # ------------------------------------------------------------------
+    # @wf.task — can be used bare or with arguments
+    # ------------------------------------------------------------------
+
+    @overload
+    def task(self, fn: Callable[P, R]) -> _TaskWrapper: ...
+
+    @overload
+    def task(
+        self,
+        fn: None = None,
+        *,
+        name: str | None = None,
+        retries: int | None = None,
+        backoff: BackoffStrategy | None = None,
+    ) -> Callable[[Callable[P, R]], _TaskWrapper]: ...
+
+    def task(
+        self,
+        fn: Callable | None = None,
+        *,
+        name: str | None = None,
+        retries: int | None = None,
+        backoff: BackoffStrategy | None = None,
+    ) -> _TaskWrapper | Callable:
+        """
+        Decorate an async function to make it a durable task.
+
+        Usage (bare):
+            @wf.task
+            async def fetch_user(user_id: str) -> User: ...
+
+        Usage (with options):
+            @wf.task(retries=5, backoff=exponential(base=2, max=120))
+            async def call_api(url: str) -> dict: ...
+
+            @wf.task(name="send-welcome-email")
+            async def send_email(user: User) -> None: ...
+        """
+
+        def decorator(func: Callable[..., Any]) -> _TaskWrapper:
+            fn_name = getattr(func, "__name__", repr(func))
+            if not asyncio.iscoroutinefunction(func):
+                raise TypeError(
+                    f"@wf.task requires an async function, got: {fn_name!r}"
+                )
+            return _TaskWrapper(
+                func,
+                step_name=name or fn_name,
+                retries=retries if retries is not None else self._default_retries,
+                backoff=backoff or self._default_backoff,
+            )
+
+        if fn is not None:
+            # Used bare: @wf.task
+            return decorator(fn)
+        # Used with args: @wf.task(retries=5)
+        return decorator
+
+    # ------------------------------------------------------------------
+    # @wf.workflow — entry point for a durable run
+    # ------------------------------------------------------------------
+
+    def workflow(
+        self,
+        fn: Callable | None = None,
+        *,
+        id: str | None = None,  # noqa: A002  (shadows builtin intentionally)
+    ) -> Callable:
+        """
+        Decorate an async function as a durable workflow entry point.
+
+        The `id` parameter is a template string resolved from the function's
+        arguments at call time:
+
+            @wf.workflow(id="process-order-{order_id}")
+            async def process_order(order_id: str) -> None: ...
+
+            await process_order(order_id="ord-99")
+            # run_id → "process-order-ord-99"
+
+        If `id` is omitted, the run_id is "{workflow_name}-{fn_name}-{all_args_joined}".
+
+        You can also call `.run(run_id, ...)` to supply an explicit run ID:
+
+            await process_order.run("my-run-123", order_id="ord-99")
+        """
+
+        def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+            fn_name = getattr(func, "__name__", repr(func))
+            if not asyncio.iscoroutinefunction(func):
+                raise TypeError(
+                    f"@wf.workflow requires an async function, got: {fn_name!r}"
+                )
+
+            id_template = id  # capture for closure
+            sig = inspect.signature(func)
+
+            async def _run_with_id(run_id: str, *args: Any, **kwargs: Any) -> Any:
+                await self._ensure_initialized()
+
+                # Create a new RunContext and install it in the ContextVar.
+                ctx = RunContext(
+                    run_id=run_id,
+                    workflow_id=f"{self.name}.{fn_name}",
+                    store=self._store,
+                )
+
+                if isinstance(self._store, SQLiteStore):
+                    await self._store.ensure_run(run_id, ctx.workflow_id)
+
+                token = _active_run.set(ctx)
+                try:
+                    result = await func(*args, **kwargs)
+                    await self._store.mark_run_done(run_id)
+                    log.info("[durable] ✓✓ workflow %s (%s) completed", fn_name, run_id)
+                    return result
+                except Exception as exc:
+                    await self._store.mark_run_failed(run_id, str(exc))
+                    log.error(
+                        "[durable] ✗✗ workflow %s (%s) failed: %s",
+                        fn_name,
+                        run_id,
+                        exc,
+                    )
+                    raise
+                finally:
+                    _active_run.reset(token)
+
+            @functools.wraps(func)
+            async def wrapper(*args: Any, **kwargs: Any) -> Any:
+                bound = sig.bind(*args, **kwargs)
+                bound.apply_defaults()
+
+                if id_template:
+                    run_id = _format_run_id(id_template, bound)
+                else:
+                    parts = [self.name, fn_name] + [
+                        str(v) for v in bound.arguments.values()
+                    ]
+                    run_id = "-".join(parts)
+
+                return await _run_with_id(run_id, *args, **kwargs)
+
+            async def run(run_id: str, *args: Any, **kwargs: Any) -> Any:
+                """Call with an explicit run ID instead of the template-derived one."""
+                return await _run_with_id(run_id, *args, **kwargs)
+
+            wrapper.run = run  # type: ignore[attr-defined]
+            return wrapper
+
+        if fn is not None:
+            return decorator(fn)
+        return decorator
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    async def _ensure_initialized(self) -> None:
+        if not self._initialized:
+            await self._store.setup()
+            self._initialized = True
+
+    @staticmethod
+    def _build_store(db: str | Store) -> Store:
+        if isinstance(db, Store):
+            return db
+        # Accept both "sqlite:///path.db" and bare "path.db"
+        path = db.removeprefix("sqlite:///")
+        return SQLiteStore(path)

python_durable-0.1.0.dist-info/METADATA

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: python-durable
+Version: 0.1.0
+Summary: Lightweight workflow durability for Python — make any async workflow resumable after crashes with just a decorator.
+Project-URL: Repository, https://github.com/WillemDeGroef/python-durable
+Author: Willem
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: aiosqlite>=0.20
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Requires-Dist: ty>=0.0.1a7; extra == 'dev'
+Provides-Extra: examples
+Requires-Dist: pydantic-ai>=0.1; extra == 'examples'
+Requires-Dist: pydantic>=2.0; extra == 'examples'
+Description-Content-Type: text/markdown
+
+# durable
+
+Lightweight workflow durability for Python. Make any async workflow resumable after crashes with just a decorator.
+
+Backed by SQLite out of the box; swap in any `Store` subclass for production.
+
+## Install
+
+```bash
+pip install python-durable
+```
+
+## Quick start
+
+```python
+from durable import Workflow
+from durable.backoff import exponential
+
+wf = Workflow("my-app")
+
+@wf.task(retries=3, backoff=exponential(base=2, max=60))
+async def fetch_data(url: str) -> dict:
+    async with httpx.AsyncClient() as client:
+        return (await client.get(url)).json()
+
+@wf.task
+async def save_result(data: dict) -> None:
+    await db.insert(data)
+
+@wf.workflow(id="pipeline-{source}")
+async def run_pipeline(source: str) -> None:
+    data = await fetch_data(f"https://api.example.com/{source}")
+    await save_result(data)
+
+# First call: runs all steps and checkpoints each one.
+# If it crashes and you call it again with the same args,
+# completed steps are replayed from SQLite instantly.
+await run_pipeline(source="users")
+```
+
+## How it works
+
+1. **`@wf.task`** wraps an async function with checkpoint + retry logic. When called inside a workflow, results are persisted to the store. On re-run, completed steps return their cached result without re-executing.
+
+2. **`@wf.workflow`** marks the entry point of a durable run. It manages a `RunContext` (via `ContextVar`) so tasks automatically know which run they belong to. The `id` parameter is a template string resolved from function arguments at call time.
+
+3. **`Store`** is the persistence backend. `SQLiteStore` is the default (zero config, backed by aiosqlite). Subclass `Store` to use Postgres, Redis, or anything else.
+
+## Features
+
+- **Crash recovery** — completed steps are never re-executed after a restart
+- **Automatic retries** — configurable per-task with `exponential`, `linear`, or `constant` backoff
+- **Loop support** — use `step_id` to checkpoint each iteration independently
+- **Zero magic outside workflows** — tasks work as plain async functions when called without a workflow context
+- **Pluggable storage** — SQLite by default, bring your own `Store` for production
+
+## Backoff strategies
+
+```python
+from durable.backoff import exponential, linear, constant
+
+@wf.task(retries=5, backoff=exponential(base=2, max=60))  # 2s, 4s, 8s, 16s, 32s
+async def exp_task(): ...
+
+@wf.task(retries=3, backoff=linear(start=2, step=3))      # 2s, 5s, 8s
+async def linear_task(): ...
+
+@wf.task(retries=3, backoff=constant(5))                   # 5s, 5s, 5s
+async def const_task(): ...
+```
+
+## Loops with step_id
+
+When calling the same task in a loop, pass `step_id` so each iteration is checkpointed independently:
+
+```python
+@wf.workflow(id="batch-{batch_id}")
+async def process_batch(batch_id: str) -> None:
+    for i, item in enumerate(items):
+        await process_item(item, step_id=f"item-{i}")
+```
+
+If the workflow crashes mid-loop, only the remaining items are processed on restart.
+
+## Important: JSON serialization
+
+Task return values must be JSON-serializable (dicts, lists, strings, numbers, booleans, `None`). The store uses `json.dumps` internally.
+
+For Pydantic models, return `.model_dump()` from tasks and reconstruct with `.model_validate()` downstream:
+
+```python
+@wf.task
+async def validate_invoice(draft: InvoiceDraft) -> dict:
+    validated = ValidatedInvoice(...)
+    return validated.model_dump()
+
+@wf.task
+async def book_invoice(data: dict) -> dict:
+    invoice = ValidatedInvoice.model_validate(data)
+    ...
+```
+
+## License
+
+MIT

python_durable-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+durable/__init__.py,sha256=o1jPcXSMbTbLeHotN2ysDECiguIhSlCnANeCYOVTE9s,1423
+durable/backoff.py,sha256=o5p3hXfJ1YMwmEzjzukqW6inYezYGYnEi3_1YwnmDcU,1056
+durable/context.py,sha256=greEK4jRz9RmVc5kHlmBjU3fisrsl2RCDDtGUPEiQM4,1324
+durable/store.py,sha256=LXSE5h6W4ph9Sb4wN0XiBLfb2f5Q41IkaaWf8EUnWgo,6786
+durable/workflow.py,sha256=qYiOvbGHrcxnifx1sCJCC1CONo8O4BhB2KQ8QdaArkg,11303
+python_durable-0.1.0.dist-info/METADATA,sha256=nD8qU-FfCXb7SccCKDY4rAyyFBE-2bVyoHsfWHb0Qo0,4620
+python_durable-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+python_durable-0.1.0.dist-info/licenses/LICENSE,sha256=S5JKY7biEEYA0tC7Qr2hO-ppopDVnD8muKbaviRFqLk,1084
+python_durable-0.1.0.dist-info/RECORD,,

python_durable-0.1.0.dist-info/WHEEL

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

python_durable-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 python-durable contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.