pyquickbase 0.1.0a1__py3-none-any.whl

pyquickbase/_response.py

@@ -0,0 +1,90 @@
+"""Turn HTTP responses and failures into results or exceptions. No network access."""
+
+from typing import Any
+
+import httpx
+
+from ._retry import parse_retry_after
+from .errors import (
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    InvalidResponseError,
+    NetworkError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    RequestTimeoutError,
+    ServerError,
+)
+
+REQUEST_ID_HEADER = "qb-api-ray"
+_MAX_DETAIL_CHARS = 500
+_ERRORS_BY_STATUS: dict[int, type[APIError]] = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+}
+
+
+def _error_details(response: httpx.Response) -> tuple[str | None, str | None]:
+    """Return Quickbase's message and description, falling back to the raw body."""
+    try:
+        body: Any = response.json()
+    except ValueError:
+        return (response.text[:_MAX_DETAIL_CHARS] or None), None
+    if not isinstance(body, dict):
+        return None, None
+    details: dict[str, Any] = body  # pyright: ignore[reportUnknownVariableType]
+    message, description = details.get("message"), details.get("description")
+    return (
+        message[:_MAX_DETAIL_CHARS] if isinstance(message, str) and message else None,
+        description[:_MAX_DETAIL_CHARS] if isinstance(description, str) and description else None,
+    )
+
+
+def error_from_response(response: httpx.Response, method: str, path: str) -> APIError:
+    message, description = _error_details(response)
+    request_id = response.headers.get(REQUEST_ID_HEADER)
+    status = response.status_code
+    summary = f"Quickbase returned {status} for {method} {path}"
+    detail = ": ".join(part for part in (message, description) if part)
+    if detail:
+        summary += f": {detail}"
+    if request_id:
+        summary += f" (request ID: {request_id})"
+    common = {
+        "status_code": status,
+        "method": method,
+        "path": path,
+        "message": message,
+        "description": description,
+        "request_id": request_id,
+    }
+    if status == 429:
+        retry_after = parse_retry_after(response.headers.get("retry-after"))
+        return RateLimitError(summary, retry_after=retry_after, **common)
+    error_type = ServerError if status >= 500 else _ERRORS_BY_STATUS.get(status, APIError)
+    return error_type(summary, **common)  # type: ignore[arg-type]  # pyright: ignore[reportArgumentType]
+
+
+def parse_response(response: httpx.Response, method: str, path: str) -> Any:
+    """Return the decoded JSON body, None for an empty body, or raise the matching error."""
+    if not response.is_success:
+        raise error_from_response(response, method, path)
+    if not response.content:
+        return None
+    try:
+        return response.json()
+    except ValueError as exc:
+        raise InvalidResponseError(
+            f"Quickbase returned a non-JSON body for {method} {path}."
+        ) from exc
+
+
+def error_from_transport(exc: httpx.TransportError, method: str, path: str) -> NetworkError:
+    reason = type(exc).__name__
+    if isinstance(exc, httpx.TimeoutException):
+        return RequestTimeoutError(f"{method} {path} timed out ({reason}).")
+    return NetworkError(f"Could not complete {method} {path} ({reason}).")

pyquickbase/_retry.py

@@ -0,0 +1,66 @@
+"""When to retry and how long to wait. Quickbase documents retrying only on HTTP 429.
+
+Connection failures are also retried, because the request never reached the server.
+Other failures are not: a timed-out or failed write may already have been applied.
+"""
+
+import random
+import re
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
+
+from .errors import ConfigurationError
+
+_SECONDS = re.compile(r"\d+(\.\d+)?")
+_MAX_EXPONENT = 32  # keeps 2**attempt from overflowing a float
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class RetryPolicy:
+    """How to retry rate-limited requests and connection failures.
+
+    Args:
+        max_retries: Retries after the first attempt. Use 0 to disable retrying.
+        base_delay: Starting backoff in seconds, when Quickbase doesn't specify a wait.
+        max_delay: Longest backoff in seconds.
+        max_retry_after: Raise `RateLimitError` rather than obey a longer `Retry-After`.
+    """
+
+    max_retries: int = 4
+    base_delay: float = 1.0
+    max_delay: float = 30.0
+    max_retry_after: float = 60.0
+
+    def __post_init__(self) -> None:
+        if self.max_retries < 0:
+            raise ConfigurationError("max_retries can't be negative.")
+        if self.base_delay < 0 or self.max_delay < 0 or self.max_retry_after < 0:
+            raise ConfigurationError("Retry delays can't be negative.")
+
+    def backoff(self, attempt: int) -> float:
+        """Exponential backoff with jitter, so parallel clients don't retry in lockstep."""
+        ceiling = min(self.max_delay, self.base_delay * 2 ** min(attempt, _MAX_EXPONENT))
+        return random.uniform(ceiling / 2, ceiling)
+
+    def rate_limit_delay(self, attempt: int, retry_after: float | None) -> float | None:
+        """Seconds to wait after a 429, or None if the wait is too long to be worth it."""
+        if retry_after is None:
+            return self.backoff(attempt)
+        return retry_after if retry_after <= self.max_retry_after else None
+
+
+def parse_retry_after(value: str | None, now: datetime | None = None) -> float | None:
+    """Parse a `Retry-After` header given as seconds or an HTTP date."""
+    if value is None:
+        return None
+    value = value.strip()
+    if _SECONDS.fullmatch(value):
+        return float(value)
+    try:
+        when = parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    if when.tzinfo is None:
+        when = when.replace(tzinfo=UTC)
+    return max(0.0, (when - (now or datetime.now(UTC))).total_seconds())

pyquickbase/_schema.py

