gushwork-argus 0.1.0__py3-none-any.whl

gushwork_argus/__init__.py

@@ -0,0 +1,78 @@
+"""Python client for Argus, Gushwork's image ingestion and search API."""
+
+from ._client import Argus, AsyncArgus
+from ._version import __version__
+from .errors import (
+    APIConnectionError,
+    APIResponseValidationError,
+    APIStatusError,
+    APITimeoutError,
+    ArgusError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    IngestionTimeoutError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    UnprocessableEntityError,
+    UploadError,
+)
+from .models import (
+    CursorPage,
+    DoorMatches,
+    Image,
+    ImageAdded,
+    ImageFile,
+    ImageProgress,
+    ImageStatus,
+    IndexState,
+    Ingestion,
+    Namespace,
+    PageAdded,
+    PageType,
+    SearchFilters,
+    SearchMode,
+    SearchResponse,
+    SearchResult,
+    Usage,
+)
+
+__all__ = [
+    "APIConnectionError",
+    "APIResponseValidationError",
+    "APIStatusError",
+    "APITimeoutError",
+    "Argus",
+    "ArgusError",
+    "AsyncArgus",
+    "AuthenticationError",
+    "BadRequestError",
+    "ConflictError",
+    "CursorPage",
+    "DoorMatches",
+    "Image",
+    "ImageAdded",
+    "ImageFile",
+    "ImageProgress",
+    "ImageStatus",
+    "IndexState",
+    "Ingestion",
+    "IngestionTimeoutError",
+    "InternalServerError",
+    "Namespace",
+    "NotFoundError",
+    "PageAdded",
+    "PageType",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "SearchFilters",
+    "SearchMode",
+    "SearchResponse",
+    "SearchResult",
+    "UnprocessableEntityError",
+    "UploadError",
+    "Usage",
+    "__version__",
+]

gushwork_argus/_client.py

@@ -0,0 +1,88 @@
+"""The two entry points: Argus (blocking) and AsyncArgus (asyncio). Same methods on both."""
+
+from __future__ import annotations
+
+import httpx
+
+from ._http import DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, AsyncTransport, Settings, SyncTransport
+from .resources import (
+    AsyncImages,
+    AsyncIngestions,
+    AsyncNamespaces,
+    AsyncPages,
+    Images,
+    Ingestions,
+    Namespaces,
+    Pages,
+)
+
+
+class Argus:
+    """A client for the Argus API.
+
+        argus = Argus(api_key="...", base_url="https://<argus host>")
+        namespace = argus.namespaces.create(slug="acme", name="Acme Dental")
+
+    `api_key` and `base_url` fall back to ARGUS_API_KEY and ARGUS_BASE_URL. `timeout` is
+    per request, in seconds. `max_retries` covers connection errors, timeouts, 429 and
+    502/503/504. Pass `http_client` only for proxies or custom transports. Reuse one client
+    per process; it holds a connection pool. Close it with `close()` or a `with` block.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        settings = Settings.resolve(api_key, base_url, timeout, max_retries)
+        self._transport = SyncTransport(settings, http_client)
+        self.namespaces = Namespaces(self._transport)
+        self.pages = Pages(self._transport)
+        self.images = Images(self._transport)
+        self.ingestions = Ingestions(self._transport)
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> Argus:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+
+class AsyncArgus:
+    """The asyncio client: the same methods as `Argus`, awaited.
+
+    async with AsyncArgus(api_key="...", base_url="https://<argus host>") as argus:
+        namespace = await argus.namespaces.get(namespace_id)
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        settings = Settings.resolve(api_key, base_url, timeout, max_retries)
+        self._transport = AsyncTransport(settings, http_client)
+        self.namespaces = AsyncNamespaces(self._transport)
+        self.pages = AsyncPages(self._transport)
+        self.images = AsyncImages(self._transport)
+        self.ingestions = AsyncIngestions(self._transport)
+
+    async def close(self) -> None:
+        await self._transport.close()
+
+    async def __aenter__(self) -> AsyncArgus:
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.close()

gushwork_argus/_http.py

@@ -0,0 +1,273 @@
+"""Sending requests: the API key, retries with backoff, responses as models or exceptions.
+
+SyncTransport and AsyncTransport are the only classes that do I/O. They mirror each other
+line for line; a change to one is a change to both.
+
+Argus writes are keyed by slug, content hash or image source, so sending one twice is
+harmless: those requests are retried on connection errors, timeouts, 429 and 502/503/504.
+A search is not a write but costs model calls each time it runs, so it is only retried
+when it certainly never reached Argus (`resend=False`).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import random
+import time
+from dataclasses import dataclass, field
+from typing import Any, TypeVar
+from urllib.parse import quote
+
+import httpx
+from pydantic import BaseModel, ValidationError
+
+from ._upload import Payload, UploadTarget
+from ._version import __version__
+from .errors import (
+    APIConnectionError,
+    APIResponseValidationError,
+    APITimeoutError,
+    UploadError,
+    status_error,
+)
+
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 2
+
+_RESEND_STATUSES = frozenset({429, 502, 503, 504})
+# Answers that mean the request was turned away before any work was done.
+_NOT_PROCESSED_STATUSES = frozenset({429})
+_NOT_SENT_ERRORS = (httpx.ConnectError, httpx.ConnectTimeout)
+_MAX_DELAY = 8.0
+_log = logging.getLogger("gushwork_argus")
+
+M = TypeVar("M", bound=BaseModel)
+
+
+@dataclass(frozen=True)
+class Settings:
+    # Kept out of repr so a logged or captured Settings never shows the key.
+    api_key: str = field(repr=False)
+    base_url: str
+    timeout: float
+    max_retries: int
+
+    @classmethod
+    def resolve(
+        cls, api_key: str | None, base_url: str | None, timeout: float, max_retries: int
+    ) -> Settings:
+        """Arguments first, then ARGUS_API_KEY / ARGUS_BASE_URL from the environment."""
+        api_key = api_key or os.environ.get("ARGUS_API_KEY")
+        base_url = base_url or os.environ.get("ARGUS_BASE_URL")
+        if not api_key:
+            raise ValueError("api_key is required: pass api_key= or set ARGUS_API_KEY")
+        if not base_url:
+            raise ValueError("base_url is required: pass base_url= or set ARGUS_BASE_URL")
+        if max_retries < 0:
+            raise ValueError("max_retries can't be negative")
+        return cls(api_key, base_url.rstrip("/"), timeout, max_retries)
+
+    @property
+    def headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "User-Agent": f"gushwork-argus-python/{__version__}",
+            "Accept": "application/json",
+        }
+
+
+def path(*segments: str) -> str:
+    """`/v1/a/b` with each segment escaped, so an id can never change the route."""
+    return "/v1/" + "/".join(quote(segment, safe="") for segment in segments)
+
+
+def without_none(values: dict[str, Any]) -> dict[str, Any]:
+    return {key: value for key, value in values.items() if value is not None}
+
+
+def retry_delay(attempt: int, response: httpx.Response | None) -> float:
+    """Exponential backoff with jitter; a numeric Retry-After from the server wins."""
+    retry_after = response.headers.get("Retry-After", "") if response is not None else ""
+    if retry_after.isdigit():
+        return min(float(retry_after), _MAX_DELAY)
+    return min(_MAX_DELAY, 0.5 * 2**attempt) * random.uniform(0.5, 1.0)
+
+
+def _should_retry(outcome: httpx.Response | httpx.TransportError, resend: bool) -> bool:
+    if isinstance(outcome, httpx.TransportError):
+        return resend or isinstance(outcome, _NOT_SENT_ERRORS)
+    return outcome.status_code in (_RESEND_STATUSES if resend else _NOT_PROCESSED_STATUSES)
+
+
+def _connection_error(exc: httpx.TransportError) -> APIConnectionError:
+    message = str(exc) or type(exc).__name__
+    if isinstance(exc, httpx.TimeoutException):
+        return APITimeoutError(message)
+    return APIConnectionError(message)
+
+
+def _parse(response: httpx.Response, cast_to: type[M]) -> M:
+    """The response as `cast_to`, or the matching ArgusError."""
+    if response.is_error:
+        raise status_error(response)
+    try:
+        return cast_to.model_validate(response.json())
+    except (ValueError, ValidationError) as exc:
+        raise APIResponseValidationError(response, str(exc)) from exc
+
+
+def _check_upload(response: httpx.Response) -> None:
+    if response.is_error:
+        raise UploadError(response.status_code, response.text)
+
+
+def _log_retry(method: str, url: str, attempt: int, delay: float, reason: str) -> None:
+    _log.info("retrying %s %s in %.1fs (attempt %d): %s", method, url, delay, attempt + 1, reason)
+
+
+class SyncTransport:
+    def __init__(self, settings: Settings, http_client: httpx.Client | None = None) -> None:
+        self._settings = settings
+        self._client = http_client or httpx.Client()
+        self._owns_client = http_client is None
+        # S3 gets its own client and never sees the API key. Like any httpx client it
+        # honours HTTPS_PROXY / SSL_CERT_FILE from the environment.
+        self._s3 = httpx.Client()
+
+    def request(
+        self,
+        method: str,
+        route: str,
+        cast_to: type[M],
+        *,
+        json: Any = None,
+        params: dict[str, Any] | None = None,
+        resend: bool = True,
+    ) -> M:
+        response = self._send(
+            self._client,
+            method,
+            self._settings.base_url + route,
+            resend,
+            headers=self._settings.headers,
+            json=json,
+            params=without_none(params or {}),
+        )
+        return _parse(response, cast_to)
+
+    def upload(self, namespace_id: str, payload: Payload) -> str:
+        """Put the bytes in the Argus bucket through a presigned POST; returns the s3:// uri."""
+        target = self.request(
+            "POST", path("uploads"), UploadTarget, json={"namespace_id": namespace_id}
+        )
+        target.check(payload)
+        response = self._send(
+            self._s3,
+            "POST",
+            target.url,
+            True,
+            data=target.fields,
+            files={"file": (payload.filename, payload.data)},
+        )
+        _check_upload(response)
+        return target.uri
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+        self._s3.close()
+
+    def _send(
+        self, client: httpx.Client, method: str, url: str, resend: bool, **kwargs: Any
+    ) -> httpx.Response:
+        attempt = 0
+        while True:
+            try:
+                response = client.request(method, url, timeout=self._settings.timeout, **kwargs)
+            except httpx.TransportError as exc:
+                if attempt >= self._settings.max_retries or not _should_retry(exc, resend):
+                    raise _connection_error(exc) from exc
+                delay, reason = retry_delay(attempt, None), type(exc).__name__
+            else:
+                if attempt >= self._settings.max_retries or not _should_retry(response, resend):
+                    return response
+                delay, reason = retry_delay(attempt, response), str(response.status_code)
+            _log_retry(method, url, attempt, delay, reason)
+            time.sleep(delay)
+            attempt += 1
+
+
+class AsyncTransport:
+    def __init__(self, settings: Settings, http_client: httpx.AsyncClient | None = None) -> None:
+        self._settings = settings
+        self._client = http_client or httpx.AsyncClient()
+        self._owns_client = http_client is None
+        # S3 gets its own client and never sees the API key. Like any httpx client it
+        # honours HTTPS_PROXY / SSL_CERT_FILE from the environment.
+        self._s3 = httpx.AsyncClient()
+
+    async def request(
+        self,
+        method: str,
+        route: str,
+        cast_to: type[M],
+        *,
+        json: Any = None,
+        params: dict[str, Any] | None = None,
+        resend: bool = True,
+    ) -> M:
+        response = await self._send(
+            self._client,
+            method,
+            self._settings.base_url + route,
+            resend,
+            headers=self._settings.headers,
+            json=json,
+            params=without_none(params or {}),
+        )
+        return _parse(response, cast_to)
+
+    async def upload(self, namespace_id: str, payload: Payload) -> str:
+        """Put the bytes in the Argus bucket through a presigned POST; returns the s3:// uri."""
+        target = await self.request(
+            "POST", path("uploads"), UploadTarget, json={"namespace_id": namespace_id}
+        )
+        target.check(payload)
+        response = await self._send(
+            self._s3,
+            "POST",
+            target.url,
+            True,
+            data=target.fields,
+            files={"file": (payload.filename, payload.data)},
+        )
+        _check_upload(response)
+        return target.uri
+
+    async def close(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+        await self._s3.aclose()
+
+    async def _send(
+        self, client: httpx.AsyncClient, method: str, url: str, resend: bool, **kwargs: Any
+    ) -> httpx.Response:
+        attempt = 0
+        while True:
+            try:
+                response = await client.request(
+                    method, url, timeout=self._settings.timeout, **kwargs
+                )
+            except httpx.TransportError as exc:
+                if attempt >= self._settings.max_retries or not _should_retry(exc, resend):
+                    raise _connection_error(exc) from exc
+                delay, reason = retry_delay(attempt, None), type(exc).__name__
+            else:
+                if attempt >= self._settings.max_retries or not _should_retry(response, resend):
+                    return response
+                delay, reason = retry_delay(attempt, response), str(response.status_code)
+            _log_retry(method, url, attempt, delay, reason)
+            await asyncio.sleep(delay)
+            attempt += 1

gushwork_argus/_pagination.py

@@ -0,0 +1,33 @@
+"""Walking every page of a list by following `next_cursor`."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterator
+from typing import TypeVar
+
+from .models import CursorPage
+
+T = TypeVar("T")
+
+
+def iterate(fetch: Callable[[str | None], CursorPage[T]]) -> Iterator[T]:
+    """Every item across pages. `fetch(cursor)` returns one page; None asks for the first."""
+    cursor: str | None = None
+    while True:
+        page = fetch(cursor)
+        yield from page.items
+        if page.next_cursor is None:
+            return
+        cursor = page.next_cursor
+
+
+async def aiterate(fetch: Callable[[str | None], Awaitable[CursorPage[T]]]) -> AsyncIterator[T]:
+    """Every item across pages. `fetch(cursor)` returns one page; None asks for the first."""
+    cursor: str | None = None
+    while True:
+        page = await fetch(cursor)
+        for item in page.items:
+            yield item
+        if page.next_cursor is None:
+            return
+        cursor = page.next_cursor

gushwork_argus/_upload.py

@@ -0,0 +1,87 @@
+"""Turning what a caller has (a path, text, bytes, an open file) into bytes to upload.
+
+No I/O against Argus or S3 happens here; the transports do that.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import BinaryIO, Union
+
+from pydantic import BaseModel
+
+from .models import PageType
+
+PageContent = Union[str, bytes, "os.PathLike[str]"]
+FileContent = Union[bytes, "os.PathLike[str]", BinaryIO]
+
+_PAGE_TYPES: dict[str, PageType] = {
+    ".md": "md",
+    ".markdown": "md",
+    ".html": "html",
+    ".htm": "html",
+}
+
+
+@dataclass(frozen=True)
+class Payload:
+    data: bytes
+    filename: str
+
+    @property
+    def content_hash(self) -> str:
+        """How Argus recognises a page it has seen before, and checks it arrived intact."""
+        return "sha256:" + hashlib.sha256(self.data).hexdigest()
+
+
+class UploadTarget(BaseModel):
+    """A presigned S3 POST from `POST /v1/uploads`: where to send the file, and its s3:// uri."""
+
+    url: str
+    fields: dict[str, str]
+    uri: str
+    max_bytes: int
+
+    def check(self, payload: Payload) -> None:
+        size = len(payload.data)
+        if size == 0:
+            raise ValueError(f"{payload.filename} is empty")
+        if size > self.max_bytes:
+            raise ValueError(
+                f"{payload.filename} is {size} bytes; Argus accepts up to {self.max_bytes}"
+            )
+
+
+def page_payload(content: PageContent, page_type: PageType | None) -> tuple[Payload, PageType]:
+    """A page as bytes plus its type: given, or read from a Path's extension."""
+    inferred: PageType | None = None
+    if isinstance(content, os.PathLike):
+        path = Path(content)
+        data, filename = path.read_bytes(), path.name
+        inferred = _PAGE_TYPES.get(path.suffix.lower())
+    elif isinstance(content, str):
+        data, filename = content.encode("utf-8"), "page"
+    else:
+        data, filename = content, "page"
+
+    resolved = page_type or inferred
+    if resolved not in ("html", "md"):
+        raise ValueError("pass type='html' or type='md' (only a .md/.html Path can be inferred)")
+    return Payload(data, filename), resolved
+
+
+def file_payload(file: FileContent) -> Payload:
+    """An image file as bytes: from a Path, raw bytes, or an open binary file."""
+    if isinstance(file, os.PathLike):
+        path = Path(file)
+        return Payload(path.read_bytes(), path.name)
+    if isinstance(file, bytes):
+        return Payload(file, "image")
+    data = file.read()
+    # Typed as bytes, but a file opened in text mode hands back str.
+    if not isinstance(data, bytes):  # pyright: ignore[reportUnnecessaryIsInstance]
+        raise TypeError("open the file in binary mode ('rb')")
+    return Payload(data, Path(str(getattr(file, "name", "image"))).name)

gushwork_argus/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"