workly 0.2.1__tar.gz → 0.4.0__tar.gz

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

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: workly
-Version: 0.2.1
+Version: 0.4.0
 Summary: Python SDK for Workly, the open-source HTTP task queue
 Keywords: task queue,background jobs,webhooks,http
 License-Expression: Apache-2.0
 License-File: LICENSE
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Framework :: AsyncIO
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
@@ -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.4.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.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "workly"
-version = "0.2.1"
+version = "0.4.0"
 description = "Python SDK for Workly, the open-source HTTP task queue"
 readme = "README.md"
 license = "Apache-2.0"
@@ -14,7 +14,7 @@ keywords = [
     "http",
 ]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 5 - Production/Stable",
     "Framework :: AsyncIO",
     "Intended Audience :: Developers",
     "Programming Language :: Python :: 3",

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

@@ -1,6 +1,6 @@
 [project]
 name = "workly"
-version = "0.2.1"
+version = "0.4.0"
 description = "Python SDK for Workly, the open-source HTTP task queue"
 readme = "README.md"
 license = "Apache-2.0"
@@ -9,7 +9,7 @@ requires-python = ">=3.11"
 dependencies = ["httpx>=0.27,<1"]
 keywords = ["task queue", "background jobs", "webhooks", "http"]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 5 - Production/Stable",
     "Framework :: AsyncIO",
     "Intended Audience :: Developers",
     "Programming Language :: Python :: 3",

{workly-0.2.1 → workly-0.4.0}/src/workly/__init__.py

@@ -7,9 +7,21 @@ from ._async_client import (
     AsyncRuns,
     AsyncSchedules,
     AsyncTasks,
+    AsyncWorkflowRuns,
+    AsyncWorkflows,
     AsyncWorkly,
 )
-from ._client import Alerts, Groups, Queues, Runs, Schedules, Tasks, Workly
+from ._client import (
+    Alerts,
+    Groups,
+    Queues,
+    Runs,
+    Schedules,
+    Tasks,
+    WorkflowRuns,
+    Workflows,
+    Workly,
+)
 from ._errors import (
     APIConnectionError,
     APIError,
@@ -34,6 +46,7 @@ from ._models import (
     AttemptOutcome,
     Callback,
     CronPreview,
+    CronSpan,
     Delivery,
     EnqueueResult,
     FailureGroup,
@@ -55,12 +68,23 @@ from ._models import (
     Schedule,
     SkipReason,
     SortOrder,
+    StepStatus,
     Task,
     TaskPage,
     TaskSort,
     TaskState,
+    TaskWorkflowStep,
+    WaitFor,
+    Workflow,
+    WorkflowRun,
+    WorkflowRunPage,
+    WorkflowRunStatus,
+    WorkflowRunSummary,
+    WorkflowStep,
+    WorkflowStepConfig,
+    WorkflowStepTask,
 )
-from ._requests import CallbackDict, GroupCallbackSpec, TaskSpec, __version__
+from ._requests import CallbackDict, GroupCallbackSpec, TaskSpec, WorkflowStepSpec, __version__
 from ._signing import sign, verify_signature
 
 __all__ = [
@@ -79,6 +103,8 @@ __all__ = [
     "AsyncRuns",
     "AsyncSchedules",
     "AsyncTasks",
+    "AsyncWorkflowRuns",
+    "AsyncWorkflows",
     "AsyncWorkly",
     "Attempt",
     "AttemptOutcome",
@@ -88,6 +114,7 @@ __all__ = [
     "CallbackDict",
     "ConflictError",
     "CronPreview",
+    "CronSpan",
     "Delivery",
     "EnqueueResult",
     "FailureGroup",
@@ -119,12 +146,26 @@ __all__ = [
     "SignatureVerificationError",
     "SkipReason",
     "SortOrder",
+    "StepStatus",
     "Task",
     "TaskPage",
     "TaskSort",
     "TaskSpec",
     "TaskState",
+    "TaskWorkflowStep",
     "Tasks",
+    "WaitFor",
+    "Workflow",
+    "WorkflowRun",
+    "WorkflowRunPage",
+    "WorkflowRunStatus",
+    "WorkflowRunSummary",
+    "WorkflowRuns",
+    "WorkflowStep",
+    "WorkflowStepConfig",
+    "WorkflowStepSpec",
+    "WorkflowStepTask",
+    "Workflows",
     "Workly",
     "WorklyError",
     "__version__",

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

@@ -39,6 +39,11 @@ from ._models import (
     TaskPage,
     TaskSort,
     TaskState,
+    Workflow,
+    WorkflowRun,
+    WorkflowRunPage,
+    WorkflowRunStatus,
+    WorkflowRunSummary,
 )
 
 
@@ -69,6 +74,8 @@ class AsyncWorkly:
         self.groups = AsyncGroups(self)
         self.schedules = AsyncSchedules(self)
         self.runs = AsyncRuns(self)
+        self.workflows = AsyncWorkflows(self)
+        self.workflow_runs = AsyncWorkflowRuns(self)
         self.alerts = AsyncAlerts(self)
 
     @property
@@ -216,6 +223,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 +232,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 +248,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)))
 
@@ -443,7 +453,8 @@ class AsyncSchedules:
         name: str,
         *,
         cron: str,
-        url: str,
+        url: str | None = None,
+        workflow: str | None = None,
         timezone: str | None = None,
         payload: Any = None,
         body: str | None = None,
@@ -458,16 +469,23 @@ 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).
 
+        With `workflow` instead of `url`, each run starts a run of that
+        workflow, with `payload` as its input.
+
         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,
             url=url,
+            workflow=workflow,
             timezone=timezone,
             payload=payload,
             body=body,
@@ -482,6 +500,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)))
 
