workly 0.2.1__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: workly
-Version: 0.2.1
+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,7 +184,7 @@ 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/). The callback goes to Workly's `_callbacks` queue unless it names a `queue`.
+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
@@ -212,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.1 → 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,7 +164,7 @@ 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/). The callback goes to Workly's `_callbacks` queue unless it names a `queue`.
+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
@@ -192,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.1 → workly-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "workly"
-version = "0.2.1"
+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.1 → workly-0.3.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "workly"
-version = "0.2.1"
+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.1 → workly-0.3.0}/src/workly/_async_client.py

@@ -216,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`.
@@ -224,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,
@@ -239,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)))
 
@@ -458,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,
@@ -482,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)))
 
@@ -508,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.1 → workly-0.3.0}/src/workly/_client.py

@@ -216,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`.
@@ -224,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,
@@ -239,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)))
 
@@ -456,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,
@@ -480,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)))
 
@@ -506,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.1 → workly-0.3.0}/src/workly/_models.py

@@ -66,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:
@@ -75,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"),
         )
 
 
@@ -226,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"],
@@ -252,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"),
         )
 
 
@@ -376,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"],
@@ -408,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),
         )
 
 
@@ -438,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:
@@ -463,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"),
         )
 
 
@@ -518,22 +560,19 @@ CALLBACK_QUEUE = "_callbacks"
 class Callback:
     """A task Workly enqueues when something completes: a POST to `url` saying what completed.
 
-    A group's callback has the group's summary as its JSON body. It is
-    delivered like any task in its queue, with that queue's retries.
+    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.
     """
 
     url: str
-    queue: str = CALLBACK_QUEUE
-    """The queue to enqueue the callback into. `_callbacks`, the default, is
-    created by Workly; configure it like any queue to change its retries."""
     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]) -> Callback:
-        return cls(
-            url=d["url"], queue=d.get("queue") or CALLBACK_QUEUE, headers=d.get("headers") or {}
-        )
+        return cls(url=d["url"], headers=d.get("headers") or {})
 
 
 GroupCallback = Callback

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

@@ -15,7 +15,6 @@ from typing import Any, Required, TypedDict
 from urllib.parse import quote
 
 from ._models import (
-    CALLBACK_QUEUE,
     AlertChannelType,
     Callback,
     GroupStatus,
@@ -75,13 +74,13 @@ class TaskSpec(TypedDict, total=False):
     max_attempts: int
     timeout_seconds: float
     group_id: str
+    on_complete: Callback | CallbackDict
 
 
 class CallbackDict(TypedDict, total=False):
     """A `Callback` as a dict, with the same fields."""
 
     url: Required[str]
-    queue: str
     headers: Mapping[str, str]
 
 
@@ -91,12 +90,10 @@ GroupCallbackSpec = CallbackDict
 
 def callback_body(cb: Callback | CallbackDict) -> dict[str, Any]:
     if isinstance(cb, Callback):
-        url, queue, headers = cb.url, cb.queue, cb.headers
+        url, headers = cb.url, cb.headers
     else:
-        url, queue, headers = cb["url"], cb.get("queue", CALLBACK_QUEUE), cb.get("headers", {})
+        url, headers = cb["url"], cb.get("headers", {})
     body: dict[str, Any] = {"url": url}
-    if queue != CALLBACK_QUEUE:
-        body["queue"] = queue
     if headers:
         body["headers"] = dict(headers)
     return body
@@ -111,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")
@@ -326,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)
@@ -355,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: