workly 0.1.0__py3-none-any.whl

workly/_client.py

@@ -0,0 +1,490 @@
+from __future__ import annotations
+
+import time
+from collections.abc import Iterable, Iterator, Mapping
+from datetime import datetime
+from types import TracebackType
+from typing import Any, Self
+
+import httpx
+
+from . import _requests as r
+from . import _transport as t
+from ._models import (
+    Activity,
+    ActivityRange,
+    AlertChannel,
+    AlertChannelList,
+    AlertChannelType,
+    Attempt,
+    CronPreview,
+    Delivery,
+    EnqueueResult,
+    FailureGroup,
+    HTTPMethod,
+    MissedPolicy,
+    OverlapPolicy,
+    Queue,
+    QueueActivity,
+    Run,
+    RunPage,
+    RunState,
+    Schedule,
+    Task,
+    TaskPage,
+    TaskState,
+)
+
+
+class Workly:
+    """Client for the Workly API.
+
+    `url` defaults to `WORKLY_URL`, then http://localhost:7337 (`workly dev`).
+    `api_key` defaults to `WORKLY_API_KEY`; `workly dev` needs none.
+
+    Use it as a context manager, or call `close()`, to release connections.
+    """
+
+    def __init__(
+        self,
+        url: str | None = None,
+        api_key: str | None = None,
+        *,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._config = r.client_config(url, api_key)
+        self._http = http_client or httpx.Client(timeout=timeout)
+        self._owns_http = http_client is None
+        self._max_retries = max_retries
+        self.queues = Queues(self)
+        self.tasks = Tasks(self)
+        self.schedules = Schedules(self)
+        self.runs = Runs(self)
+        self.alerts = Alerts(self)
+
+    @property
+    def url(self) -> str:
+        return self._config.base_url
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def _send(self, req: r.Request) -> Any:
+        attempt = 0
+        while True:
+            try:
+                response = self._http.request(
+                    req.method,
+                    self._config.base_url + req.path,
+                    params=req.params,
+                    json=req.json,
+                    headers={**self._config.headers, **req.headers},
+                )
+            except httpx.TransportError as exc:
+                if attempt < self._max_retries and t.retry_after_error(req, exc):
+                    time.sleep(t.delay(attempt))
+                    attempt += 1
+                    continue
+                raise t.connection_error(req, exc) from exc
+            if attempt < self._max_retries and t.retry_after_status(req, response):
+                time.sleep(t.delay(attempt, response))
+                attempt += 1
+                continue
+            return t.decode(response)
+
+
+class Queues:
+    def __init__(self, client: Workly) -> None:
+        self._client = client
+
+    def list(self) -> list[Queue]:
+        """All queues, by name, with their stats."""
+        data = self._client._send(r.list_queues())
+        return [Queue._from_json(q) for q in data["queues"]]
+
+    def get(self, name: str) -> Queue:
+        return Queue._from_json(self._client._send(r.get_queue(name)))
+
+    def put(
+        self,
+        name: str,
+        *,
+        max_attempts: int | None = None,
+        min_backoff_seconds: float | None = None,
+        max_backoff_seconds: float | None = None,
+        backoff_multiplier: float | None = None,
+        timeout_seconds: float | None = None,
+        retry_on_4xx: bool | None = None,
+        rate_per_second: float | None = None,
+        max_concurrency: int | None = None,
+    ) -> Queue:
+        """Create or update a queue.
+
+        Declarative: the queue ends up with exactly this configuration, and
+        omitted settings are reset to their defaults. It doesn't change
+        whether the queue is paused.
+        """
+        config = dict(
+            max_attempts=max_attempts,
+            min_backoff_seconds=min_backoff_seconds,
+            max_backoff_seconds=max_backoff_seconds,
+            backoff_multiplier=backoff_multiplier,
+            timeout_seconds=timeout_seconds,
+            retry_on_4xx=retry_on_4xx,
+            rate_per_second=rate_per_second,
+            max_concurrency=max_concurrency,
+        )
+        return Queue._from_json(self._client._send(r.put_queue(name, config)))
+
+    def delete(self, name: str) -> None:
+        """Delete a queue and all its tasks."""
+        self._client._send(r.delete_queue(name))
+
+    def pause(self, name: str) -> Queue:
+        """Stop dispatching. In-flight deliveries finish; enqueueing still works."""
+        return Queue._from_json(self._client._send(r.pause_queue(name)))
+
+    def resume(self, name: str) -> Queue:
+        return Queue._from_json(self._client._send(r.resume_queue(name)))
+
+    def cancel_pending(self, name: str) -> int:
+        """Cancel the queue's pending tasks, including scheduled ones. Returns how many.
+
+        Running tasks finish. Cancelled tasks stay in the history and can be retried.
+        """
+        data = self._client._send(r.cancel_pending_tasks(name))
+        return int(data["cancelled"])
+
+    def failures(self, name: str, *, limit: int | None = None) -> list[FailureGroup]:
+        """The queue's failed tasks grouped by error, most common first (default: 10 groups)."""
+        data = self._client._send(r.get_queue_failures(name, limit))
+        return [FailureGroup._from_json(g) for g in data["groups"]]
+
+    def activity(self, name: str, *, since: datetime | None = None) -> QueueActivity:
+        """Count the queue's tasks that finished since `since` (default: 7 days ago), by state."""
+        return QueueActivity._from_json(self._client._send(r.get_queue_activity(name, since)))
+
+    def retry_failed(self, name: str, *, last_error: str | None = None) -> int:
+        """Retry the failed tasks in the queue now, e.g. after an outage.
+
+        Each task gets a fresh set of attempts. With `last_error`, only tasks
+        that failed with exactly that error (a group from `failures`) are
+        retried. Returns how many were retried.
+        """
+        data = self._client._send(r.retry_failed_tasks(name, last_error))
+        return int(data["retried"])
+
+
+class Tasks:
+    def __init__(self, client: Workly) -> None:
+        self._client = client
+
+    def enqueue(
+        self,
+        queue: str,
+        *,
+        url: str,
+        payload: Any = None,
+        body: str | None = None,
+        content_type: str | None = None,
+        method: HTTPMethod | None = None,
+        headers: Mapping[str, str] | None = None,
+        delay_seconds: float | None = None,
+        run_at: datetime | None = None,
+        idempotency_key: str | None = None,
+        max_attempts: int | None = None,
+        timeout_seconds: float | None = None,
+        traceparent: str | None = None,
+    ) -> Task:
+        """Enqueue a task to deliver to `url`.
+
+        `payload` is sent as JSON; `body` as raw text (use one). The queue is
+        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.
+        """
+        spec = {
+            "url": url,
+            "payload": payload,
+            "body": body,
+            "content_type": content_type,
+            "method": method,
+            "headers": headers,
+            "delay_seconds": delay_seconds,
+            "run_at": run_at,
+            "idempotency_key": idempotency_key,
+            "max_attempts": max_attempts,
+            "timeout_seconds": timeout_seconds,
+        }
+        return Task._from_json(self._client._send(r.enqueue(queue, spec, traceparent)))
+
+    def enqueue_many(
+        self, queue: str, tasks: Iterable[r.TaskSpec], *, traceparent: str | None = None
+    ) -> list[EnqueueResult]:
+        """Enqueue up to 100 tasks at once: all of them, or none if any is invalid."""
+        data = self._client._send(r.enqueue_many(queue, list(tasks), traceparent))
+        return [
+            EnqueueResult(created=res["created"], task=Task._from_json(res["task"]))
+            for res in data["results"]
+        ]
+
+    def get(self, task_id: str) -> Task:
+        return Task._from_json(self._client._send(r.get_task(task_id)))
+
+    def attempts(self, task_id: str) -> list[Attempt]:
+        """The task's delivery attempts, oldest first."""
+        data = self._client._send(r.list_attempts(task_id))
+        return [Attempt._from_json(a) for a in data["attempts"]]
+
+    def delivery(self, task_id: str) -> Delivery:
+        """The request that delivers the task, as it would be sent now and freshly signed.
+
+        Nothing is sent. Useful to replay a delivery by hand while fixing an endpoint.
+        """
+        return Delivery._from_json(self._client._send(r.get_task_delivery(task_id)))
+
+    def cancel(self, task_id: str) -> Task:
+        """Cancel a pending or running task. A running attempt finishes but isn't retried."""
+        return Task._from_json(self._client._send(r.cancel_task(task_id)))
+
+    def retry(self, task_id: str) -> Task:
+        """Make the task due now. A finished task is replayed with fresh attempts."""
+        return Task._from_json(self._client._send(r.retry_task(task_id)))
+
+    def list(
+        self,
+        *,
+        queue: str | None = None,
+        state: TaskState | None = None,
+        idempotency_key: str | None = None,
+        last_error: str | None = None,
+        created_after: datetime | None = None,
+        created_before: datetime | None = None,
+        page_size: int | None = None,
+    ) -> Iterator[Task]:
+        """Tasks matching every filter given, newest first, fetching pages as needed."""
+        cursor: str | None = None
+        while True:
+            page = self.list_page(
+                queue=queue,
+                state=state,
+                idempotency_key=idempotency_key,
+                last_error=last_error,
+                created_after=created_after,
+                created_before=created_before,
+                cursor=cursor,
+                limit=page_size,
+            )
+            yield from page.tasks
+            if page.next_cursor is None:
+                return
+            cursor = page.next_cursor
+
+    def list_page(
+        self,
+        *,
+        queue: str | None = None,
+        state: TaskState | None = None,
+        idempotency_key: str | None = None,
+        last_error: str | None = None,
+        created_after: datetime | None = None,
+        created_before: datetime | None = None,
+        cursor: str | None = None,
+        limit: int | None = None,
+    ) -> TaskPage:
+        """One page of `list`. Pass the previous page's `next_cursor` as `cursor`."""
+        req = r.search_tasks(
+            queue=queue,
+            state=state,
+            idempotency_key=idempotency_key,
+            last_error=last_error,
+            created_after=created_after,
+            created_before=created_before,
+            cursor=cursor,
+            limit=limit,
+        )
+        return TaskPage._from_json(self._client._send(req))
+
+    def activity(self, *, range: ActivityRange | None = None) -> Activity:
+        """Count the workspace's tasks created over time, by queue (default range: 24h).
+
+        Buckets are 5 minutes for 1h, 1 hour for 24h and 6 hours for 7d, aligned to UTC.
+        """
+        return Activity._from_json(self._client._send(r.get_activity(range)))
+
+
+class Schedules:
+    """Cron schedules that call an endpoint. Separate from queues: each call is a run."""
+
+    def __init__(self, client: Workly) -> None:
+        self._client = client
+
+    def list(self) -> list[Schedule]:
+        """All schedules, by name, with their next and last run."""
+        data = self._client._send(r.list_schedules())
+        return [Schedule._from_json(s) for s in data["schedules"]]
+
+    def get(self, name: str) -> Schedule:
+        return Schedule._from_json(self._client._send(r.get_schedule(name)))
+
+    def put(
+        self,
+        name: str,
+        *,
+        cron: str,
+        url: str,
+        timezone: str | None = None,
+        payload: Any = None,
+        body: str | None = None,
+        content_type: str | None = None,
+        method: HTTPMethod | None = None,
+        headers: Mapping[str, str] | None = None,
+        timeout_seconds: float | None = None,
+        max_attempts: int | None = None,
+        min_backoff_seconds: float | None = None,
+        max_backoff_seconds: float | None = None,
+        backoff_multiplier: float | None = None,
+        retry_on_4xx: bool | None = None,
+        overlap: OverlapPolicy | None = None,
+        missed: MissedPolicy | 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.
+        """
+        config = dict(
+            cron=cron,
+            url=url,
+            timezone=timezone,
+            payload=payload,
+            body=body,
+            content_type=content_type,
+            method=method,
+            headers=headers,
+            timeout_seconds=timeout_seconds,
+            max_attempts=max_attempts,
+            min_backoff_seconds=min_backoff_seconds,
+            max_backoff_seconds=max_backoff_seconds,
+            backoff_multiplier=backoff_multiplier,
+            retry_on_4xx=retry_on_4xx,
+            overlap=overlap,
+            missed=missed,
+        )
+        return Schedule._from_json(self._client._send(r.put_schedule(name, config)))
+
+    def delete(self, name: str) -> None:
+        """Delete a schedule and all its runs."""
+        self._client._send(r.delete_schedule(name))
+
+    def pause(self, name: str) -> Schedule:
+        """Stop the schedule from firing. Runs in flight finish; `trigger` still works."""
+        return Schedule._from_json(self._client._send(r.pause_schedule(name)))
+
+    def resume(self, name: str) -> Schedule:
+        """Fire again from the next slot. Slots that passed while paused aren't run."""
+        return Schedule._from_json(self._client._send(r.resume_schedule(name)))
+
+    def preview_cron(self, cron: str, *, timezone: str | 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.
+        """
+        return CronPreview._from_json(self._client._send(r.preview_cron(cron, timezone)))
+
+    def trigger(self, name: str) -> Run:
+        """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
+    ) -> Iterator[Run]:
+        """The schedule's runs, newest first, fetching pages as needed."""
+        cursor: str | None = None
+        while True:
+            page = self.runs_page(name, 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(
+        self,
+        name: str,
+        *,
+        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)
+        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)))
+
+    def attempts(self, run_id: str) -> list[Attempt]:
+        """The run's delivery attempts, oldest first."""
+        data = self._client._send(r.list_run_attempts(run_id))
+        return [Attempt._from_json(a) for a in data["attempts"]]
+
+    def delivery(self, run_id: str) -> Delivery:
+        """The request that delivers the run, as it would be sent now and freshly signed."""
+        return Delivery._from_json(self._client._send(r.get_run_delivery(run_id)))
+
+    def cancel(self, run_id: str) -> Run:
+        """Cancel a pending or running run. A running attempt finishes but isn't retried."""
+        return Run._from_json(self._client._send(r.cancel_run(run_id)))
+
+    def retry(self, run_id: str) -> Run:
+        """Deliver the run now. A finished or skipped run gets fresh attempts."""
+        return Run._from_json(self._client._send(r.retry_run(run_id)))
+
+
+class Alerts:
+    """Where alerts about failed tasks and schedule runs go: email or Slack.
+
+    When tasks in a queue or runs of a schedule fail, every channel gets an
+    alert within about a minute, then at most one every 30 minutes per queue
+    or schedule.
+    """
+
+    def __init__(self, client: Workly) -> None:
+        self._client = client
+
+    def list(self) -> AlertChannelList:
+        """The workspace's channels, oldest first, and whether email can be sent."""
+        return AlertChannelList._from_json(self._client._send(r.list_alert_channels()))
+
+    def create(self, type: AlertChannelType, target: str) -> AlertChannel:
+        """Add a channel: an email address, or a Slack incoming webhook URL."""
+        return AlertChannel._from_json(self._client._send(r.create_alert_channel(type, target)))
+
+    def delete(self, channel_id: str) -> None:
+        self._client._send(r.delete_alert_channel(channel_id))
+
+    def test(self, channel_id: str) -> None:
+        """Send a test alert to the channel now. Raises APIError (alert_failed) if it can't."""
+        self._client._send(r.test_alert_channel(channel_id))

