workly 0.2.0__tar.gz → 0.2.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: workly
-Version: 0.2.0
+Version: 0.2.1
 Summary: Python SDK for Workly, the open-source HTTP task queue
 Keywords: task queue,background jobs,webhooks,http
 License-Expression: Apache-2.0
@@ -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://docs.workly.run/groups/). The callback goes to Workly's `_callbacks` queue unless it names a `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(

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

@@ -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://docs.workly.run/groups/). The callback goes to Workly's `_callbacks` queue unless it names a `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(

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

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

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

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

{workly-0.2.0 → workly-0.2.1}/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.2.1}/src/workly/_async_client.py

@@ -17,6 +17,7 @@ from ._models import (
     AlertChannelList,
     AlertChannelType,
     Attempt,
+    Callback,
     CronPreview,
     Delivery,
     EnqueueResult,
@@ -370,13 +371,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)

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

@@ -17,6 +17,7 @@ from ._models import (
     AlertChannelList,
     AlertChannelType,
     Attempt,
+    Callback,
     CronPreview,
     Delivery,
     EnqueueResult,
@@ -369,13 +370,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)

{workly-0.2.0 → workly-0.2.1}/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
 
@@ -510,17 +511,33 @@ 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.
+
+    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.
+    """
 
-    queue: str
     url: str
-    headers: dict[str, 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]) -> 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"], queue=d.get("queue") or CALLBACK_QUEUE, headers=d.get("headers") or {}
+        )
+
+
+GroupCallback = Callback
+"""Deprecated: use `Callback`."""
 
 
 @dataclass(frozen=True, slots=True)
@@ -537,7 +554,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 +575,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.2.1}/src/workly/_requests.py

@@ -15,7 +15,9 @@ from typing import Any, Required, TypedDict
 from urllib.parse import quote
 
 from ._models import (
+    CALLBACK_QUEUE,
     AlertChannelType,
+    Callback,
     GroupStatus,
     HTTPMethod,
     RunState,
@@ -75,14 +77,31 @@ class TaskSpec(TypedDict, total=False):
     group_id: str
 
 
-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]
+    queue: 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, queue, headers = cb.url, cb.queue, cb.headers
+    else:
+        url, queue, headers = cb["url"], cb.get("queue", CALLBACK_QUEUE), cb.get("headers", {})
+    body: dict[str, Any] = {"url": url}
+    if queue != CALLBACK_QUEUE:
+        body["queue"] = queue
+    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():
@@ -256,7 +275,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 +283,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)