workwae 0.1.0a1__py3-none-any.whl

workwae/__init__.py

@@ -0,0 +1,52 @@
+"""workwae: a typed client for the Workwae /v1 API, plus cursor, error and webhook helpers.
+
+Every API model is in `workwae.types`, under the name the OpenAPI document gives it."""
+
+from . import types
+from ._client import AsyncWorkwae, Workwae
+from ._core import NOT_GIVEN, BinaryResponse, NotGiven, RequestOptions
+from ._errors import APIError, WorkwaeError
+from ._version import __version__
+from .pagination import AsyncChangeFeed, ChangeFeed, changes, pages, paginate
+from .types import EVENT_TYPES, ErrorReason, Event
+from .webhooks import (
+    MAX_SIGNATURE_CANDIDATES,
+    WEBHOOK_TOLERANCE_SECONDS,
+    UnknownEvent,
+    WebhookEvent,
+    WebhookVerificationError,
+    WebhookVerificationFailure,
+    check_webhook_signature,
+    parse_webhook,
+    verify_webhook,
+)
+
+__all__ = [
+    "EVENT_TYPES",
+    "MAX_SIGNATURE_CANDIDATES",
+    "NOT_GIVEN",
+    "WEBHOOK_TOLERANCE_SECONDS",
+    "APIError",
+    "AsyncChangeFeed",
+    "AsyncWorkwae",
+    "BinaryResponse",
+    "ChangeFeed",
+    "ErrorReason",
+    "Event",
+    "NotGiven",
+    "RequestOptions",
+    "UnknownEvent",
+    "WebhookEvent",
+    "WebhookVerificationError",
+    "WebhookVerificationFailure",
+    "Workwae",
+    "WorkwaeError",
+    "__version__",
+    "changes",
+    "check_webhook_signature",
+    "pages",
+    "paginate",
+    "parse_webhook",
+    "types",
+    "verify_webhook",
+]