@@ -0,0 +1,35 @@
+"""A small time-limited cache for app, table, and field metadata. No network access."""
+
+import threading
+import time
+from typing import Any
+
+
+class SchemaCache:
+    """Safe to share across threads, so one sync client can serve several of them."""
+
+    def __init__(self, ttl: float) -> None:
+        self._ttl = ttl
+        self._lock = threading.Lock()
+        self._entries: dict[str, tuple[float, Any]] = {}
+
+    def get(self, key: str) -> Any:
+        """Return the cached value, or None if it's missing or expired."""
+        with self._lock:
+            entry = self._entries.get(key)
+        if entry is None or time.monotonic() - entry[0] >= self._ttl:
+            return None
+        return entry[1]
+
+    def set(self, key: str, value: Any) -> None:
+        with self._lock:
+            self._entries[key] = (time.monotonic(), value)
+
+    def delete(self, *keys: str) -> None:
+        with self._lock:
+            for key in keys:
+                self._entries.pop(key, None)
+
+    def clear(self) -> None:
+        with self._lock:
+            self._entries.clear()

pyquickbase/_sync/_client.py

@@ -0,0 +1,152 @@
+# Generated from the async code by scripts/generate_sync.py. Do not edit.
+"""The async Quickbase client."""
+
+import re
+from collections.abc import Collection, Mapping
+from types import TracebackType
+from typing import Any, Self
+
+import httpx
+
+from .._auth import UserTokenAuth
+from .._config import (
+    DEFAULT_BASE_URL,
+    DEFAULT_TIMEOUT,
+    build_user_agent,
+    normalize_allowed_writes,
+    normalize_realm,
+    read_env,
+    validate_base_url,
+    validate_token,
+)
+from .._retry import RetryPolicy
+from .._schema import SchemaCache
+from ..errors import ConfigurationError
+from ._resources import App
+from ._transport import Transport
+
+DEFAULT_SCHEMA_TTL = 300.0
+_APP_ID = re.compile(r"[A-Za-z0-9]+")
+
+
+class Quickbase:
+    """A Quickbase API client. Use it as a context manager so connections get closed.
+
+    Args:
+        realm: Your realm, as `acme`, `acme.quickbase.com`, or a realm URL.
+        token: A Quickbase user token.
+        base_url: The API root. Must use HTTPS, except for loopback addresses.
+        retry: How to retry rate limits and connection failures.
+        timeout: Request timeout in seconds. Ignored if you pass `http_client`.
+        user_agent: Identifies your application, placed before the SDK's own User-Agent.
+        http_client: Your own configured httpx client, for proxies, custom TLS, event hooks,
+            or custom transports. You remain responsible for closing it.
+        schema_ttl: Seconds to cache app, table, and field metadata. Use 0 to disable caching.
+        read_only: Refuse any request that could change data, raising `ReadOnlyError`. Only GET
+            requests and record queries are sent, including through `request()`.
+        allowed_writes: Like `read_only`, but also allow these `(method, path)` pairs, such as
+            `{("POST", "/records")}`. Paths must match exactly.
+    """
+
+    def __init__(
+        self,
+        *,
+        realm: str,
+        token: str,
+        base_url: str = DEFAULT_BASE_URL,
+        retry: RetryPolicy | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        user_agent: str | None = None,
+        http_client: httpx.Client | None = None,
+        schema_ttl: float = DEFAULT_SCHEMA_TTL,
+        read_only: bool = False,
+        allowed_writes: Collection[tuple[str, str]] | None = None,
+    ) -> None:
+        self._realm = normalize_realm(realm)
+        self._transport = Transport(
+            realm=self._realm,
+            auth=UserTokenAuth(validate_token(token)),
+            base_url=validate_base_url(base_url),
+            retry=RetryPolicy() if retry is None else retry,
+            timeout=timeout,
+            user_agent=build_user_agent(user_agent),
+            http_client=http_client,
+            allowed_writes=normalize_allowed_writes(read_only, allowed_writes),
+        )
+        self._schema = SchemaCache(schema_ttl)
+
+    @classmethod
+    def from_env(
+        cls,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        retry: RetryPolicy | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        user_agent: str | None = None,
+        http_client: httpx.Client | None = None,
+        schema_ttl: float = DEFAULT_SCHEMA_TTL,
+        read_only: bool = False,
+        allowed_writes: Collection[tuple[str, str]] | None = None,
+    ) -> Self:
+        """Create a client from the `QB_REALM` and `QB_USER_TOKEN` environment variables."""
+        realm, token = read_env()
+        return cls(
+            realm=realm,
+            token=token,
+            base_url=base_url,
+            retry=retry,
+            timeout=timeout,
+            user_agent=user_agent,
+            http_client=http_client,
+            schema_ttl=schema_ttl,
+            read_only=read_only,
+            allowed_writes=allowed_writes,
+        )
+
+    @property
+    def realm(self) -> str:
+        """The full realm hostname, such as `acme.quickbase.com`."""
+        return self._realm
+
+    def app(self, app_id: str) -> App:
+        """Get an app by ID, the `bq...` part of its URL. This makes no network calls."""
+        if not _APP_ID.fullmatch(app_id):
+            raise ConfigurationError("An app ID contains only letters and numbers.")
+        return App(self._transport, self._schema, app_id)
+
+    def clear_schema_cache(self) -> None:
+        """Forget cached metadata, for example after changing a table's fields."""
+        self._schema.clear()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any = None,
+    ) -> Any:
+        """Call any Quickbase endpoint directly and return its decoded JSON body.
+
+        This is the escape hatch for endpoints without a dedicated method. `path` is relative
+        to the API root, such as `/tables/abc123`, and the body is None if the response is empty.
+        """
+        return self._transport.request(method, path, params=params, json=json)
+
+    def close(self) -> None:
+        """Close connections. Safe to call more than once."""
+        self._transport.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(realm={self._realm!r})"