@@ -497,49 +516,65 @@ class AsyncSchedules:
         """Fire again from the next slot. Slots that passed while paused aren't run."""
         return Schedule._from_json(await self._client._send(r.resume_schedule(name)))
 
-    async def preview_cron(self, cron: str, *, timezone: str | None = None) -> CronPreview:
+    async def preview_cron(
+        self,
+        cron: str,
+        *,
+        timezone: str | None = None,
+        from_: datetime | None = None,
+        until: datetime | None = None,
+    ) -> CronPreview:
         """The next 5 times a schedule with this cron would run, without creating it.
 
-        `timezone` is an IANA name; the default is UTC.
+        `timezone` is an IANA name; the default is UTC. With `from_` and `until` (at
+        most 35 days apart), `spans` lists every run in that window.
         """
-        return CronPreview._from_json(await self._client._send(r.preview_cron(cron, timezone)))
+        return CronPreview._from_json(
+            await self._client._send(r.preview_cron(cron, timezone, from_, until))
+        )
 
     async def trigger(self, name: str) -> Run:
         """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)))
 
@@ -588,3 +623,106 @@ class AsyncAlerts:
     async def test(self, channel_id: str) -> None:
         """Send a test alert to the channel now. Raises APIError (alert_failed) if it can't."""
         await self._client._send(r.test_alert_channel(channel_id))
+
+
+class AsyncWorkflows:
+    """Workflows: DAGs of HTTP steps, each delivered as a task once its dependencies succeed.
+
+    A step's endpoint can hand its completion to a task group by answering
+    2xx with `Workly-Wait-For: group/<id>`; the step then finishes when the
+    group does. Define workflows in workly.yaml (`workly deploy`) or with `put`.
+    """
+
+    def __init__(self, client: AsyncWorkly) -> None:
+        self._client = client
+
+    async def list(self) -> list[Workflow]:
+        """All workflows, by name, with their latest run."""
+        data = await self._client._send(r.list_workflows())
+        return [Workflow._from_json(w) for w in data["workflows"]]
+
+    async def get(self, name: str) -> Workflow:
+        return Workflow._from_json(await self._client._send(r.get_workflow(name)))
+
+    async def put(
+        self,
+        name: str,
+        *,
+        steps: list[r.WorkflowStepSpec],
+        max_duration_seconds: float | None = None,
+    ) -> Workflow:
+        """Create or update a workflow with exactly these steps.
+
+        Runs already started keep the definition they started with. A run
+        still going after `max_duration_seconds` (default a day) fails.
+        """
+        req = r.put_workflow(name, steps, max_duration_seconds)
+        return Workflow._from_json(await self._client._send(req))
+
+    async def delete(self, name: str) -> None:
+        """Delete the definition. Its runs are kept, and those going finish."""
+        await self._client._send(r.delete_workflow(name))
+
+    async def trigger(
+        self, name: str, *, input: Any = None, idempotency_key: str | None = None
+    ) -> WorkflowRun:
+        """Start a run. `input` (any JSON) is sent to every step without a body of its own.
+
+        With an `idempotency_key` already used for a run of this workflow,
+        that run is returned and nothing starts.
+        """
+        req = r.start_workflow_run(name, input, idempotency_key)
+        return WorkflowRun._from_json(await self._client._send(req))
+
+
+class AsyncWorkflowRuns:
+    """Runs of workflows, with each step's status, task and what it waits for."""
+
+    def __init__(self, client: AsyncWorkly) -> None:
+        self._client = client
+
+    async def list(
+        self,
+        *,
+        workflow: str | None = None,
+        status: WorkflowRunStatus | None = None,
+        page_size: int | None = None,
+    ) -> AsyncIterator[WorkflowRunSummary]:
+        """Runs of every workflow, or of one, newest first, fetching pages as needed."""
+        cursor: str | None = None
+        while True:
+            page = await self.list_page(
+                workflow=workflow, status=status, cursor=cursor, limit=page_size
+            )
+            for run in page.workflow_runs:
+                yield run
+            if page.next_cursor is None:
+                return
+            cursor = page.next_cursor
+
+    async def list_page(
+        self,
+        *,
+        workflow: str | None = None,
+        status: WorkflowRunStatus | None = None,
+        cursor: str | None = None,
+        limit: int | None = None,
+    ) -> WorkflowRunPage:
+        """One page of `list`. Pass the previous page's `next_cursor` as `cursor`."""
+        req = r.list_workflow_runs(workflow=workflow, status=status, cursor=cursor, limit=limit)
+        return WorkflowRunPage._from_json(await self._client._send(req))
+
+    async def get(self, run_id: str) -> WorkflowRun:
+        return WorkflowRun._from_json(await self._client._send(r.get_workflow_run(run_id)))
+
+    async def cancel(self, run_id: str) -> WorkflowRun:
+        """Stop a run: steps not yet started are skipped. Requests in flight finish."""
+        return WorkflowRun._from_json(await self._client._send(r.cancel_workflow_run(run_id)))
+
+    async def retry(self, run_id: str) -> WorkflowRun:
+        """Reopen a failed or cancelled run under the definition it started with.
+
+        Steps that succeeded stay; the rest run again, each on its old task with a
+        fresh set of attempts. A step that was waiting for a group follows the group.
+        """
+        return WorkflowRun._from_json(await self._client._send(r.retry_workflow_run(run_id)))