#378: prepare sdk-python 0.2.0 release

Author: durable-workflow-ops

CHANGELOG.md

@@ -4,18 +4,17 @@ All notable changes to the `durable-workflow` Python SDK are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.1.1] — unreleased
+## [0.2.0] — 2026-04-17
 
 ### Added
 - Runtime server version compatibility check at worker registration. On
   `Worker.run()`, the SDK now calls `/api/cluster/info` and refuses to
   register against a server whose major version falls outside the set the
-  SDK knows how to talk to. This prevents a 0.1.x worker from silently
+  SDK knows how to talk to. This prevents a 0.2.x worker from silently
   attempting to drive a future breaking-release server. (#302)
 - `Client.get_cluster_info()` — fetches the server version and declared
   capability manifest from `/api/cluster/info`.
-- Avro payload codec support (optional). Install with
-  `pip install 'durable-workflow[avro]'` to pull in `apache/avro 1.12`.
+- Avro payload codec support as a core runtime dependency.
   `serializer.encode()`, `serializer.decode()`, and
   `serializer.envelope()` now accept a `codec=` argument, and
   `decode_envelope()` honors the inner codec tag. The Worker decodes
@@ -25,6 +24,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   version: int}` record), byte-compatible with the PHP
   `Workflow\Serializers\Avro` serializer. (#362)
 
+### Changed
+- Avro is now the default codec for new payloads produced by the client,
+  serializer helpers, schedules, workflow commands, and activity results.
+  JSON payloads remain supported for compatibility with existing history.
+- Replayed activity results now decode using the event payload codec.
+
 ## [0.1.0] — 2026-04-12
 
 Initial PyPI release. HTTP+JSON worker and client for the Durable

README.md

@@ -56,7 +56,7 @@ async def main():
 - **Type-safe**: Full type hints, passes `mypy --strict`
 - **Polyglot**: Works alongside PHP workers on the same task queue
 - **HTTP/JSON protocol**: No gRPC, no protobuf dependencies
-- **Codec envelopes**: Proper `{codec: "json", blob: "..."}` serialization for cross-language workflows
+- **Codec envelopes**: Avro payloads by default, with JSON decode compatibility for existing history
 
 ## Documentation
 
@@ -77,7 +77,7 @@ Full documentation is available at [durable-workflow.github.io/docs/2.0/sdks/pyt
 
 ## Compatibility
 
-SDK version 0.1.x requires **Server 2.x** (versions 2.0.0+).
+SDK version 0.2.x is compatible with Durable Workflow server 0.x prerelease images and the Server 2.x protocol line.
 
 The worker automatically checks server version at startup and raises a clear error if incompatible.
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "durable-workflow"
-version = "0.1.1"
+version = "0.2.0"
 description = "Python SDK for the Durable Workflow server (language-neutral HTTP protocol)"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -37,7 +37,6 @@ dependencies = [
 
 [project.optional-dependencies]
 dev = [
-    "avro>=1.12,<2",
     "pytest>=8.0",
     "pytest-asyncio>=0.23",
     "mypy>=1.10",

src/durable_workflow/_avro.py

@@ -10,13 +10,9 @@
 are not yet encodeable/decodeable from this SDK because typed schemas
 require a schema registry that is out of scope for the first Avro release.
 
-The ``avro`` third-party package is an *optional* runtime dependency.
-Install it with::
-
-    pip install 'durable-workflow[avro]'
-
-If the extra is not installed, calling :func:`encode` or :func:`decode`
-raises :class:`AvroNotInstalledError` with the install hint.
+The ``avro`` third-party package is a core runtime dependency. If it is
+missing from a broken or partial installation, calling :func:`encode` or
+:func:`decode` raises :class:`AvroNotInstalledError` with a reinstall hint.
 """
 from __future__ import annotations
 
@@ -43,7 +39,7 @@ def _load_avro_schema() -> Any:
     except ImportError as exc:
         raise AvroNotInstalledError(
             "The 'avro' package is required to encode/decode payloads with the 'avro' "
-            "codec. Install with: pip install 'durable-workflow[avro]'"
+            "codec. Reinstall durable-workflow with its runtime dependencies."
         ) from exc
 
     return avro.schema.parse(WRAPPER_SCHEMA_JSON)
@@ -59,7 +55,7 @@ def encode(value: Any) -> str:
     except ImportError as exc:
         raise AvroNotInstalledError(
             "The 'avro' package is required to encode payloads with the 'avro' "
-            "codec. Install with: pip install 'durable-workflow[avro]'"
+            "codec. Reinstall durable-workflow with its runtime dependencies."
         ) from exc
 
     schema = _load_avro_schema()
@@ -88,7 +84,7 @@ def decode(blob: str) -> Any:
     except ImportError as exc:
         raise AvroNotInstalledError(
             "The 'avro' package is required to decode payloads with the 'avro' "
-            "codec. Install with: pip install 'durable-workflow[avro]'"
+            "codec. Reinstall durable-workflow with its runtime dependencies."
         ) from exc
 
     try:

src/durable_workflow/errors.py

@@ -102,7 +102,7 @@ def __init__(self, message: str, *, cause: Exception | None = None) -> None:
 
 
 class AvroNotInstalledError(DurableWorkflowError, ImportError):
-    """Raised when Avro codec is requested but the ``avro`` extra is not installed."""
+    """Raised when the core ``avro`` runtime dependency is unavailable."""
 
 
 def _raise_for_status(status: int, body: object, *, context: str = "") -> None:

src/durable_workflow/serializer.py

@@ -28,7 +28,7 @@ def encode(value: Any, codec: str = AVRO_CODEC) -> str:
 
     Raises ``ValueError`` for unknown codecs and
     :class:`~durable_workflow.errors.AvroNotInstalledError` when the Avro
-    extra is requested but not installed.
+    runtime dependency is missing from a broken or partial installation.
     """
     if codec == JSON_CODEC:
         return json.dumps(value, separators=(",", ":"), ensure_ascii=False)
@@ -61,7 +61,7 @@ def decode(blob: str | None, codec: str | None = None) -> Any:
 
     Raises ``ValueError`` for unknown codecs or malformed blobs, and
     :class:`~durable_workflow.errors.AvroNotInstalledError` when the Avro
-    extra is requested but not installed.
+    runtime dependency is missing from a broken or partial installation.
     """
     if blob is None or blob == "":
         return None

src/durable_workflow/worker.py

@@ -64,11 +64,11 @@ async def _register(self) -> None:
                 log.warning("unable to parse server version %r; skipping compatibility check", server_version)
                 major = None
 
-            # Require server major version 0 or 2+ (0.x is pre-release, 2.x is stable)
-            # SDK 0.1.x is compatible with server 0.1.x and 2.x
+            # Require server major version 0 or 2 (0.x is pre-release, 2.x is stable).
+            # SDK 0.2.x is compatible with server 0.x prereleases and 2.x protocol releases.
             if major is not None and major not in (0, 2):
                 raise RuntimeError(
-                    f"Server version {server_version} is incompatible with sdk-python 0.1.x "
+                    f"Server version {server_version} is incompatible with sdk-python 0.2.x "
                     f"(requires server 0.x or 2.x). "
                     f"Upgrade the server or use a compatible SDK version."
                 )
@@ -121,15 +121,15 @@ async def _run_workflow_task(self, task: dict[str, Any]) -> list[dict[str, Any]]
             if decoded is not None:
                 start_input = decoded if isinstance(decoded, list) else [decoded]
         except AvroNotInstalledError as e:
-            log.exception("task %s start input Avro decode failed (extra not installed)", task_id)
+            log.exception("task %s start input Avro decode failed (avro dependency unavailable)", task_id)
             try:
                 await self.client.fail_workflow_task(
                     task_id=task_id,
                     lease_owner=self.worker_id,
                     workflow_task_attempt=attempt,
                     message=(
                         f"cannot decode workflow start input with codec 'avro': {e}. "
-                        f"Install the avro extra: pip install 'durable-workflow[avro]'."
+                        f"Reinstall durable-workflow with its runtime dependencies."
                     ),
                     failure_type=type(e).__name__,
                     stack_trace=traceback.format_exc(),
@@ -174,15 +174,15 @@ async def _run_workflow_task(self, task: dict[str, Any]) -> list[dict[str, Any]]
         try:
             outcome = replay(cls, history, start_input, run_id=run_id, payload_codec=codec)
         except AvroNotInstalledError as e:
-            log.exception("replay failed: Avro extra not installed")
+            log.exception("replay failed: Avro dependency unavailable")
             try:
                 await self.client.fail_workflow_task(
                     task_id=task_id,
                     lease_owner=self.worker_id,
                     workflow_task_attempt=attempt,
                     message=(
                         f"cannot replay workflow history with codec 'avro': {e}. "
-                        f"Install the avro extra: pip install 'durable-workflow[avro]'."
+                        f"Reinstall durable-workflow with its runtime dependencies."
                     ),
                     failure_type=type(e).__name__,
                     stack_trace=traceback.format_exc(),
@@ -234,15 +234,15 @@ async def _run_activity_task(self, task: dict[str, Any]) -> None:
         try:
             args = serializer.decode_envelope(raw_args, codec=inbound_codec) or []
         except AvroNotInstalledError as e:
-            log.exception("activity %s arguments Avro decode failed (extra not installed)", task_id)
+            log.exception("activity %s arguments Avro decode failed (avro dependency unavailable)", task_id)
             try:
                 await self.client.fail_activity_task(
                     task_id=task_id,
                     activity_attempt_id=attempt_id,
                     lease_owner=self.worker_id,
                     message=(
                         f"cannot decode activity arguments with codec 'avro': {e}. "
-                        f"Install the avro extra: pip install 'durable-workflow[avro]'."
+                        f"Reinstall durable-workflow with its runtime dependencies."
                     ),
                     failure_type=type(e).__name__,
                     stack_trace=traceback.format_exc(),

tests/test_serializer.py

@@ -11,7 +11,7 @@
     _AVRO_AVAILABLE = False
 
 requires_avro = pytest.mark.skipif(
-    not _AVRO_AVAILABLE, reason="avro extra not installed"
+    not _AVRO_AVAILABLE, reason="avro package not installed"
 )
 
 
@@ -170,14 +170,14 @@ def test_empty_blob_is_none(self) -> None:
 class TestAvroNotInstalledError:
     """Verify AvroNotInstalledError is a proper ImportError subclass.
 
-    This matters because callers who already catch ImportError to detect
-    optional-dep absence (a common Python pattern) will transparently
-    catch the SDK-specific error too.
+    This matters because callers who already catch ImportError for broken
+    or partial installations will transparently catch the SDK-specific
+    error too.
     """
 
     def test_is_import_error_subclass(self) -> None:
         assert issubclass(AvroNotInstalledError, ImportError)
 
     def test_carries_install_hint_in_message(self) -> None:
-        exc = AvroNotInstalledError("install with: pip install 'durable-workflow[avro]'")
-        assert "durable-workflow[avro]" in str(exc)
+        exc = AvroNotInstalledError("reinstall durable-workflow with runtime dependencies")
+        assert "runtime dependencies" in str(exc)

tests/test_worker.py

@@ -195,7 +195,7 @@ async def test_sync_activity(self, mock_client: AsyncMock) -> None:
 
     @pytest.mark.asyncio
     async def test_activity_echoes_avro_codec(self, mock_client: AsyncMock) -> None:
-        avro = pytest.importorskip("avro", reason="avro extra not installed")
+        avro = pytest.importorskip("avro", reason="avro package not installed")
         del avro
         from durable_workflow import serializer as _ser
 
@@ -317,7 +317,7 @@ async def test_activity_json_decode_failure_fails_task(self, mock_client: AsyncM
 
     @pytest.mark.asyncio
     async def test_activity_avro_decode_failure_fails_task(self, mock_client: AsyncMock) -> None:
-        pytest.importorskip("avro", reason="avro extra not installed")
+        pytest.importorskip("avro", reason="avro package not installed")
         worker = Worker(mock_client, task_queue="q1", workflows=[], activities=[echo_activity])
         task = {
             "task_id": "at-bad-avro",
@@ -335,7 +335,7 @@ async def test_activity_avro_decode_failure_fails_task(self, mock_client: AsyncM
         mock_client.complete_activity_task.assert_not_called()
 
     @pytest.mark.asyncio
-    async def test_activity_avro_missing_extra_fails_task(
+    async def test_activity_avro_missing_dependency_fails_task(
         self, mock_client: AsyncMock, monkeypatch: pytest.MonkeyPatch
     ) -> None:
         from durable_workflow import _avro
@@ -344,7 +344,7 @@ async def test_activity_avro_missing_extra_fails_task(
         def _raise_missing(_blob: str) -> None:
             raise AvroNotInstalledError(
                 "The 'avro' package is required to encode/decode payloads with the 'avro' "
-                "codec. Install with: pip install 'durable-workflow[avro]'"
+                "codec. Reinstall durable-workflow with its runtime dependencies."
             )
 
         monkeypatch.setattr(_avro, "decode", _raise_missing)
@@ -360,7 +360,7 @@ def _raise_missing(_blob: str) -> None:
         await worker._run_activity_task(task)
         mock_client.fail_activity_task.assert_called_once()
         call_kwargs = mock_client.fail_activity_task.call_args.kwargs
-        assert "avro extra" in call_kwargs["message"].lower() or "pip install" in call_kwargs["message"]
+        assert "runtime dependencies" in call_kwargs["message"]
         assert call_kwargs["failure_type"] == "AvroNotInstalledError"
         assert call_kwargs["non_retryable"] is True
         mock_client.complete_activity_task.assert_not_called()
@@ -384,7 +384,7 @@ async def test_workflow_json_decode_failure_fails_task(self, mock_client: AsyncM
         mock_client.complete_workflow_task.assert_not_called()
 
     @pytest.mark.asyncio
-    async def test_workflow_avro_missing_extra_fails_task(
+    async def test_workflow_avro_missing_dependency_fails_task(
         self, mock_client: AsyncMock, monkeypatch: pytest.MonkeyPatch
     ) -> None:
         from durable_workflow import _avro
@@ -393,7 +393,7 @@ async def test_workflow_avro_missing_extra_fails_task(
         def _raise_missing(_blob: str) -> None:
             raise AvroNotInstalledError(
                 "The 'avro' package is required to encode/decode payloads with the 'avro' "
-                "codec. Install with: pip install 'durable-workflow[avro]'"
+                "codec. Reinstall durable-workflow with its runtime dependencies."
             )
 
         monkeypatch.setattr(_avro, "decode", _raise_missing)
@@ -410,23 +410,23 @@ def _raise_missing(_blob: str) -> None:
         await worker._run_workflow_task(task)
         mock_client.fail_workflow_task.assert_called_once()
         call_kwargs = mock_client.fail_workflow_task.call_args.kwargs
-        assert "avro extra" in call_kwargs["message"].lower() or "pip install" in call_kwargs["message"]
+        assert "runtime dependencies" in call_kwargs["message"]
         assert call_kwargs["failure_type"] == "AvroNotInstalledError"
         mock_client.complete_workflow_task.assert_not_called()
 
     @pytest.mark.asyncio
-    async def test_workflow_replay_avro_missing_extra_fails_task(
+    async def test_workflow_replay_avro_missing_dependency_fails_task(
         self, mock_client: AsyncMock, monkeypatch: pytest.MonkeyPatch
     ) -> None:
-        """Avro-encoded history result that cannot be decoded (extra missing)
+        """Avro-encoded history result that cannot be decoded (dependency missing)
         surfaces as fail_workflow_task, not an unhandled dispatcher exception."""
         from durable_workflow import _avro
         from durable_workflow.errors import AvroNotInstalledError
 
         def _raise_missing(_blob: str) -> None:
             raise AvroNotInstalledError(
                 "The 'avro' package is required to encode/decode payloads with the 'avro' "
-                "codec. Install with: pip install 'durable-workflow[avro]'"
+                "codec. Reinstall durable-workflow with its runtime dependencies."
             )
 
         monkeypatch.setattr(_avro, "decode", _raise_missing)