workwae/_client.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+import asyncio
+import inspect
+import os
+import time
+from collections.abc import Mapping
+from types import TracebackType
+from typing import Any
+
+import httpx
+
+from ._core import (
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_MAX_RETRY_DELAY,
+    DEFAULT_TIMEOUT,
+    ApiKey,
+    AsyncApiKey,
+    BaseClient,
+    Operation,
+    RequestOptions,
+)
+from ._resources import AsyncResources, Resources
+
+# Module attributes rather than direct calls, so tests can stand in for the clock.
+_sleep = time.sleep
+_async_sleep = asyncio.sleep
+
+
+class Workwae(BaseClient, Resources):
+    """A client for the Workwae /v1 API: `Workwae(api_key=...).accounts.get(account_id=...)`.
+
+    `api_key` is an API key (`wk_...`) or an account token (`wat_...`), or a function returning
+    one per request, for tokens that are refreshed; it defaults to the WORKWAE_API_KEY environment
+    variable. `base_url` defaults to the hosted API; set it only to go through a proxy or gateway
+    of your own. `http_client` replaces the httpx.Client the client makes (proxies, transports,
+    tests); it is not closed by `close()`.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: ApiKey | None = None,
+        base_url: str | None = None,
+        headers: Mapping[str, str] | None = None,
+        timeout: float | httpx.Timeout = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        max_retry_delay: float = DEFAULT_MAX_RETRY_DELAY,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        BaseClient.__init__(
+            self,
+            base_url=base_url,
+            headers=headers,
+            timeout=timeout,
+            max_retries=max_retries,
+            max_retry_delay=max_retry_delay,
+        )
+        self._api_key = api_key if api_key is not None else os.environ.get("WORKWAE_API_KEY")
+        self._owns_http = http_client is None
+        self._http = http_client if http_client is not None else httpx.Client()
+        Resources.__init__(self)
+
+    def _call(
+        self, op: Operation, params: Mapping[str, Any], options: RequestOptions | None
+    ) -> Any:
+        key = self._api_key() if callable(self._api_key) else self._api_key
+        request = self._build(op, params, options, key)
+        attempt = 0
+        while True:
+            response = self._http.send(request)
+            delay = self._retry_delay(response, attempt)
+            if delay is None:
+                return self._decode(op, response)
+            response.close()
+            _sleep(delay)
+            attempt += 1
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> Workwae:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+class AsyncWorkwae(BaseClient, AsyncResources):
+    """The asyncio client: `await AsyncWorkwae(api_key=...).accounts.get(account_id=...)`. Takes
+    the same options as Workwae; `api_key` may also be an async function, and `http_client` an
+    httpx.AsyncClient."""
+
+    def __init__(
+        self,
+        *,
+        api_key: AsyncApiKey | None = None,
+        base_url: str | None = None,
+        headers: Mapping[str, str] | None = None,
+        timeout: float | httpx.Timeout = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        max_retry_delay: float = DEFAULT_MAX_RETRY_DELAY,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        BaseClient.__init__(
+            self,
+            base_url=base_url,
+            headers=headers,
+            timeout=timeout,
+            max_retries=max_retries,
+            max_retry_delay=max_retry_delay,
+        )
+        self._api_key = api_key if api_key is not None else os.environ.get("WORKWAE_API_KEY")
+        self._owns_http = http_client is None
+        self._http = http_client if http_client is not None else httpx.AsyncClient()
+        AsyncResources.__init__(self)
+
+    async def _call(
+        self, op: Operation, params: Mapping[str, Any], options: RequestOptions | None
+    ) -> Any:
+        key = self._api_key() if callable(self._api_key) else self._api_key
+        if inspect.isawaitable(key):
+            key = await key
+        request = self._build(op, params, options, key)
+        attempt = 0
+        while True:
+            response = await self._http.send(request)
+            delay = self._retry_delay(response, attempt)
+            if delay is None:
+                return self._decode(op, response)
+            await response.aclose()
+            await _async_sleep(delay)
+            attempt += 1
+
+    async def close(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncWorkwae:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.close()

workwae/_core.py

@@ -0,0 +1,263 @@
+# The transport both clients share: how an operation's keyword arguments become a request, how
+# 429 and 503 answers are retried, and how an answer becomes a model or an APIError. The
+# generated resources (_resources.py) only describe each operation as an Operation.
+from __future__ import annotations
+
+import email.utils
+import functools
+import json
+import random
+import re
+import uuid
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass, field
+from datetime import date, datetime, timezone
+from typing import Any, Protocol, TypedDict
+from urllib.parse import quote, unquote
+
+import httpx
+from pydantic import TypeAdapter
+
+from ._errors import APIError
+from ._version import __version__
+
+DEFAULT_BASE_URL = "https://api.workwae.com"
+DEFAULT_TIMEOUT = 60.0
+DEFAULT_MAX_RETRIES = 2
+DEFAULT_MAX_RETRY_DELAY = 60.0
+_BACKOFF_START = 0.5
+_RETRIED_STATUSES = (429, 503)
+
+
+class NotGiven:
+    """The default of every optional argument: the field is left out of the request, where None
+    sends null (which clears a nullable field on PATCH)."""
+
+    _instance: NotGiven | None = None
+
+    def __new__(cls) -> NotGiven:
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __bool__(self) -> bool:
+        return False
+
+    def __repr__(self) -> str:
+        return "NOT_GIVEN"
+
+
+NOT_GIVEN = NotGiven()
+
+
+class RequestOptions(TypedDict, total=False):
+    """Per-call options, passed as `request_options=`."""
+
+    idempotency_key: str
+    """The POST's Idempotency-Key. Without one, each POST call sends a key of its own, the same on
+    every automatic retry. Pass one to make retries of your own (a later process, a timeout)
+    answer what the first attempt did."""
+    timeout: float | httpx.Timeout
+    headers: Mapping[str, str]
+
+
+@dataclass(frozen=True)
+class BinaryResponse:
+    """An answer that is not JSON: a raw message, an attachment, a contact photo, an export."""
+
+    content: bytes
+    content_type: str | None
+    filename: str | None
+    headers: httpx.Headers = field(repr=False)
+
+
+@dataclass(frozen=True)
+class Operation:
+    """One /v1 operation. Keyword arguments named in `path` and `query` go there, under their
+    wire names; every other one is a body field, validated through `body`."""
+
+    method: str
+    path: str
+    path_params: Mapping[str, str] = field(default_factory=dict[str, str])
+    query_params: Mapping[str, str] = field(default_factory=dict[str, str])
+    body: Any = None
+    response: Any = None
+    binary: bool = False
+
+
+@functools.cache
+def adapter(tp: Any) -> TypeAdapter[Any]:
+    # Built on first use, so importing the package does not compile every model's schema.
+    return TypeAdapter(tp)
+
+
+def _query_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, datetime):
+        return value.isoformat()
+    if isinstance(value, date):
+        return value.isoformat()
+    return str(value)
+
+
+def _query(
+    op: Operation, params: Mapping[str, Any]
+) -> list[tuple[str, str | int | float | bool | None]]:
+    query: list[tuple[str, str | int | float | bool | None]] = []
+    for name, wire in op.query_params.items():
+        value = params.get(name, NOT_GIVEN)
+        if value is NOT_GIVEN or value is None:
+            continue
+        if isinstance(value, (list, tuple)):
+            # Bracket notation (`types[0]=...`), which the API reads arrays from.
+            items: list[Any] | tuple[Any, ...] = value  # pyright: ignore[reportUnknownVariableType]
+            query.extend((f"{wire}[{i}]", _query_value(item)) for i, item in enumerate(items))
+        else:
+            query.append((wire, _query_value(value)))
+    return query
+
+
+def _body(op: Operation, params: Mapping[str, Any]) -> bytes | None:
+    if op.body is None:
+        return None
+    reserved = op.path_params.keys() | op.query_params.keys()
+    given = {
+        name: value
+        for name, value in params.items()
+        if name not in reserved and value is not NOT_GIVEN
+    }
+    body_adapter = adapter(op.body)
+    model = body_adapter.validate_python(given)
+    data = body_adapter.dump_python(model, mode="json", by_alias=True, exclude_unset=True)
+    return json.dumps(data, separators=(",", ":")).encode()
+
+
+def parse_retry_after(value: str | None) -> float | None:
+    """Retry-After in seconds: delta seconds or an HTTP date; None when absent or unreadable."""
+    if value is None:
+        return None
+    value = value.strip()
+    if re.fullmatch(r"\d+(\.\d+)?", value):
+        return float(value)
+    try:
+        at = email.utils.parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    if at.tzinfo is None:
+        at = at.replace(tzinfo=timezone.utc)
+    return max(0.0, (at - datetime.now(timezone.utc)).total_seconds())
+
+
+def _filename(disposition: str | None) -> str | None:
+    if not disposition:
+        return None
+    match = re.search(
+        r"filename\*=UTF-8''([^;]+)|filename=\"([^\"]*)\"|filename=([^;]+)", disposition
+    )
+    if not match:
+        return None
+    encoded, quoted, bare = match.groups()
+    if encoded:
+        return unquote(encoded)
+    return quoted if quoted is not None else bare.strip()
+
+
+class BaseClient:
+    """What the sync and async clients share: options, request building and decoding."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str | None,
+        headers: Mapping[str, str] | None,
+        timeout: float | httpx.Timeout,
+        max_retries: int,
+        max_retry_delay: float,
+    ) -> None:
+        # The /v1 paths are appended to it, so a path prefix is kept.
+        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self.headers = dict(headers or {})
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.max_retry_delay = max_retry_delay
+
+    def _build(
+        self,
+        op: Operation,
+        params: Mapping[str, Any],
+        options: RequestOptions | None,
+        api_key: str | None,
+    ) -> httpx.Request:
+        options = options or {}
+        path = op.path
+        for name, wire in op.path_params.items():
+            path = path.replace("{" + wire + "}", quote(str(params[name]), safe=""))
+        headers = {
+            "accept": "application/json",
+            "user-agent": f"workwae-python/{__version__}",
+            **self.headers,
+            **options.get("headers", {}),
+        }
+        if api_key:
+            headers["authorization"] = f"Bearer {api_key}"
+        content = _body(op, params)
+        if content is not None:
+            headers["content-type"] = "application/json"
+        # One key for every attempt, so an attempt the API did act on is never acted on again.
+        if op.method == "POST":
+            key = options.get("idempotency_key") or headers.get("idempotency-key")
+            headers["idempotency-key"] = key or str(uuid.uuid4())
+        timeout = options.get("timeout", self.timeout)
+        return httpx.Request(
+            op.method,
+            self.base_url + path,
+            params=_query(op, params),
+            headers=headers,
+            content=content,
+            extensions={"timeout": httpx.Timeout(timeout).as_dict()},
+        )
+
+    def _retry_delay(self, response: httpx.Response, attempt: int) -> float | None:
+        """How long to wait before sending again, or None to return this answer. The API answers
+        429 and 503 before acting on the request, so sending it again cannot apply it twice. The
+        wait is Retry-After when the answer names one, else an exponential backoff with full
+        jitter on its upper half, which keeps clients that failed together from retrying
+        together."""
+        if attempt >= self.max_retries or response.status_code not in _RETRIED_STATUSES:
+            return None
+        retry_after = parse_retry_after(response.headers.get("retry-after"))
+        if retry_after is not None:
+            return None if retry_after > self.max_retry_delay else retry_after
+        backoff = _BACKOFF_START * 2**attempt * (0.5 + random.random() / 2)
+        return min(backoff, self.max_retry_delay)
+
+    def _decode(self, op: Operation, response: httpx.Response) -> Any:
+        if response.status_code >= 400:
+            raise APIError.from_response(response)
+        if op.binary:
+            return BinaryResponse(
+                content=response.content,
+                content_type=response.headers.get("content-type"),
+                filename=_filename(response.headers.get("content-disposition")),
+                headers=response.headers,
+            )
+        if op.response is None:
+            return None
+        return adapter(op.response).validate_json(response.content)
+
+
+ApiKey = str | Callable[[], str]
+AsyncApiKey = str | Callable[[], str | Awaitable[str]]
+
+
+class SyncCaller(Protocol):
+    def _call(
+        self, op: Operation, params: Mapping[str, Any], options: RequestOptions | None
+    ) -> Any: ...
+
+
+class AsyncCaller(Protocol):
+    def _call(
+        self, op: Operation, params: Mapping[str, Any], options: RequestOptions | None
+    ) -> Awaitable[Any]: ...

workwae/_errors.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import json
+from typing import Any, cast
+
+import httpx
+
+
+class WorkwaeError(Exception):
+    """Base of every error this package raises itself."""
+
+
+class APIError(WorkwaeError):
+    """A refusal the API answered with. `code` is the error's stable reason (`account_not_found`,
+    `invalid_input`, ...; see `workwae.types.ErrorReason`), `status` its HTTP status, `data` the
+    reason's details when it has any, and `request_id` the answer's X-Request-Id (quote it to
+    support). `defined` is true for a reason the operation declares.
+
+    An answer whose body is not an API error (a proxy's page, say) has `code` None."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int,
+        code: str | None,
+        data: Any = None,
+        defined: bool = False,
+        request_id: str | None = None,
+        headers: httpx.Headers | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.data = data
+        self.defined = defined
+        self.request_id = request_id
+        self.headers = headers if headers is not None else httpx.Headers()
+
+    def __repr__(self) -> str:
+        return (
+            f"APIError(status={self.status}, code={self.code!r}, message={self.message!r}, "
+            f"request_id={self.request_id!r})"
+        )
+
+    @classmethod
+    def from_response(cls, response: httpx.Response) -> APIError:
+        request_id = response.headers.get("x-request-id")
+        try:
+            body: Any = json.loads(response.content)
+        except ValueError:
+            body = None
+        fields = cast(dict[str, Any], body) if isinstance(body, dict) else {}
+        if isinstance(fields.get("code"), str):
+            message = fields.get("message")
+            return cls(
+                message if isinstance(message, str) else fields["code"],
+                status=response.status_code,
+                code=fields["code"],
+                data=fields.get("data"),
+                defined=fields.get("defined") is True,
+                request_id=request_id,
+                headers=response.headers,
+            )
+        return cls(
+            f"HTTP {response.status_code} {response.reason_phrase}".strip(),
+            status=response.status_code,
+            code=None,
+            request_id=request_id,
+            headers=response.headers,
+        )

workwae/_models.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+import pydantic
+
+
+class Model(pydantic.BaseModel):
+    """Base of every API model. Fields are snake_case and read their camelCase wire names; either
+    is accepted when building one. Fields the API adds after this SDK version are kept."""
+
+    model_config = pydantic.ConfigDict(
+        extra="allow",
+        validate_by_name=True,
+        validate_by_alias=True,
+        serialize_by_alias=True,
+        # Built on first use: importing the package does not compile every model's schema.
+        defer_build=True,
+    )