workly/_errors.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+
+class WorklyError(Exception):
+    """Base class for every error the SDK raises."""
+
+
+class APIConnectionError(WorklyError):
+    """The server couldn't be reached, or the connection failed mid-request."""
+
+
+class APIError(WorklyError):
+    """The server answered with an error.
+
+    `code` is stable and machine-readable (e.g. `queue_not_found`);
+    `message` is for humans.
+    """
+
+    def __init__(self, status: int, code: str, message: str) -> None:
+        super().__init__(f"{code}: {message} (HTTP {status})")
+        self.status = status
+        self.code = code
+        self.message = message
+
+
+class BadRequestError(APIError):
+    """400: the request was invalid."""
+
+
+class AuthenticationError(APIError):
+    """401: the API key is missing or wrong."""
+
+
+class PermissionDeniedError(APIError):
+    """403: not allowed, or a limit was reached, e.g. a hosted workspace's monthly task quota."""
+
+
+class NotFoundError(APIError):
+    """404: the queue or task doesn't exist."""
+
+
+class ConflictError(APIError):
+    """409: the task is in the wrong state, e.g. retrying a running task."""
+
+
+class PayloadTooLargeError(APIError):
+    """413: the task body is over the server's limit."""
+
+
+class RateLimitError(APIError):
+    """429: too many requests; retried automatically (`max_retries`) before this is raised."""
+
+
+class SignatureVerificationError(WorklyError):
+    """A delivery's signature is missing, wrong or too old."""
+
+
+_BY_STATUS: dict[int, type[APIError]] = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    413: PayloadTooLargeError,
+    429: RateLimitError,
+}
+
+
+def api_error(status: int, code: str, message: str) -> APIError:
+    return _BY_STATUS.get(status, APIError)(status, code, message)