workly 0.2.0__tar.gz → 0.3.0__tar.gz

{workly-0.2.0 → workly-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: workly
-Version: 0.2.0
+Version: 0.3.0
 Summary: Python SDK for Workly, the open-source HTTP task queue
 Keywords: task queue,background jobs,webhooks,http
 License-Expression: Apache-2.0
@@ -156,7 +156,7 @@ client.queues.delete("emails")  # delete the queue and all its tasks
 
 ## Schedules
 
-A schedule calls a URL on a cron timetable; each call is a run, retried and recorded like a task. Schedules are separate from queues. `put` is declarative, like `queues.put`. See [Schedules](https://docs.workly.run/schedules/).
+A schedule calls a URL on a cron timetable; each call is a run, retried and recorded like a task. Schedules are separate from queues. `put` is declarative, like `queues.put`. See [Schedules](https://workly.run/docs/schedules/).
 
 ```python
 schedule = client.schedules.put(
@@ -171,7 +171,7 @@ schedule = client.schedules.put(
 print(schedule.next_runs)  # the next five times
 
 run = client.schedules.trigger("nightly-report")  # run it now
-for run in client.schedules.runs("nightly-report", state="failed"):
+for run in client.runs.list(schedule="nightly-report", state="failed"):
     print(run.id, run.scheduled_for, run.last_error)
 client.runs.attempts(run.id)
 client.runs.retry(run.id)  # deliver it again, e.g. a failed or skipped run
@@ -184,13 +184,16 @@ Runs are delivered with `Workly-Run-Id`, `Workly-Schedule` and `Workly-Scheduled
 
 ## Task groups
 
-A group tracks a set of tasks and enqueues a callback task once it's closed and they've all finished: a `POST` of the group's status and counts. See [Task groups](https://docs.workly.run/groups/).
+A group tracks a set of tasks and enqueues a callback task once it's closed and they've all finished: a `POST` of the group's status and counts. See [Task groups](https://workly.run/docs/groups/). Like every callback, it goes to Workly's `_callbacks` queue.
 
 ```python
+from workly import Callback
+
 group = client.groups.create(
     name="daily-stock-prices",
     idempotency_key="stock-prices-2026-10-19",  # creating it again returns this group
-    on_complete={"queue": "jobs", "url": "https://api.example.com/jobs/refresh-views"},
+    # or a dict: {"url": "https://api.example.com/jobs/refresh-views"}
+    on_complete=Callback(url="https://api.example.com/jobs/refresh-views"),
 )
 for company in companies:
     client.tasks.enqueue(
@@ -209,6 +212,27 @@ for group in client.groups.list(name="daily-stock-prices", status="failed"):
     print(group.id, group.finished_at)
 ```
 
+## Callbacks
+
+Tasks and schedules take the same `on_complete`: each time the task, or a run of the schedule, succeeds, fails or is cancelled, Workly POSTs a summary of it to the URL. See [Callbacks](https://workly.run/docs/callbacks/).
+
+```python
+client.tasks.enqueue(
+    "exports",
+    url="https://api.example.com/jobs/export",
+    payload={"export_id": 42},
+    on_complete=Callback(url="https://api.example.com/jobs/export-done"),
+)
+client.schedules.put(
+    "nightly-report",
+    cron="0 3 * * *",
+    url="https://api.example.com/reports/nightly",
+    on_complete={"url": "https://api.example.com/reports/nightly-done"},
+)
+```
+
+The summary arrives as the callback task's JSON body: `task_id`, `queue`, `state`, `attempt_count`, `last_status`, `last_error` and `finished_at` for a task; `run_id`, `schedule` and the same outcome fields for a run.
+
 ## Async
 
 `AsyncWorkly` has the same methods, as coroutines:

{workly-0.2.0 → workly-0.3.0}/README.md

@@ -136,7 +136,7 @@ client.queues.delete("emails")  # delete the queue and all its tasks
 
 ## Schedules
 
-A schedule calls a URL on a cron timetable; each call is a run, retried and recorded like a task. Schedules are separate from queues. `put` is declarative, like `queues.put`. See [Schedules](https://docs.workly.run/schedules/).
+A schedule calls a URL on a cron timetable; each call is a run, retried and recorded like a task. Schedules are separate from queues. `put` is declarative, like `queues.put`. See [Schedules](https://workly.run/docs/schedules/).
 
 ```python
 schedule = client.schedules.put(
@@ -151,7 +151,7 @@ schedule = client.schedules.put(
 print(schedule.next_runs)  # the next five times
 
 run = client.schedules.trigger("nightly-report")  # run it now
-for run in client.schedules.runs("nightly-report", state="failed"):
+for run in client.runs.list(schedule="nightly-report", state="failed"):
     print(run.id, run.scheduled_for, run.last_error)
 client.runs.attempts(run.id)
 client.runs.retry(run.id)  # deliver it again, e.g. a failed or skipped run
@@ -164,13 +164,16 @@ Runs are delivered with `Workly-Run-Id`, `Workly-Schedule` and `Workly-Scheduled
 
 ## Task groups
 
-A group tracks a set of tasks and enqueues a callback task once it's closed and they've all finished: a `POST` of the group's status and counts. See [Task groups](https://docs.workly.run/groups/).
+A group tracks a set of tasks and enqueues a callback task once it's closed and they've all finished: a `POST` of the group's status and counts. See [Task groups](https://workly.run/docs/groups/). Like every callback, it goes to Workly's `_callbacks` queue.
 
 ```python
+from workly import Callback
+
 group = client.groups.create(
     name="daily-stock-prices",
     idempotency_key="stock-prices-2026-10-19",  # creating it again returns this group
-    on_complete={"queue": "jobs", "url": "https://api.example.com/jobs/refresh-views"},
+    # or a dict: {"url": "https://api.example.com/jobs/refresh-views"}
+    on_complete=Callback(url="https://api.example.com/jobs/refresh-views"),
 )
 for company in companies:
     client.tasks.enqueue(
@@ -189,6 +192,27 @@ for group in client.groups.list(name="daily-stock-prices", status="failed"):
     print(group.id, group.finished_at)
 ```
 
+## Callbacks
+
+Tasks and schedules take the same `on_complete`: each time the task, or a run of the schedule, succeeds, fails or is cancelled, Workly POSTs a summary of it to the URL. See [Callbacks](https://workly.run/docs/callbacks/).
+
+```python
+client.tasks.enqueue(
+    "exports",
+    url="https://api.example.com/jobs/export",
+    payload={"export_id": 42},
+    on_complete=Callback(url="https://api.example.com/jobs/export-done"),
+)
+client.schedules.put(
+    "nightly-report",
+    cron="0 3 * * *",
+    url="https://api.example.com/reports/nightly",
+    on_complete={"url": "https://api.example.com/reports/nightly-done"},
+)
+```
+
+The summary arrives as the callback task's JSON body: `task_id`, `queue`, `state`, `attempt_count`, `last_status`, `last_error` and `finished_at` for a task; `run_id`, `schedule` and the same outcome fields for a run.
+
 ## Async
 
 `AsyncWorkly` has the same methods, as coroutines:

{workly-0.2.0 → workly-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "workly"
-version = "0.2.0"
+version = "0.3.0"
 description = "Python SDK for Workly, the open-source HTTP task queue"
 readme = "README.md"
 license = "Apache-2.0"

{workly-0.2.0 → workly-0.3.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "workly"
-version = "0.2.0"
+version = "0.3.0"
 description = "Python SDK for Workly, the open-source HTTP task queue"
 readme = "README.md"
 license = "Apache-2.0"

{workly-0.2.0 → workly-0.3.0}/src/workly/__init__.py

@@ -32,6 +32,7 @@ from ._models import (
     AlertChannelType,
     Attempt,
     AttemptOutcome,
+    Callback,
     CronPreview,
     Delivery,
     EnqueueResult,
@@ -59,7 +60,7 @@ from ._models import (
     TaskSort,
     TaskState,
 )
-from ._requests import GroupCallbackSpec, TaskSpec, __version__
+from ._requests import CallbackDict, GroupCallbackSpec, TaskSpec, __version__
 from ._signing import sign, verify_signature
 
 __all__ = [
@@ -83,6 +84,8 @@ __all__ = [
     "AttemptOutcome",
     "AuthenticationError",
     "BadRequestError",
+    "Callback",
+    "CallbackDict",
     "ConflictError",
     "CronPreview",
     "Delivery",

{workly-0.2.0 → workly-0.3.0}/src/workly/_async_client.py

@@ -17,6 +17,7 @@ from ._models import (
     AlertChannelList,
     AlertChannelType,
     Attempt,
+    Callback,
     CronPreview,
     Delivery,
     EnqueueResult,
@@ -215,6 +216,7 @@ class AsyncTasks:
         max_attempts: int | None = None,
         timeout_seconds: float | None = None,
         group_id: str | None = None,
+        on_complete: Callback | r.CallbackDict | None = None,
         traceparent: str | None = None,
     ) -> Task:
         """Enqueue a task to deliver to `url`.
@@ -223,7 +225,8 @@ class AsyncTasks:
         created with default settings if it doesn't exist. If
         `idempotency_key` matches a task already in the queue, that task is
         returned and nothing is enqueued. With `group_id`, the task joins
-        that group, which must be open.
+        that group, which must be open. `on_complete` is called each time the
+        task succeeds, fails or is cancelled, with a `TaskSummary`.
         """
         spec = {
             "url": url,
@@ -238,6 +241,7 @@ class AsyncTasks:
             "max_attempts": max_attempts,
             "timeout_seconds": timeout_seconds,
             "group_id": group_id,
+            "on_complete": on_complete,
         }
         return Task._from_json(await self._client._send(r.enqueue(queue, spec, traceparent)))
 
@@ -370,13 +374,13 @@ class AsyncGroups:
         *,
         name: str | None = None,
         idempotency_key: str | None = None,
-        on_complete: r.GroupCallbackSpec | None = None,
+        on_complete: Callback | r.CallbackDict | None = None,
     ) -> Group:
         """Create an open group.
 
         `on_complete` is the task to enqueue when the group completes, e.g.
-        `{"queue": "jobs", "url": "https://api.example.com/done"}`; it is a
-        POST of the group's summary as JSON. If `idempotency_key` matches an
+        `Callback(url="https://api.example.com/done")` or the same as a dict;
+        it is a POST of the group's summary as JSON. If `idempotency_key` matches an
         existing group, that group is returned and nothing is created.
         """
         req = r.create_group(name, idempotency_key, on_complete)
@@ -457,12 +461,15 @@ class AsyncSchedules:
         retry_on_4xx: bool | None = None,
         overlap: OverlapPolicy | None = None,
         missed: MissedPolicy | None = None,
+        on_complete: Callback | r.CallbackDict | None = None,
     ) -> Schedule:
         """Create or update a schedule that calls `url` on `cron` (read in `timezone`, default UTC).
 
         Declarative: the schedule ends up with exactly these settings, and
         omitted ones are reset to their defaults. It doesn't change whether
-        the schedule is paused. `next_runs` on the result shows when it runs.
+        the schedule is paused. `next_runs` on the result shows when it runs
+        (`next_runs_if_resumed` while it is paused). `on_complete` is called
+        each time a run succeeds, fails or is cancelled, with a `RunSummary`.
         """
         config = dict(
             cron=cron,
@@ -481,6 +488,7 @@ class AsyncSchedules:
             retry_on_4xx=retry_on_4xx,
             overlap=overlap,
             missed=missed,
+            on_complete=on_complete,
         )
         return Schedule._from_json(await self._client._send(r.put_schedule(name, config)))
 
@@ -507,38 +515,44 @@ class AsyncSchedules:
         """Run the schedule now, even if paused. Doesn't change when it next fires."""
         return Run._from_json(await self._client._send(r.trigger_schedule(name)))
 
-    async def runs(
-        self, name: str, *, state: RunState | None = None, page_size: int | None = None
+
+class AsyncRuns:
+    """Runs of schedules: one per firing, with its own attempts."""
+
+    def __init__(self, client: AsyncWorkly) -> None:
+        self._client = client
+
+    async def list(
+        self,
+        *,
+        schedule: str | None = None,
+        state: RunState | None = None,
+        page_size: int | None = None,
     ) -> AsyncIterator[Run]:
-        """The schedule's runs, newest first, fetching pages as needed."""
+        """Runs of every schedule, or of one, newest first, fetching pages as needed."""
         cursor: str | None = None
         while True:
-            page = await self.runs_page(name, state=state, cursor=cursor, limit=page_size)
+            page = await self.list_page(
+                schedule=schedule, state=state, cursor=cursor, limit=page_size
+            )
             for run in page.runs:
                 yield run
             if page.next_cursor is None:
                 return
             cursor = page.next_cursor
 
-    async def runs_page(
+    async def list_page(
         self,
-        name: str,
         *,
+        schedule: str | None = None,
         state: RunState | None = None,
         cursor: str | None = None,
         limit: int | None = None,
     ) -> RunPage:
-        """One page of `runs`. Pass the previous page's `next_cursor` as `cursor`."""
-        req = r.list_runs(name, state=state, cursor=cursor, limit=limit)
+        """One page of `list`. Pass the previous page's `next_cursor` as `cursor`."""
+        req = r.list_runs(schedule=schedule, state=state, cursor=cursor, limit=limit)
         return RunPage._from_json(await self._client._send(req))
 
-
-class AsyncRuns:
-    """Runs of schedules: one per firing, with its own attempts."""
-
-    def __init__(self, client: AsyncWorkly) -> None:
-        self._client = client
-
     async def get(self, run_id: str) -> Run:
         return Run._from_json(await self._client._send(r.get_run(run_id)))
 

{workly-0.2.0 → workly-0.3.0}/src/workly/_client.py

@@ -17,6 +17,7 @@ from ._models import (
     AlertChannelList,
     AlertChannelType,
     Attempt,
+    Callback,
     CronPreview,
     Delivery,
     EnqueueResult,
@@ -215,6 +216,7 @@ class Tasks:
         max_attempts: int | None = None,
         timeout_seconds: float | None = None,
         group_id: str | None = None,
+        on_complete: Callback | r.CallbackDict | None = None,
         traceparent: str | None = None,
     ) -> Task:
         """Enqueue a task to deliver to `url`.
@@ -223,7 +225,8 @@ class Tasks:
         created with default settings if it doesn't exist. If
         `idempotency_key` matches a task already in the queue, that task is
         returned and nothing is enqueued. With `group_id`, the task joins
-        that group, which must be open.
+        that group, which must be open. `on_complete` is called each time the
+        task succeeds, fails or is cancelled, with a `TaskSummary`.
         """
         spec = {
             "url": url,
@@ -238,6 +241,7 @@ class Tasks:
             "max_attempts": max_attempts,
             "timeout_seconds": timeout_seconds,
             "group_id": group_id,
+            "on_complete": on_complete,
         }
         return Task._from_json(self._client._send(r.enqueue(queue, spec, traceparent)))
 
@@ -369,13 +373,13 @@ class Groups:
         *,
         name: str | None = None,
         idempotency_key: str | None = None,
-        on_complete: r.GroupCallbackSpec | None = None,
+        on_complete: Callback | r.CallbackDict | None = None,
     ) -> Group:
         """Create an open group.
 
         `on_complete` is the task to enqueue when the group completes, e.g.
-        `{"queue": "jobs", "url": "https://api.example.com/done"}`; it is a
-        POST of the group's summary as JSON. If `idempotency_key` matches an
+        `Callback(url="https://api.example.com/done")` or the same as a dict;
+        it is a POST of the group's summary as JSON. If `idempotency_key` matches an
         existing group, that group is returned and nothing is created.
         """
         req = r.create_group(name, idempotency_key, on_complete)
@@ -455,12 +459,15 @@ class Schedules:
         retry_on_4xx: bool | None = None,
         overlap: OverlapPolicy | None = None,
         missed: MissedPolicy | None = None,
+        on_complete: Callback | r.CallbackDict | None = None,
     ) -> Schedule:
         """Create or update a schedule that calls `url` on `cron` (read in `timezone`, default UTC).
 
         Declarative: the schedule ends up with exactly these settings, and
         omitted ones are reset to their defaults. It doesn't change whether
-        the schedule is paused. `next_runs` on the result shows when it runs.
+        the schedule is paused. `next_runs` on the result shows when it runs
+        (`next_runs_if_resumed` while it is paused). `on_complete` is called
+        each time a run succeeds, fails or is cancelled, with a `RunSummary`.
         """
         config = dict(
             cron=cron,
@@ -479,6 +486,7 @@ class Schedules:
             retry_on_4xx=retry_on_4xx,
             overlap=overlap,
             missed=missed,
+            on_complete=on_complete,
         )
         return Schedule._from_json(self._client._send(r.put_schedule(name, config)))
 
@@ -505,37 +513,41 @@ class Schedules:
         """Run the schedule now, even if paused. Doesn't change when it next fires."""
         return Run._from_json(self._client._send(r.trigger_schedule(name)))
 
-    def runs(
-        self, name: str, *, state: RunState | None = None, page_size: int | None = None
+
+class Runs:
+    """Runs of schedules: one per firing, with its own attempts."""
+
+    def __init__(self, client: Workly) -> None:
+        self._client = client
+
+    def list(
+        self,
+        *,
+        schedule: str | None = None,
+        state: RunState | None = None,
+        page_size: int | None = None,
     ) -> Iterator[Run]:
-        """The schedule's runs, newest first, fetching pages as needed."""
+        """Runs of every schedule, or of one, newest first, fetching pages as needed."""
         cursor: str | None = None
         while True:
-            page = self.runs_page(name, state=state, cursor=cursor, limit=page_size)
+            page = self.list_page(schedule=schedule, state=state, cursor=cursor, limit=page_size)
             yield from page.runs
             if page.next_cursor is None:
                 return
             cursor = page.next_cursor
 
-    def runs_page(
+    def list_page(
         self,
-        name: str,
         *,
+        schedule: str | None = None,
         state: RunState | None = None,
         cursor: str | None = None,
         limit: int | None = None,
     ) -> RunPage:
-        """One page of `runs`. Pass the previous page's `next_cursor` as `cursor`."""
-        req = r.list_runs(name, state=state, cursor=cursor, limit=limit)
+        """One page of `list`. Pass the previous page's `next_cursor` as `cursor`."""
+        req = r.list_runs(schedule=schedule, state=state, cursor=cursor, limit=limit)
         return RunPage._from_json(self._client._send(req))
 
-
-class Runs:
-    """Runs of schedules: one per firing, with its own attempts."""
-
-    def __init__(self, client: Workly) -> None:
-        self._client = client
-
     def get(self, run_id: str) -> Run:
         return Run._from_json(self._client._send(r.get_run(run_id)))
 

{workly-0.2.0 → workly-0.3.0}/src/workly/_models.py

@@ -5,7 +5,8 @@ Unknown fields are ignored, so newer servers don't break older SDKs.
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from collections.abc import Mapping
+from dataclasses import dataclass, field
 from datetime import datetime
 from typing import Any, Literal
 
@@ -65,6 +66,10 @@ class QueueActivity:
     cancelled: int
     retention_seconds: float | None
     """How long the server keeps finished tasks; None if forever. Older ones aren't counted."""
+    p50_duration_ms: int | None = None
+    """Median duration of the latest attempt of the succeeded and failed tasks counted."""
+    p95_duration_ms: int | None = None
+    """95th percentile of the same durations."""
 
     @classmethod
     def _from_json(cls, d: dict[str, Any]) -> QueueActivity:
@@ -74,6 +79,8 @@ class QueueActivity:
             failed=d["failed"],
             cancelled=d["cancelled"],
             retention_seconds=d.get("retention_seconds"),
+            p50_duration_ms=d.get("p50_duration_ms"),
+            p95_duration_ms=d.get("p95_duration_ms"),
         )
 
 
@@ -225,9 +232,18 @@ class Task:
     """When the task was last retried by hand."""
     group_id: str | None = None
     """The group the task belongs to, if any."""
+    started_at: datetime | None = None
+    """When the first delivery attempt started; minus `created_at`, the time spent waiting."""
+    last_duration_ms: int | None = None
+    """How long the latest finished attempt took."""
+    on_complete: Callback | None = None
+    """Called each time the task finishes."""
+    callback_task_id: str | None = None
+    """The callback task enqueued when the task last finished, if it has `on_complete`."""
 
     @classmethod
     def _from_json(cls, d: dict[str, Any]) -> Task:
+        cb = d.get("on_complete")
         return cls(
             id=d["id"],
             queue=d["queue"],
@@ -251,6 +267,10 @@ class Task:
             last_attempt_at=_opt_time(d.get("last_attempt_at")),
             retried_at=_opt_time(d.get("retried_at")),
             group_id=d.get("group_id"),
+            started_at=_opt_time(d.get("started_at")),
+            last_duration_ms=d.get("last_duration_ms"),
+            on_complete=None if cb is None else Callback._from_json(cb),
+            callback_task_id=d.get("callback_task_id"),
         )
 
 
@@ -375,14 +395,21 @@ class Schedule:
     next_run_at: datetime | None
     """When the schedule next fires; None while paused."""
     next_runs: list[datetime]
-    """The next five slots (as if resumed now, while paused)."""
+    """The next five slots. Empty while paused; see `next_runs_if_resumed`."""
     last_run: LastRun | None
     created_at: datetime
     updated_at: datetime
+    paused_at: datetime | None = None
+    """When a paused schedule was paused; None while it runs."""
+    next_runs_if_resumed: list[datetime] | None = None
+    """While paused, the five slots it would run at if resumed now; None while it runs."""
+    on_complete: Callback | None = None
+    """Called each time a run finishes, except skipped runs."""
 
     @classmethod
     def _from_json(cls, d: dict[str, Any]) -> Schedule:
         last = d.get("last_run")
+        cb = d.get("on_complete")
         next_runs: list[str] = d.get("next_runs") or []
         return cls(
             name=d["name"],
@@ -407,6 +434,13 @@ class Schedule:
             last_run=None if last is None else LastRun._from_json(last),
             created_at=_time(d["created_at"]),
             updated_at=_time(d["updated_at"]),
+            paused_at=_opt_time(d.get("paused_at")),
+            next_runs_if_resumed=(
+                None
+                if (resumed := d.get("next_runs_if_resumed")) is None
+                else [_time(t) for t in resumed]
+            ),
+            on_complete=None if cb is None else Callback._from_json(cb),
         )
 
 
@@ -437,6 +471,12 @@ class Run:
     finished_at: datetime | None
     last_attempt_at: datetime | None
     retried_at: datetime | None
+    started_at: datetime | None = None
+    """When the first delivery attempt started."""
+    last_duration_ms: int | None = None
+    """How long the latest finished attempt took."""
+    callback_task_id: str | None = None
+    """The callback task enqueued when the run last finished, if its schedule has `on_complete`."""
 
     @classmethod
     def _from_json(cls, d: dict[str, Any]) -> Run:
@@ -462,6 +502,9 @@ class Run:
             finished_at=_opt_time(d.get("finished_at")),
             last_attempt_at=_opt_time(d.get("last_attempt_at")),
             retried_at=_opt_time(d.get("retried_at")),
+            started_at=_opt_time(d.get("started_at")),
+            last_duration_ms=d.get("last_duration_ms"),
+            callback_task_id=d.get("callback_task_id"),
         )
 
 
@@ -510,17 +553,30 @@ class AlertChannelList:
         )
 
 
-@dataclass(frozen=True, slots=True)
-class GroupCallback:
-    """The task a group enqueues when it completes: a POST of the group's summary as JSON."""
+CALLBACK_QUEUE = "_callbacks"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Callback:
+    """A task Workly enqueues when something completes: a POST to `url` saying what completed.
+
+    Its JSON body is a `TaskSummary` for a task, a `RunSummary` for a
+    schedule's run and a `GroupSummary` for a group. It is delivered as a task
+    in the `_callbacks` queue, with that queue's retries: configure it like
+    any queue to change them.
+    """
 
-    queue: str
     url: str
-    headers: dict[str, str]
+    headers: Mapping[str, str] = field(default_factory=dict[str, str])
+    """Headers sent with the callback. `Workly-*` headers are reserved."""
 
     @classmethod
-    def _from_json(cls, d: dict[str, Any]) -> GroupCallback:
-        return cls(queue=d["queue"], url=d["url"], headers=d.get("headers") or {})
+    def _from_json(cls, d: dict[str, Any]) -> Callback:
+        return cls(url=d["url"], headers=d.get("headers") or {})
+
+
+GroupCallback = Callback
+"""Deprecated: use `Callback`."""
 
 
 @dataclass(frozen=True, slots=True)
@@ -537,7 +593,7 @@ class Group:
     cancelled: int
     remaining: int
     """Tasks still pending or running."""
-    on_complete: GroupCallback | None
+    on_complete: Callback | None
     callback_task_id: str | None
     """The callback task, once the group has completed."""
     created_at: datetime
@@ -558,7 +614,7 @@ class Group:
             failed=d["failed"],
             cancelled=d["cancelled"],
             remaining=d["remaining"],
-            on_complete=None if cb is None else GroupCallback._from_json(cb),
+            on_complete=None if cb is None else Callback._from_json(cb),
             callback_task_id=d.get("callback_task_id"),
             created_at=_time(d["created_at"]),
             closed_at=_opt_time(d.get("closed_at")),

{workly-0.2.0 → workly-0.3.0}/src/workly/_requests.py

@@ -16,6 +16,7 @@ from urllib.parse import quote
 
 from ._models import (
     AlertChannelType,
+    Callback,
     GroupStatus,
     HTTPMethod,
     RunState,
@@ -73,16 +74,31 @@ class TaskSpec(TypedDict, total=False):
     max_attempts: int
     timeout_seconds: float
     group_id: str
+    on_complete: Callback | CallbackDict
 
 
-class GroupCallbackSpec(TypedDict, total=False):
-    """The `on_complete` callback of `groups.create`: a task to enqueue when the group completes."""
+class CallbackDict(TypedDict, total=False):
+    """A `Callback` as a dict, with the same fields."""
 
-    queue: Required[str]
     url: Required[str]
     headers: Mapping[str, str]
 
 
+GroupCallbackSpec = CallbackDict
+"""Deprecated: use `Callback` or `CallbackDict`."""
+
+
+def callback_body(cb: Callback | CallbackDict) -> dict[str, Any]:
+    if isinstance(cb, Callback):
+        url, headers = cb.url, cb.headers
+    else:
+        url, headers = cb["url"], cb.get("headers", {})
+    body: dict[str, Any] = {"url": url}
+    if headers:
+        body["headers"] = dict(headers)
+    return body
+
+
 def task_body(spec: Mapping[str, Any]) -> dict[str, Any]:
     body: dict[str, Any] = {}
     for key, value in spec.items():
@@ -92,6 +108,8 @@ def task_body(spec: Mapping[str, Any]) -> dict[str, Any]:
             value = _timestamp(value, "run_at")
         elif key == "headers":
             value = dict(value)
+        elif key == "on_complete":
+            value = callback_body(value)
         body[key] = value
     if "payload" in body and "body" in body:
         raise ValueError("pass payload or body, not both")
@@ -256,7 +274,7 @@ def retry_task(task_id: str) -> Request:
 
 
 def create_group(
-    name: str | None, idempotency_key: str | None, on_complete: GroupCallbackSpec | None
+    name: str | None, idempotency_key: str | None, on_complete: Callback | CallbackDict | None
 ) -> Request:
     body: dict[str, Any] = {}
     if name is not None:
@@ -264,10 +282,7 @@ def create_group(
     if idempotency_key is not None:
         body["idempotency_key"] = idempotency_key
     if on_complete is not None:
-        callback: dict[str, Any] = {"queue": on_complete["queue"], "url": on_complete["url"]}
-        if "headers" in on_complete:
-            callback["headers"] = dict(on_complete["headers"])
-        body["on_complete"] = callback
+        body["on_complete"] = callback_body(on_complete)
     return Request("POST", "/v1/groups", json=body, idempotent=idempotency_key is not None)
 
 
@@ -310,7 +325,11 @@ def put_schedule(name: str, config: Mapping[str, Any]) -> Request:
     for key, value in config.items():
         if value is None:
             continue
-        body[key] = dict(value) if key == "headers" else value
+        if key == "headers":
+            value = dict(value)
+        elif key == "on_complete":
+            value = callback_body(value)
+        body[key] = value
     if "payload" in body and "body" in body:
         raise ValueError("pass payload or body, not both")
     return Request("PUT", f"/v1/schedules/{_q(name)}", json=body, idempotent=True)
@@ -339,16 +358,18 @@ def trigger_schedule(name: str) -> Request:
 
 
 def list_runs(
-    name: str, *, state: RunState | None, cursor: str | None, limit: int | None
+    *, schedule: str | None, state: RunState | None, cursor: str | None, limit: int | None
 ) -> Request:
     params: dict[str, str] = {}
+    if schedule is not None:
+        params["schedule"] = schedule
     if state is not None:
         params["state"] = state
     if cursor is not None:
         params["cursor"] = cursor
     if limit is not None:
         params["limit"] = str(limit)
-    return Request("GET", f"/v1/schedules/{_q(name)}/runs", params=params, idempotent=True)
+    return Request("GET", "/v1/runs", params=params, idempotent=True)
 
 
 def get_run(run_id: str) -> Request: