errors: make WorkflowCancelled/ActivityCancelled uncatchable by except Exception

Inherit from BaseException (not DurableWorkflowError/Exception) so a generic
except Exception: block in activity bodies or result handlers cannot silently
swallow cancellation. Mirrors asyncio.CancelledError / KeyboardInterrupt.

Pre-1.0 shape fix for zorporation/durable-workflow#441 — upstream lesson
from temporalio/sdk-python#1292.

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

Author: durable-workflow-ops

CHANGELOG.md

@@ -6,6 +6,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+- **Breaking (pre-1.0):** `WorkflowCancelled` and `ActivityCancelled` now inherit
+  from `BaseException` (not `DurableWorkflowError` / `Exception`), so a generic
+  `except Exception:` block in activity code or result handlers no longer
+  silently swallows cancellation. Callers that relied on catching cancellation
+  via `except Exception:` or `except DurableWorkflowError:` must now either
+  catch the class by name (e.g. `except (ActivityCancelled, WorkflowCancelled):`)
+  or catch `BaseException`. Mirrors the standard-library precedent set by
+  `asyncio.CancelledError` and `KeyboardInterrupt`. Rationale and upstream
+  lesson: [zorporation/durable-workflow#441](https://github.com/zorporation/durable-workflow/issues/441).
+
 ## [0.3.0] — 2026-04-19
 
 ### Added

src/durable_workflow/errors.py

@@ -1,10 +1,19 @@
 """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.
+Every *error* 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.
+
+Cancellation is intentionally *not* in that hierarchy. :class:`WorkflowCancelled`
+and :class:`ActivityCancelled` inherit from :class:`BaseException` directly,
+so a generic ``except Exception:`` block cannot accidentally swallow a
+cancellation signal. Callers that want to handle cancellation must name the
+class explicitly (``except (ActivityCancelled, ...):``). This mirrors the way
+:class:`asyncio.CancelledError` and :class:`KeyboardInterrupt` behave in the
+standard library and avoids the historical mistake called out in
+https://github.com/temporalio/sdk-python/issues/1292.
 """
 
 from __future__ import annotations
@@ -140,19 +149,39 @@ 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."""
+class WorkflowCancelled(BaseException):
+    """A workflow was cancelled and finished in the ``cancelled`` state.
+
+    Inherits from :class:`BaseException` — not :class:`Exception` — so that a
+    generic ``except Exception:`` block cannot accidentally swallow the
+    cancellation outcome. Callers that want to treat a cancelled workflow
+    differently from a failed one (e.g. to skip alerting) must catch this
+    class by name.
+    """
 
     def __init__(self, message: str = "workflow was cancelled") -> None:
         super().__init__(message)
 
 
-class ActivityCancelled(DurableWorkflowError):
+class ActivityCancelled(BaseException):
     """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.
+
+    Inherits from :class:`BaseException` — not :class:`Exception` — so that a
+    user ``except Exception:`` block inside the activity function cannot
+    accidentally swallow the cancellation signal. Activities that need to run
+    cleanup on cancellation should catch this class by name and re-raise:
+
+    .. code-block:: python
+
+        try:
+            await activity.context().heartbeat()
+        except ActivityCancelled:
+            cleanup()
+            raise
     """
 
     def __init__(self, message: str = "activity was cancelled") -> None:

tests/test_activity_context.py

@@ -199,6 +199,45 @@ async def heartbeat_activity() -> str:
         assert call_kwargs["failure_type"] == "ActivityCancelled"
         assert call_kwargs["non_retryable"] is True
 
+    @pytest.mark.asyncio
+    async def test_cancellation_survives_user_generic_except(self, mock_client: AsyncMock) -> None:
+        """A user activity with ``except Exception:`` must not swallow cancellation.
+
+        Regression guard for zorporation/durable-workflow#441: when the server
+        signals cancellation via the heartbeat response, the activity function
+        may have a broad ``except Exception:`` block (for logging, retry, etc.).
+        That block must *not* catch ``ActivityCancelled``, so the worker still
+        reports the activity as cancelled rather than completing normally.
+        """
+        mock_client.heartbeat_activity_task = AsyncMock(return_value={"cancel_requested": True})
+
+        @activity.defn(name="hb-swallow-act")
+        async def activity_with_broad_except() -> str:
+            ctx = activity.context()
+            try:
+                await ctx.heartbeat()
+            except Exception:  # noqa: BLE001 — intentional: simulates user mistake
+                return "swallowed cancellation"
+            return "no cancel"
+
+        worker = Worker(
+            mock_client, task_queue="q1", workflows=[], activities=[activity_with_broad_except]
+        )
+        task = {
+            "task_id": "at-swallow",
+            "activity_attempt_id": "aa-swallow",
+            "activity_type": "hb-swallow-act",
+            "arguments": "[]",
+            "payload_codec": "json",
+        }
+        outcome = await worker._run_activity_task(task)
+
+        assert outcome == "cancelled"
+        mock_client.fail_activity_task.assert_called_once()
+        call_kwargs = mock_client.fail_activity_task.call_args.kwargs
+        assert call_kwargs["failure_type"] == "ActivityCancelled"
+        mock_client.complete_activity_task.assert_not_called()
+
     @pytest.mark.asyncio
     async def test_non_retryable_error(self, mock_client: AsyncMock) -> None:
         @activity.defn(name="nr-act")

tests/test_errors.py

@@ -3,13 +3,16 @@
 import pytest
 
 from durable_workflow.errors import (
+    ActivityCancelled,
+    DurableWorkflowError,
     InvalidArgument,
     NamespaceNotFound,
     QueryFailed,
     ServerError,
     Unauthorized,
     UpdateRejected,
     WorkflowAlreadyStarted,
+    WorkflowCancelled,
     WorkflowNotFound,
     _raise_for_status,
 )
@@ -78,3 +81,66 @@ def test_reason_from_dict(self) -> None:
     def test_reason_from_str(self) -> None:
         e = ServerError(500, "plain text")
         assert e.reason() is None
+
+
+class TestCancellationContract:
+    """Cancellation exceptions must not be caught by generic ``except Exception:``.
+
+    Guards the pre-1.0 design decision that ``WorkflowCancelled`` and
+    ``ActivityCancelled`` inherit from :class:`BaseException` directly, so that
+    user worker/activity code cannot accidentally swallow a cancellation signal
+    in a catch-all. See zorporation/durable-workflow#441.
+    """
+
+    def test_workflow_cancelled_not_caught_by_exception(self) -> None:
+        try:
+            raise WorkflowCancelled("stop")
+        except Exception:  # noqa: BLE001 — intentional: proves it does NOT catch
+            pytest.fail("WorkflowCancelled must not be catchable via except Exception")
+        except WorkflowCancelled:
+            pass
+
+    def test_activity_cancelled_not_caught_by_exception(self) -> None:
+        try:
+            raise ActivityCancelled("stop")
+        except Exception:  # noqa: BLE001 — intentional: proves it does NOT catch
+            pytest.fail("ActivityCancelled must not be catchable via except Exception")
+        except ActivityCancelled:
+            pass
+
+    def test_workflow_cancelled_not_caught_by_durableworkflowerror(self) -> None:
+        """Belt-and-braces: DurableWorkflowError is also an Exception subclass."""
+        try:
+            raise WorkflowCancelled("stop")
+        except DurableWorkflowError:
+            pytest.fail(
+                "WorkflowCancelled must not be catchable via except DurableWorkflowError"
+            )
+        except WorkflowCancelled:
+            pass
+
+    def test_activity_cancelled_not_caught_by_durableworkflowerror(self) -> None:
+        try:
+            raise ActivityCancelled("stop")
+        except DurableWorkflowError:
+            pytest.fail(
+                "ActivityCancelled must not be catchable via except DurableWorkflowError"
+            )
+        except ActivityCancelled:
+            pass
+
+    def test_cancellation_explicitly_caught_by_baseexception(self) -> None:
+        """Callers that really want to catch everything still can — by naming BaseException."""
+        for exc_cls in (WorkflowCancelled, ActivityCancelled):
+            try:
+                raise exc_cls("stop")
+            except BaseException as e:  # noqa: BLE001 — intentional
+                assert isinstance(e, exc_cls)
+
+    def test_cancellation_inheritance_shape(self) -> None:
+        assert issubclass(WorkflowCancelled, BaseException)
+        assert issubclass(ActivityCancelled, BaseException)
+        assert not issubclass(WorkflowCancelled, Exception)
+        assert not issubclass(ActivityCancelled, Exception)
+        assert not issubclass(WorkflowCancelled, DurableWorkflowError)
+        assert not issubclass(ActivityCancelled, DurableWorkflowError)