durable-workflow 0.4.2__tar.gz → 0.4.4__tar.gz

{durable_workflow-0.4.2/src/durable_workflow.egg-info → durable_workflow-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: durable-workflow
-Version: 0.4.2
+Version: 0.4.4
 Summary: Python SDK for the Durable Workflow server (language-neutral HTTP protocol)
 Author: Durable Workflow Contributors
 License-Expression: MIT

{durable_workflow-0.4.2 → durable_workflow-0.4.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "durable-workflow"
-version = "0.4.2"
+version = "0.4.4"
 description = "Python SDK for the Durable Workflow server (language-neutral HTTP protocol)"
 readme = "README.md"
 requires-python = ">=3.10"

{durable_workflow-0.4.2 → durable_workflow-0.4.4}/src/durable_workflow/__init__.py

@@ -25,6 +25,8 @@ from .client import (
     ScheduleBackfillResult,
     ScheduleDescription,
     ScheduleHandle,
+    ScheduleHistoryEvent,
+    ScheduleHistoryPage,
     ScheduleList,
     ScheduleSpec,
     ScheduleTriggerResult,
@@ -171,6 +173,8 @@ __all__ = [
     "ScheduleBackfillResult",
     "ScheduleDescription",
     "ScheduleHandle",
+    "ScheduleHistoryEvent",
+    "ScheduleHistoryPage",
     "ScheduleList",
     "ScheduleNotFound",
     "ScheduleSpec",

{durable_workflow-0.4.2 → durable_workflow-0.4.4}/src/durable_workflow/client.py

@@ -21,7 +21,7 @@ from __future__ import annotations
 import asyncio
 import time
 import warnings
-from collections.abc import Callable
+from collections.abc import AsyncIterator, Callable
 from dataclasses import dataclass
 from importlib.metadata import PackageNotFoundError
 from importlib.metadata import version as _pkg_version
@@ -745,6 +745,42 @@ class ScheduleBackfillResult:
     results: list[dict[str, Any]] | None = None
 
 
+@dataclass
+class ScheduleHistoryEvent:
+    """One entry in a schedule's audit history stream.
+
+    Each event corresponds to a lifecycle transition recorded by the
+    server (ScheduleCreated, SchedulePaused, ScheduleResumed,
+    ScheduleUpdated, ScheduleTriggered, ScheduleTriggerSkipped, or
+    ScheduleDeleted). The ``payload`` mirrors what the workflow engine
+    recorded, including command-context attribution when the transition
+    came from a mutating API call.
+    """
+
+    sequence: int
+    event_type: str | None = None
+    recorded_at: str | None = None
+    workflow_instance_id: str | None = None
+    workflow_run_id: str | None = None
+    payload: dict[str, Any] | None = None
+    id: str | None = None
+
+
+@dataclass
+class ScheduleHistoryPage:
+    """One page of a schedule's audit history stream.
+
+    ``next_cursor`` is the ``after_sequence`` value to request the next
+    page when ``has_more`` is ``True``; it is ``None`` on the final page.
+    """
+
+    schedule_id: str
+    events: list[ScheduleHistoryEvent]
+    has_more: bool = False
+    next_cursor: int | None = None
+    namespace: str | None = None
+
+
 @dataclass
 class BridgeAdapterOutcome:
     """Machine-readable result returned by a bridge adapter event."""
@@ -934,6 +970,32 @@ class ScheduleHandle:
             self.schedule_id, start_time=start_time, end_time=end_time, overlap_policy=overlap_policy,
         )
 
+    async def history(
+        self,
+        *,
+        limit: int | None = None,
+        after_sequence: int | None = None,
+    ) -> ScheduleHistoryPage:
+        """Return one page of this schedule's audit history. See :meth:`Client.get_schedule_history`."""
+        return await self._client.get_schedule_history(
+            self.schedule_id,
+            limit=limit,
+            after_sequence=after_sequence,
+        )
+
+    def iter_history(
+        self,
+        *,
+        limit: int | None = None,
+        after_sequence: int | None = None,
+    ) -> AsyncIterator[ScheduleHistoryEvent]:
+        """Iterate every audit event for this schedule. See :meth:`Client.iter_schedule_history`."""
+        return self._client.iter_schedule_history(
+            self.schedule_id,
+            limit=limit,
+            after_sequence=after_sequence,
+        )
+
 
 class Client:
     """Async HTTP client for Durable Workflow control-plane and worker APIs.
@@ -2409,6 +2471,102 @@ class Client:
             results=data.get("results"),
         )
 
+    async def get_schedule_history(
+        self,
+        schedule_id: str,
+        *,
+        limit: int | None = None,
+        after_sequence: int | None = None,
+    ) -> ScheduleHistoryPage:
+        """Return one page of the audit history stream for a schedule.
+
+        The page is ordered by ``sequence`` ascending. Use
+        ``after_sequence=page.next_cursor`` to request the next page while
+        ``page.has_more`` is ``True``, or call :meth:`iter_schedule_history`
+        to walk every remaining event with paging hidden.
+
+        History is available for deleted schedules: the audit stream
+        records ``ScheduleDeleted`` and survives the schedule's removal
+        exactly so operators can review what happened.
+
+        ``limit`` is clamped by the server between 1 and 500 (default
+        100). ``after_sequence`` must be a non-negative integer; invalid
+        values raise :class:`~durable_workflow.errors.InvalidArgument`
+        through the shared 4xx mapping.
+        """
+        if limit is not None and limit < 1:
+            raise ValueError("limit must be >= 1")
+        if after_sequence is not None and after_sequence < 0:
+            raise ValueError("after_sequence must be >= 0")
+
+        params: dict[str, str] = {}
+        if limit is not None:
+            params["limit"] = str(limit)
+        if after_sequence is not None:
+            params["after_sequence"] = str(after_sequence)
+
+        path = f"/schedules/{schedule_id}/history"
+        if params:
+            path = f"{path}?{urlencode(params)}"
+
+        data = await self._request("GET", path, context=schedule_id)
+        raw_events = data.get("events") or []
+        events = [
+            ScheduleHistoryEvent(
+                sequence=int(item.get("sequence", 0)),
+                event_type=item.get("event_type"),
+                recorded_at=item.get("recorded_at"),
+                workflow_instance_id=item.get("workflow_instance_id"),
+                workflow_run_id=item.get("workflow_run_id"),
+                payload=item.get("payload") if isinstance(item.get("payload"), dict) else None,
+                id=item.get("id"),
+            )
+            for item in raw_events
+        ]
+
+        raw_cursor = data.get("next_cursor")
+        next_cursor: int | None
+        if raw_cursor is None:
+            next_cursor = None
+        else:
+            try:
+                next_cursor = int(raw_cursor)
+            except (TypeError, ValueError):
+                next_cursor = None
+
+        return ScheduleHistoryPage(
+            schedule_id=data.get("schedule_id", schedule_id),
+            events=events,
+            has_more=bool(data.get("has_more", False)),
+            next_cursor=next_cursor,
+            namespace=data.get("namespace"),
+        )
+
+    async def iter_schedule_history(
+        self,
+        schedule_id: str,
+        *,
+        limit: int | None = None,
+        after_sequence: int | None = None,
+    ) -> AsyncIterator[ScheduleHistoryEvent]:
+        """Yield every audit event for a schedule, paging under the hood.
+
+        Each element is a :class:`ScheduleHistoryEvent`. Paging stops once
+        the server reports ``has_more=False``.
+        """
+        cursor = after_sequence
+        while True:
+            page = await self.get_schedule_history(
+                schedule_id,
+                limit=limit,
+                after_sequence=cursor,
+            )
+            for event in page.events:
+                yield event
+            if not page.has_more or page.next_cursor is None:
+                return
+            cursor = page.next_cursor
+
     # ── Worker protocol ────────────────────────────────────────────────
     async def register_worker(
         self,

{durable_workflow-0.4.2 → durable_workflow-0.4.4/src/durable_workflow.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: durable-workflow
-Version: 0.4.2
+Version: 0.4.4
 Summary: Python SDK for the Durable Workflow server (language-neutral HTTP protocol)
 Author: Durable Workflow Contributors
 License-Expression: MIT

{durable_workflow-0.4.2 → durable_workflow-0.4.4}/tests/test_schedules.py

@@ -14,6 +14,8 @@ from durable_workflow.client import (
     ScheduleBackfillResult,
     ScheduleDescription,
     ScheduleHandle,
+    ScheduleHistoryEvent,
+    ScheduleHistoryPage,
     ScheduleList,
     ScheduleSpec,
     ScheduleTriggerResult,
@@ -538,3 +540,187 @@ class TestScheduleHandle:
                 end_time="2026-04-14T01:00:00Z",
             )
             assert result.fires_attempted == 1
+
+
+class TestScheduleHistory:
+    @pytest.mark.asyncio
+    async def test_parses_events_and_pagination_cursor(self, client: Client) -> None:
+        resp = _mock_response(200, {
+            "schedule_id": "sched-1",
+            "namespace": "ns1",
+            "events": [
+                {
+                    "id": "evt-1",
+                    "sequence": 1,
+                    "event_type": "ScheduleCreated",
+                    "recorded_at": "2026-04-01T00:00:00+00:00",
+                    "workflow_instance_id": None,
+                    "workflow_run_id": None,
+                    "payload": {},
+                },
+                {
+                    "id": "evt-2",
+                    "sequence": 2,
+                    "event_type": "ScheduleTriggered",
+                    "recorded_at": "2026-04-02T00:00:00+00:00",
+                    "workflow_instance_id": "wf-abc",
+                    "workflow_run_id": "run-abc",
+                    "payload": {"outcome": "triggered", "trigger_number": 1},
+                },
+            ],
+            "has_more": True,
+            "next_cursor": 2,
+        })
+
+        with patch.object(client._http, "request", new_callable=AsyncMock, return_value=resp) as mock_req:
+            page = await client.get_schedule_history("sched-1")
+
+        assert isinstance(page, ScheduleHistoryPage)
+        assert page.schedule_id == "sched-1"
+        assert page.namespace == "ns1"
+        assert page.has_more is True
+        assert page.next_cursor == 2
+        assert len(page.events) == 2
+        assert isinstance(page.events[0], ScheduleHistoryEvent)
+        assert page.events[0].sequence == 1
+        assert page.events[0].event_type == "ScheduleCreated"
+        assert page.events[1].workflow_instance_id == "wf-abc"
+        assert page.events[1].payload == {"outcome": "triggered", "trigger_number": 1}
+
+        call = mock_req.call_args
+        assert call.args[0] == "GET"
+        assert call.args[1] == "/api/schedules/sched-1/history"
+
+    @pytest.mark.asyncio
+    async def test_forwards_limit_and_after_sequence_in_query(self, client: Client) -> None:
+        resp = _mock_response(200, {
+            "schedule_id": "sched-1",
+            "namespace": "ns1",
+            "events": [],
+            "has_more": False,
+            "next_cursor": None,
+        })
+
+        with patch.object(client._http, "request", new_callable=AsyncMock, return_value=resp) as mock_req:
+            await client.get_schedule_history("sched-1", limit=50, after_sequence=7)
+
+        call = mock_req.call_args
+        path = call.args[1]
+        assert path.startswith("/api/schedules/sched-1/history?")
+        assert "limit=50" in path
+        assert "after_sequence=7" in path
+
+    @pytest.mark.asyncio
+    async def test_rejects_invalid_limit(self, client: Client) -> None:
+        with pytest.raises(ValueError):
+            await client.get_schedule_history("sched-1", limit=0)
+
+    @pytest.mark.asyncio
+    async def test_rejects_negative_after_sequence(self, client: Client) -> None:
+        with pytest.raises(ValueError):
+            await client.get_schedule_history("sched-1", after_sequence=-1)
+
+    @pytest.mark.asyncio
+    async def test_not_found_maps_to_schedule_not_found(self, client: Client) -> None:
+        resp = _mock_response(404, {"reason": "schedule_not_found", "message": "not found"})
+        with (
+            patch.object(client._http, "request", new_callable=AsyncMock, return_value=resp),
+            pytest.raises(ScheduleNotFound),
+        ):
+            await client.get_schedule_history("missing")
+
+    @pytest.mark.asyncio
+    async def test_iter_pages_across_multiple_server_responses(self, client: Client) -> None:
+        responses = [
+            _mock_response(200, {
+                "schedule_id": "sched-1",
+                "namespace": "ns1",
+                "events": [
+                    {
+                        "sequence": 1,
+                        "event_type": "ScheduleCreated",
+                        "recorded_at": "2026-04-01T00:00:00+00:00",
+                        "payload": {},
+                    },
+                    {
+                        "sequence": 2,
+                        "event_type": "SchedulePaused",
+                        "recorded_at": "2026-04-02T00:00:00+00:00",
+                        "payload": {},
+                    },
+                ],
+                "has_more": True,
+                "next_cursor": 2,
+            }),
+            _mock_response(200, {
+                "schedule_id": "sched-1",
+                "namespace": "ns1",
+                "events": [
+                    {
+                        "sequence": 3,
+                        "event_type": "ScheduleResumed",
+                        "recorded_at": "2026-04-03T00:00:00+00:00",
+                        "payload": {},
+                    },
+                ],
+                "has_more": False,
+                "next_cursor": None,
+            }),
+        ]
+
+        mock = AsyncMock(side_effect=responses)
+        with patch.object(client._http, "request", new=mock):
+            sequences = [event.sequence async for event in client.iter_schedule_history("sched-1")]
+
+        assert sequences == [1, 2, 3]
+        assert mock.call_count == 2
+        second_call_path = mock.call_args_list[1].args[1]
+        assert "after_sequence=2" in second_call_path
+
+    @pytest.mark.asyncio
+    async def test_handle_history_delegates_to_client(self, client: Client) -> None:
+        resp = _mock_response(200, {
+            "schedule_id": "sched-1",
+            "namespace": "ns1",
+            "events": [
+                {
+                    "sequence": 1,
+                    "event_type": "ScheduleCreated",
+                    "recorded_at": "2026-04-01T00:00:00+00:00",
+                    "payload": {},
+                },
+            ],
+            "has_more": False,
+            "next_cursor": None,
+        })
+
+        handle = client.get_schedule_handle("sched-1")
+        with patch.object(client._http, "request", new_callable=AsyncMock, return_value=resp):
+            page = await handle.history(limit=10)
+
+        assert isinstance(page, ScheduleHistoryPage)
+        assert page.events[0].event_type == "ScheduleCreated"
+
+    @pytest.mark.asyncio
+    async def test_handle_iter_history_delegates_to_client(self, client: Client) -> None:
+        resp = _mock_response(200, {
+            "schedule_id": "sched-1",
+            "namespace": "ns1",
+            "events": [
+                {
+                    "sequence": 1,
+                    "event_type": "ScheduleCreated",
+                    "recorded_at": "2026-04-01T00:00:00+00:00",
+                    "payload": {},
+                },
+            ],
+            "has_more": False,
+            "next_cursor": None,
+        })
+
+        handle = client.get_schedule_handle("sched-1")
+        with patch.object(client._http, "request", new_callable=AsyncMock, return_value=resp):
+            events = [event async for event in handle.iter_history()]
+
+        assert len(events) == 1
+        assert events[0].event_type == "ScheduleCreated"