docs: add module-level docstrings and fill minor API gaps

Addresses zorporation/durable-workflow#389. Adds module-level
docstrings to client, errors, metrics, retry_policy, worker, and
workflow; adds per-class docstrings to every exception in errors.py
(which were previously inheriting Exception's base docstring); fills
docstrings on ActivityContext.info/is_cancelled/heartbeat,
InMemoryMetrics.counter_value/observations, and the concrete
MetricsRecorder implementations. Hides plumbing methods
(to_server_command, to_dict) from the mkdocstrings reference via
filters and flags the RetryPolicy name-collision footgun in its
module docstring (pointing at #392).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: durable-workflow-ops

mkdocs.yml

@@ -44,7 +44,11 @@ plugins:
             separate_signature: true
             merge_init_into_class: true
             members_order: source
-            filters: ["!^_"]
+            inherited_members: true
+            filters:
+              - "!^_"
+              - "!^to_server_command$"
+              - "!^to_dict$"
 
 markdown_extensions:
   - admonition

src/durable_workflow/activity.py

@@ -45,13 +45,26 @@ def __init__(
 
     @property
     def info(self) -> ActivityInfo:
+        """Metadata for the currently running activity attempt."""
         return self._info
 
     @property
     def is_cancelled(self) -> bool:
+        """``True`` once the server has signalled that the owning workflow cancelled this activity."""
         return self._cancel_requested
 
     async def heartbeat(self, details: dict[str, Any] | None = None) -> None:
+        """Report liveness to the server and check for a cancellation request.
+
+        Long-running activities should call ``heartbeat()`` periodically so the
+        server can distinguish a slow-but-alive attempt from a dead worker.
+        Optional ``details`` are attached to the heartbeat and surface as the
+        activity's last-known progress on failure.
+
+        Raises :class:`~durable_workflow.errors.ActivityCancelled` when the
+        owning workflow has requested cancellation, so the activity can exit
+        cleanly at its next natural break point.
+        """
         resp = await self._client.heartbeat_activity_task(
             task_id=self._info.task_id,
             activity_attempt_id=self._info.activity_attempt_id,

src/durable_workflow/client.py

@@ -1,3 +1,20 @@
+"""Async client for the Durable Workflow server's control and worker planes.
+
+The :class:`Client` wraps the server's HTTP/JSON protocol. Control-plane
+methods (``start_workflow``, ``signal_workflow``, ``describe_workflow``,
+schedule management, …) are what callers use to drive workflows from outside.
+Worker-plane methods (``register_worker``, ``poll_workflow_task``,
+``complete_activity_task``, …) are what the :class:`~durable_workflow.Worker`
+uses to run tasks; they are public so advanced users can build custom
+workers, but most applications should not call them directly.
+
+The module also defines the returned-value dataclasses (``WorkflowExecution``,
+``WorkflowList``, ``ScheduleSpec``, ``ScheduleDescription``, …) and the
+ergonomic handle classes (:class:`WorkflowHandle`, :class:`ScheduleHandle`)
+that bind a workflow or schedule id to a :class:`Client` so you can call
+methods without repeating the id on every call.
+"""
+
 from __future__ import annotations
 
 import asyncio

src/durable_workflow/errors.py

@@ -1,101 +1,172 @@
+"""Typed exceptions raised by the Durable Workflow client and worker.
+
+Every exception inherits from :class:`DurableWorkflowError`, so callers that
+only want to distinguish SDK errors from unrelated failures can catch that
+base. More specific subclasses let callers react to particular outcomes —
+workflow-not-found, update-rejected, schedule-already-exists — without
+parsing server response bodies.
+"""
+
 from __future__ import annotations
 
 from typing import Any
 
 
 class DurableWorkflowError(Exception):
-    pass
+    """Base class for every exception raised by the SDK."""
 
 
 class ServerError(DurableWorkflowError):
+    """A server response was an error that does not map to a typed subclass.
+
+    The HTTP status is on :attr:`status`, and the parsed JSON body is on
+    :attr:`body` when the server returned one.
+    """
+
     def __init__(self, status: int, body: object) -> None:
         super().__init__(f"server returned {status}: {body!r}")
         self.status = status
         self.body = body
 
     def reason(self) -> str | None:
+        """Return the machine-readable ``reason`` field from the response body, if any."""
         if isinstance(self.body, dict):
             return self.body.get("reason")
         return None
 
 
 class WorkflowFailed(DurableWorkflowError):
+    """A workflow finished in the ``failed`` state.
+
+    :attr:`exception_class` carries the fully qualified name of the exception
+    class the workflow raised, when the server recorded one.
+    """
+
     def __init__(self, message: str, exception_class: str | None = None) -> None:
         super().__init__(message)
         self.exception_class = exception_class
 
 
 class WorkflowNotFound(DurableWorkflowError):
+    """The addressed workflow instance does not exist on the server."""
+
     def __init__(self, workflow_id: str) -> None:
         super().__init__(f"workflow not found: {workflow_id}")
         self.workflow_id = workflow_id
 
 
 class WorkflowAlreadyStarted(DurableWorkflowError):
+    """A start request collided with an existing instance id.
+
+    Raised when duplicate-start policy is ``reject`` (the default) and the
+    caller-supplied ``workflow_id`` is already in use.
+    """
+
     def __init__(self, workflow_id: str) -> None:
         super().__init__(f"workflow already started: {workflow_id}")
         self.workflow_id = workflow_id
 
 
 class NamespaceNotFound(DurableWorkflowError):
+    """The namespace configured on the :class:`~durable_workflow.Client` is unknown to the server."""
+
     def __init__(self, namespace: str) -> None:
         super().__init__(f"namespace not found: {namespace}")
         self.namespace = namespace
 
 
 class InvalidArgument(DurableWorkflowError):
+    """The server rejected the request as malformed (HTTP 422).
+
+    :attr:`errors` holds the structured validation errors from the response
+    body when the server returned them.
+    """
+
     def __init__(self, message: str, errors: dict[str, Any] | None = None) -> None:
         super().__init__(message)
         self.errors = errors
 
 
 class Unauthorized(DurableWorkflowError):
+    """The request was rejected for missing or invalid authentication (HTTP 401)."""
+
     def __init__(self, message: str = "unauthorized") -> None:
         super().__init__(message)
 
 
 class ScheduleNotFound(DurableWorkflowError):
+    """The addressed schedule does not exist on the server."""
+
     def __init__(self, schedule_id: str) -> None:
         super().__init__(f"schedule not found: {schedule_id}")
         self.schedule_id = schedule_id
 
 
 class ScheduleAlreadyExists(DurableWorkflowError):
+    """A create-schedule request collided with an existing schedule id."""
+
     def __init__(self, schedule_id: str) -> None:
         super().__init__(f"schedule already exists: {schedule_id}")
         self.schedule_id = schedule_id
 
 
 class QueryFailed(DurableWorkflowError):
-    pass
+    """A workflow query was rejected or the workflow raised while handling it."""
 
 
 class UpdateRejected(DurableWorkflowError):
-    pass
+    """A workflow update was rejected by the workflow's validator."""
 
 
 class ChildWorkflowFailed(DurableWorkflowError):
+    """A child workflow finished in the ``failed`` state.
+
+    Raised inside the parent workflow when it awaits the child's result.
+    :attr:`exception_class` mirrors the child's recorded exception class.
+    """
+
     def __init__(self, message: str, exception_class: str | None = None) -> None:
         super().__init__(message)
         self.exception_class = exception_class
 
 
 class WorkflowTerminated(DurableWorkflowError):
+    """A workflow was terminated by operator action.
+
+    Termination is non-gracious and skips normal cleanup, unlike cancellation.
+    """
+
     def __init__(self, message: str = "workflow was terminated") -> None:
         super().__init__(message)
 
 
 class WorkflowCancelled(DurableWorkflowError):
+    """A workflow was cancelled and finished in the ``cancelled`` state."""
+
     def __init__(self, message: str = "workflow was cancelled") -> None:
         super().__init__(message)
 
 
 class ActivityCancelled(DurableWorkflowError):
+    """An in-flight activity was cancelled.
+
+    Raised inside :meth:`durable_workflow.ActivityContext.heartbeat` when the
+    server reports that the owning workflow has asked for cancellation, so the
+    activity can exit cleanly on its next heartbeat.
+    """
+
     def __init__(self, message: str = "activity was cancelled") -> None:
         super().__init__(message)
 
 
 class NonRetryableError(DurableWorkflowError):
+    """Marker an activity can raise to fail its workflow without further retries.
+
+    The server stops retrying the activity and surfaces the failure to the
+    workflow as a terminal activity error, regardless of the configured retry
+    policy.
+    """
+
     def __init__(self, message: str, *, cause: Exception | None = None) -> None:
         super().__init__(message)
         self.__cause__ = cause

src/durable_workflow/metrics.py

@@ -1,3 +1,15 @@
+"""Pluggable metrics hooks for the Durable Workflow client and worker.
+
+Pass any :class:`MetricsRecorder` implementation as ``metrics=`` on
+:class:`~durable_workflow.Client` or :class:`~durable_workflow.Worker`. The
+SDK ships three recorders out of the box: :class:`NoopMetrics` (the default),
+:class:`InMemoryMetrics` for tests and small exporter loops, and
+:class:`PrometheusMetrics` which forwards to the optional ``prometheus-client``
+package. Custom recorders implement two methods — :meth:`MetricsRecorder.increment`
+and :meth:`MetricsRecorder.record` — and receive stable metric names and tag
+dicts defined as module-level constants in this file.
+"""
+
 from __future__ import annotations
 
 from collections.abc import Mapping
@@ -30,10 +42,10 @@ class NoopMetrics:
     """Default metrics recorder that intentionally drops all observations."""
 
     def increment(self, name: str, value: float = 1.0, tags: MetricTags | None = None) -> None:
-        pass
+        """Implements :meth:`MetricsRecorder.increment` as a no-op."""
 
     def record(self, name: str, value: float, tags: MetricTags | None = None) -> None:
-        pass
+        """Implements :meth:`MetricsRecorder.record` as a no-op."""
 
 
 NOOP_METRICS = NoopMetrics()
@@ -51,16 +63,20 @@ class InMemoryMetrics:
     histograms: dict[MetricKey, list[float]] = field(default_factory=dict)
 
     def increment(self, name: str, value: float = 1.0, tags: MetricTags | None = None) -> None:
+        """Accumulate into an in-memory counter keyed by ``name`` + sorted ``tags``."""
         key = _metric_key(name, tags)
         self.counters[key] = self.counters.get(key, 0.0) + value
 
     def record(self, name: str, value: float, tags: MetricTags | None = None) -> None:
+        """Append an observation to an in-memory histogram keyed by ``name`` + sorted ``tags``."""
         self.histograms.setdefault(_metric_key(name, tags), []).append(value)
 
     def counter_value(self, name: str, tags: MetricTags | None = None) -> float:
+        """Return the current value of a counter, or ``0.0`` if it has never been incremented."""
         return self.counters.get(_metric_key(name, tags), 0.0)
 
     def observations(self, name: str, tags: MetricTags | None = None) -> list[float]:
+        """Return a copy of the histogram observations recorded under ``name`` + ``tags``."""
         return list(self.histograms.get(_metric_key(name, tags), []))
 
 
@@ -84,6 +100,7 @@ def __init__(self, *, registry: Any | None = None) -> None:
         self._label_names: dict[tuple[str, str], tuple[str, ...]] = {}
 
     def increment(self, name: str, value: float = 1.0, tags: MetricTags | None = None) -> None:
+        """Forward to a ``prometheus_client.Counter``, creating one on first use."""
         tag_values = dict(_metric_key(name, tags)[1])
         counter = self._metric("counter", name, tuple(tag_values))
         if tag_values:
@@ -92,6 +109,7 @@ def increment(self, name: str, value: float = 1.0, tags: MetricTags | None = Non
             counter.inc(value)
 
     def record(self, name: str, value: float, tags: MetricTags | None = None) -> None:
+        """Forward to a ``prometheus_client.Histogram``, creating one on first use."""
         tag_values = dict(_metric_key(name, tags)[1])
         histogram = self._metric("histogram", name, tuple(tag_values))
         if tag_values:

src/durable_workflow/retry_policy.py

@@ -1,3 +1,15 @@
+"""HTTP transport retry policy used inside :class:`~durable_workflow.Client`.
+
+.. warning::
+
+   This :class:`RetryPolicy` covers **only client-side HTTP retries** for
+   transient transport errors (connection failures, timeouts, 5xx responses,
+   429 rate-limiting). It is **not** the activity retry policy. Activity-level
+   retry and timeout configuration is tracked in
+   https://github.com/zorporation/durable-workflow/issues/392 and will land on
+   ``ctx.schedule_activity(..., retry_policy=...)``.
+"""
+
 from __future__ import annotations
 
 import asyncio

src/durable_workflow/worker.py

@@ -1,3 +1,18 @@
+"""Long-polling worker that runs workflow and activity tasks.
+
+:class:`Worker` registers itself with the server for a given task queue, then
+spawns poll loops for both workflow tasks and activity tasks. Each received
+task is dispatched to the registered workflow class or activity function,
+results are serialized, and success/failure commands are sent back to the
+server. Workers drain in-flight tasks on shutdown up to a configurable
+``shutdown_timeout``.
+
+Most applications create one :class:`Worker` per task queue and pass it the
+same :class:`~durable_workflow.Client` used for control-plane calls, plus
+lists of workflow classes and activity callables registered via
+:func:`durable_workflow.workflow.defn` and :func:`durable_workflow.activity.defn`.
+"""
+
 from __future__ import annotations
 
 import asyncio

src/durable_workflow/workflow.py

@@ -1,3 +1,19 @@
+"""Workflow authoring primitives: decorators, context, commands, and replayer.
+
+A workflow is a Python class registered with :func:`defn`. Its ``run`` method
+is a generator that yields command dataclasses (``ScheduleActivity``,
+``StartTimer``, ``StartChildWorkflow``, …) — the worker's replayer drives the
+generator forward by resolving each yielded command against the current
+history of the workflow run. Yield a *list* of commands to run them in
+parallel.
+
+Determinism-sensitive helpers live on the :class:`WorkflowContext` passed to
+``run``: :meth:`WorkflowContext.random`, :meth:`WorkflowContext.uuid4`,
+:meth:`WorkflowContext.now`, and :meth:`WorkflowContext.side_effect` all
+produce values that are recorded on first execution and replayed verbatim
+on every subsequent replay of the same history.
+"""
+
 from __future__ import annotations
 
 import contextlib