python-openarch-api 0.1.0__py3-none-any.whl

python_openarch_api/auth.py

@@ -0,0 +1,48 @@
+"""Authentication for OpenArch.
+
+A local OpenArch (its openarch-users.yml users) takes HTTP Basic; a hosted one takes a bearer JWT from
+its identity provider. A token can be a string or a callable returning the current token, so a
+caller that refreshes tokens hands the client a function instead of a value.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Generator
+
+import httpx
+
+TokenSource = str | Callable[[], str]
+
+
+class BearerAuth(httpx.Auth):
+    """``Authorization: Bearer <token>``, the token read on every request."""
+
+    def __init__(self, token: TokenSource):
+        self._token = token
+
+    def auth_flow(self, request: httpx.Request) -> Generator[httpx.Request, httpx.Response, None]:
+        token = self._token() if callable(self._token) else self._token
+        request.headers["Authorization"] = f"Bearer {token}"
+        yield request
+
+
+def build_auth(
+    *,
+    username: str | None = None,
+    password: str | None = None,
+    token: TokenSource | None = None,
+    auth: httpx.Auth | None = None,
+) -> httpx.Auth | None:
+    """One of: an ``httpx.Auth``, a bearer ``token``, or ``username`` + ``password`` (Basic)."""
+    given = [x for x in (auth, token, username) if x is not None]
+    if len(given) > 1:
+        raise ValueError("give one of auth, token, or username/password")
+    if auth is not None:
+        return auth
+    if token is not None:
+        return BearerAuth(token)
+    if username is not None:
+        if password is None:
+            raise ValueError("username needs a password")
+        return httpx.BasicAuth(username, password)
+    return None

python_openarch_api/errors.py

@@ -0,0 +1,52 @@
+"""Errors raised by the client."""
+
+from __future__ import annotations
+
+import httpx
+
+from .models.generated import RepositoryErrorResponse
+
+
+class OpenArchError(Exception):
+    """A non-2xx answer from OpenArch. ``error`` is the parsed error body when it had one."""
+
+    def __init__(self, response: httpx.Response, error: RepositoryErrorResponse | None = None):
+        self.response = response
+        self.status_code = response.status_code
+        self.error = error
+        detail = (error.message if error and error.message else response.text[:300]) or response.reason_phrase
+        super().__init__(f"{response.request.method} {response.request.url.path}: HTTP {self.status_code}: {detail}")
+
+    @classmethod
+    def from_response(cls, response: httpx.Response) -> OpenArchError:
+        error = None
+        try:
+            error = RepositoryErrorResponse.model_validate(response.json())
+        except ValueError:  # not JSON, or not the error shape (ValidationError is a ValueError)
+            pass
+        if response.status_code in (401, 403):
+            return OpenArchAuthError(response, error)
+        if response.status_code == 404:
+            return OpenArchNotFoundError(response, error)
+        if response.status_code == 409:
+            return OpenArchConflictError(response, error)
+        if response.status_code == 412:
+            return OpenArchPreconditionError(response, error)
+        return cls(response, error)
+
+
+class OpenArchAuthError(OpenArchError):
+    """401 / 403: missing, expired or insufficient credentials."""
+
+
+class OpenArchNotFoundError(OpenArchError):
+    """404: no such document, path, user, ..."""
+
+
+class OpenArchConflictError(OpenArchError):
+    """409: e.g. a ``set_*_v2`` whose ``version`` is stale (optimistic lock failure)."""
+
+
+class OpenArchPreconditionError(OpenArchError):
+    """412: a write's ``condition`` / ``if_`` did not match, or the document cannot do that
+    (checkin of a non-versionable document)."""

python_openarch_api/models/__init__.py

@@ -0,0 +1,7 @@
+"""Pydantic v2 models: ``generated`` (from docs/openapi/openarch-api.yaml) and the hand-written
+``OpenArchDocument`` / ``OpenArchQueryResult`` (``document``)."""
+
+from .document import MIXIN_CIN_REMOTE, OpenArchDocument, OpenArchQueryResult, TermsBucket
+from .generated import *  # noqa: F403
+
+__all__ = ["MIXIN_CIN_REMOTE", "OpenArchDocument", "OpenArchQueryResult", "TermsBucket"]

python_openarch_api/models/document.py

@@ -0,0 +1,91 @@
+"""Hand-written Document and QueryResult.
+
+OpenArch documents carry dynamic properties beyond the ``sys_*`` ones in the OpenAPI schema -- the
+``cin_*`` fields of the ``CinRemote`` mixin, ``sysembed_*`` embeddings, and whatever the
+repository model adds. The generated ``Document`` keeps them only as untyped extras, and the
+generated ``QueryResult`` types its documents as that ``Document``. As in content-lake-app
+(``HxprDocument`` / ``HxprDocument.QueryResult`` in content-lake-core), these two are written by
+hand: ``OpenArchDocument`` types the known ``cin_*`` fields and still accepts any other property;
+``OpenArchQueryResult`` returns ``OpenArchDocument`` instances.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .generated import Document, QueryResult
+
+# Mixin that owns the cin_* fields: OpenArch rejects a document carrying any of them (400, naming the
+# field) unless sys_mixinTypes includes it.
+MIXIN_CIN_REMOTE = "CinRemote"
+
+
+class OpenArchDocument(Document):
+    """A document: the schema's ``sys_*`` fields, the ``CinRemote`` ``cin_*`` fields, and any
+    other property (``doc.properties`` / ``doc.get("my_prop")``)."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    # CinRemote: the source-system identity and metadata of an ingested document
+    cin_id: str | None = None
+    """Id of the document in its source system (e.g. an Alfresco node id)."""
+    cin_source_id: Annotated[str | None, Field(alias="cin_sourceId")] = None
+    """Id of the source system (e.g. an Alfresco repository id)."""
+    cin_paths: list[str] | None = None
+    cin_ingest_properties: Annotated[dict[str, Any] | None, Field(alias="cin_ingestProperties")] = None
+    cin_ingest_property_names: Annotated[list[str] | None, Field(alias="cin_ingestPropertyNames")] = None
+    cin_read: list[str] | None = None
+    """Authorities that may read the document in its source system."""
+    cin_deny: list[str] | None = None
+    """Authorities denied reading it."""
+
+    @property
+    def properties(self) -> dict[str, Any]:
+        """The properties not declared on this class (repository-model fields, sysembed_*, ...),
+        under their wire names."""
+        return dict(self.model_extra or {})
+
+    def get(self, name: str, default: Any = None) -> Any:
+        """A property by its wire name (``sys_primaryType``, ``cin_sourceId``, ``my_field``)."""
+        for field_name, info in type(self).model_fields.items():
+            if name in (field_name, info.alias):
+                value = getattr(self, field_name)
+                return default if value is None else value
+        return (self.model_extra or {}).get(name, default)
+
+    def with_cin_remote(self) -> OpenArchDocument:
+        """This document with ``CinRemote`` in ``sys_mixinTypes`` (needed to write cin_* fields)."""
+        mixins = list(self.sys_mixin_types or [])
+        if MIXIN_CIN_REMOTE not in mixins:
+            mixins.append(MIXIN_CIN_REMOTE)
+        return self.model_copy(update={"sys_mixin_types": mixins})
+
+    def to_json(self) -> dict[str, Any]:
+        """The request body: wire names, unset and None fields left out."""
+        return self.model_dump(mode="json", by_alias=True, exclude_none=True)
+
+
+class TermsBucket(BaseModel):
+    """One terms-aggregation bucket. The spec's ``StringTermsBucket`` has no properties (springdoc
+    cannot see into the OpenSearch class), so the generated model would drop them."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    key: str | None = None
+    doc_count: Annotated[int | None, Field(alias="docCount")] = None
+
+
+class OpenArchQueryResult(QueryResult):
+    """A query result whose documents are :class:`OpenArchDocument`."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    documents: list[OpenArchDocument] | None = None  # type: ignore[assignment]
+    aggregations_buckets: Annotated[  # type: ignore[assignment]
+        list[TermsBucket] | None, Field(alias="aggregationsBuckets")
+    ] = None
+    # The Query schemas describe this cursor ("use the nextSearchAfter value from a previous
+    # response") but QueryResult does not declare it: pass it back as ``search_after``.
+    next_search_after: Annotated[str | None, Field(alias="nextSearchAfter")] = None