workly 0.4.0__tar.gz → 0.4.3__tar.gz

{workly-0.4.0 → workly-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: workly
-Version: 0.4.0
+Version: 0.4.3
 Summary: Python SDK for Workly, the open-source HTTP task queue
 Keywords: task queue,background jobs,webhooks,http
 License-Expression: Apache-2.0
@@ -27,7 +27,7 @@ pip install workly          # the SDK
 pip install "workly[cli]"   # the SDK plus the workly binary, for `workly dev`
 ```
 
-Requires Python 3.11+. The only dependency is [httpx](https://www.python-httpx.org). The `cli` extra adds [`workly-cli`](https://pypi.org/project/workly-cli/), the server binary (about 7 MB), which you usually want on dev machines and not in production images.
+Requires Python 3.11+. The only dependency is [httpx](https://www.python-httpx.org). The `cli` extra adds [`workly-cli`](https://pypi.org/project/workly-cli/), the `workly` binary (about 7 MB): the dev server (`workly dev`) and the CLI, including `workly validate`, `plan` and `deploy` for [configuration as code](https://workly.run/docs/deploy/). Install it on dev machines and in CI; production images that only enqueue tasks don't need it.
 
 ## Quickstart
 
@@ -186,24 +186,27 @@ Runs are delivered with `Workly-Run-Id`, `Workly-Schedule` and `Workly-Scheduled
 
 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.
 
+`groups.enqueue` does the whole job in one call: it creates the group, enqueues the tasks into it in batches of 100 and closes it, and it's safe to retry with the same `idempotency_key`.
+
 ```python
 from workly import Callback
 
-group = client.groups.create(
+group = client.groups.enqueue(
+    "stock-prices",
+    (
+        {"url": "https://api.example.com/jobs/update-stock-price", "payload": {"symbol": c.symbol}}
+        for c in companies
+    ),
     name="daily-stock-prices",
-    idempotency_key="stock-prices-2026-10-19",  # creating it again returns this group
+    idempotency_key="stock-prices-2026-10-19",  # a retry finishes this group rather than start another
     # 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(
-        "stock-prices",
-        url="https://api.example.com/jobs/update-stock-price",
-        payload={"symbol": company.symbol},
-        group_id=group.id,
-    )
-client.groups.close(group.id)  # no more tasks; it completes once they've finished
+```
 
+Or step by step: `client.groups.create(...)`, then `client.tasks.enqueue(..., group_id=group.id)` or `enqueue_many` for each task, then `client.groups.close(group.id)`, after which it completes once its tasks have finished.
+
+```python
 group = client.groups.get(group.id)
 print(group.status, group.total, group.succeeded, group.failed, group.remaining)
 for task in client.tasks.list(group_id=group.id, state="failed"):

{workly-0.4.0 → workly-0.4.3}/README.md

@@ -7,7 +7,7 @@ pip install workly          # the SDK
 pip install "workly[cli]"   # the SDK plus the workly binary, for `workly dev`
 ```
 
-Requires Python 3.11+. The only dependency is [httpx](https://www.python-httpx.org). The `cli` extra adds [`workly-cli`](https://pypi.org/project/workly-cli/), the server binary (about 7 MB), which you usually want on dev machines and not in production images.
+Requires Python 3.11+. The only dependency is [httpx](https://www.python-httpx.org). The `cli` extra adds [`workly-cli`](https://pypi.org/project/workly-cli/), the `workly` binary (about 7 MB): the dev server (`workly dev`) and the CLI, including `workly validate`, `plan` and `deploy` for [configuration as code](https://workly.run/docs/deploy/). Install it on dev machines and in CI; production images that only enqueue tasks don't need it.
 
 ## Quickstart
 
@@ -166,24 +166,27 @@ Runs are delivered with `Workly-Run-Id`, `Workly-Schedule` and `Workly-Scheduled
 
 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.
 
+`groups.enqueue` does the whole job in one call: it creates the group, enqueues the tasks into it in batches of 100 and closes it, and it's safe to retry with the same `idempotency_key`.
+
 ```python
 from workly import Callback
 
-group = client.groups.create(
+group = client.groups.enqueue(
+    "stock-prices",
+    (
+        {"url": "https://api.example.com/jobs/update-stock-price", "payload": {"symbol": c.symbol}}
+        for c in companies
+    ),
     name="daily-stock-prices",
-    idempotency_key="stock-prices-2026-10-19",  # creating it again returns this group
+    idempotency_key="stock-prices-2026-10-19",  # a retry finishes this group rather than start another
     # 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(
-        "stock-prices",
-        url="https://api.example.com/jobs/update-stock-price",
-        payload={"symbol": company.symbol},
-        group_id=group.id,
-    )
-client.groups.close(group.id)  # no more tasks; it completes once they've finished
+```
 
+Or step by step: `client.groups.create(...)`, then `client.tasks.enqueue(..., group_id=group.id)` or `enqueue_many` for each task, then `client.groups.close(group.id)`, after which it completes once its tasks have finished.
+
+```python
 group = client.groups.get(group.id)
 print(group.status, group.total, group.succeeded, group.failed, group.remaining)
 for task in client.tasks.list(group_id=group.id, state="failed"):

{workly-0.4.0 → workly-0.4.3}/pyproject.toml

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

{workly-0.4.0 → workly-0.4.3}/pyproject.toml.orig

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

{workly-0.4.0 → workly-0.4.3}/src/workly/_async_client.py

@@ -393,6 +393,37 @@ class AsyncGroups:
         req = r.create_group(name, idempotency_key, on_complete)
         return Group._from_json(await self._client._send(req))
 
+    async def enqueue(
+        self,
+        queue: str,
+        tasks: Iterable[r.TaskSpec],
+        *,
+        name: str | None = None,
+        idempotency_key: str | None = None,
+        on_complete: Callback | r.CallbackDict | None = None,
+        traceparent: str | None = None,
+    ) -> Group:
+        """Create a group, enqueue `tasks` into it and close it: the whole job in one call.
+
+        Tasks go in batches of 100, each joining the group. Returns the closed
+        group, which completes (and enqueues `on_complete`) once its tasks
+        have finished.
+
+        Safe to retry with the same `idempotency_key` and tasks: the group is
+        found again instead of created, a task without its own
+        `idempotency_key` gets one from the group and its position so none is
+        enqueued twice, and a group that is already closed is returned as it
+        is. Without `idempotency_key`, a retry starts a second group.
+        """
+        group = await self.create(
+            name=name, idempotency_key=idempotency_key, on_complete=on_complete
+        )
+        if group.status != "open":
+            return group
+        for batch in r.group_batches(group.id, tasks):
+            await self._client.tasks.enqueue_many(queue, batch, traceparent=traceparent)
+        return await self.close(group.id)
+
     async def get(self, group_id: str) -> Group:
         return Group._from_json(await self._client._send(r.get_group(group_id)))
 

{workly-0.4.0 → workly-0.4.3}/src/workly/_client.py

@@ -392,6 +392,35 @@ class Groups:
         req = r.create_group(name, idempotency_key, on_complete)
         return Group._from_json(self._client._send(req))
 
+    def enqueue(
+        self,
+        queue: str,
+        tasks: Iterable[r.TaskSpec],
+        *,
+        name: str | None = None,
+        idempotency_key: str | None = None,
+        on_complete: Callback | r.CallbackDict | None = None,
+        traceparent: str | None = None,
+    ) -> Group:
+        """Create a group, enqueue `tasks` into it and close it: the whole job in one call.
+
+        Tasks go in batches of 100, each joining the group. Returns the closed
+        group, which completes (and enqueues `on_complete`) once its tasks
+        have finished.
+
+        Safe to retry with the same `idempotency_key` and tasks: the group is
+        found again instead of created, a task without its own
+        `idempotency_key` gets one from the group and its position so none is
+        enqueued twice, and a group that is already closed is returned as it
+        is. Without `idempotency_key`, a retry starts a second group.
+        """
+        group = self.create(name=name, idempotency_key=idempotency_key, on_complete=on_complete)
+        if group.status != "open":
+            return group
+        for batch in r.group_batches(group.id, tasks):
+            self._client.tasks.enqueue_many(queue, batch, traceparent=traceparent)
+        return self.close(group.id)
+
     def get(self, group_id: str) -> Group:
         return Group._from_json(self._client._send(r.get_group(group_id)))
 

{workly-0.4.0 → workly-0.4.3}/src/workly/_requests.py

@@ -7,7 +7,7 @@ send it and decode the response, so the two stay in step.
 from __future__ import annotations
 
 import os
-from collections.abc import Mapping
+from collections.abc import Iterable, Iterator, Mapping
 from dataclasses import dataclass, field
 from datetime import datetime
 from importlib.metadata import PackageNotFoundError, version
@@ -529,3 +529,26 @@ def cancel_workflow_run(run_id: str) -> Request:
 def retry_workflow_run(run_id: str) -> Request:
     # Not idempotent: once it is running again, retrying is invalid_state.
     return Request("POST", f"/v1/workflow-runs/{_q(run_id)}/retry")
+
+
+# The most tasks one batch enqueue takes.
+MAX_BATCH = 100
+
+
+def group_batches(group_id: str, specs: Iterable[TaskSpec]) -> Iterator[list[TaskSpec]]:
+    """Split a group's tasks into batches, each task joining the group.
+
+    A task without an idempotency key gets one from the group and its
+    position, so enqueueing the same tasks again (a retry) adds none twice.
+    """
+    batch: list[TaskSpec] = []
+    for i, spec in enumerate(specs):
+        task = TaskSpec(**spec)
+        task["group_id"] = group_id
+        task.setdefault("idempotency_key", f"{group_id}:{i}")
+        batch.append(task)
+        if len(batch) == MAX_BATCH:
+            yield batch
+            batch = []
+    if batch:
+        yield batch