holder-python 0.2.5__py3-none-any.whl

holder/__init__.py

@@ -0,0 +1,21 @@
+"""Holder Python Library - control your knowledge using Python."""
+
+from .client import Holder
+from .models import (
+    Card,
+    CardSearchResult,
+    HierarchyRepair,
+    Project,
+    RepairedCard,
+    Tag,
+)
+
+__all__ = [
+    "Card",
+    "CardSearchResult",
+    "HierarchyRepair",
+    "Holder",
+    "Project",
+    "RepairedCard",
+    "Tag",
+]

holder/client.py

@@ -0,0 +1,182 @@
+"""Connection and request handling for the synchronous Holder client."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from collections.abc import Iterator
+from typing import Any, Self
+
+import httpx
+
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    ClosedError,
+    ConnectionError,
+    NotFoundError,
+    ProtocolError,
+)
+from .generated import AuthenticatedClient
+from .generated.models import ErrorResponse
+from .models.project import Project, ProjectCollection
+
+
+class Holder:
+    """Control your local knowledge, or connect with an explicit URL/token pair.
+
+    Use as a context manager. Collection queries run only when consumed.
+    Local discovery requires holderctl on PATH (or the holderctl argument).
+    """
+
+    def __init__(
+        self,
+        *,
+        url: str | None = None,
+        token: str | None = None,
+        holderctl: str = "holderctl",
+        timeout: float | httpx.Timeout = 10.0,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        if (url is None) != (token is None):
+            raise ValueError("Supply url and token together, or omit both")
+        self._url = url
+        self._token = token
+        self._local = url is None
+        self._holderctl = holderctl
+        self._timeout = timeout
+        self._transport = transport
+        self._client: AuthenticatedClient | None = None
+        self._closed = False
+        self.projects = ProjectCollection(self)
+
+    def _command(self, *args: str) -> str:
+        try:
+            result = subprocess.run(
+                [self._holderctl, *args],
+                capture_output=True,
+                text=True,
+                timeout=65,
+                check=False,
+            )
+        except (OSError, subprocess.TimeoutExpired):
+            raise ConnectionError(
+                "Could not run holderctl; install Holder or supply url and token"
+            ) from None
+        if result.returncode:
+            # CLI output and stderr may contain local credentials; never echo them.
+            raise ConnectionError(
+                f"holderctl {args[0]} failed (exit {result.returncode})"
+            )
+        return result.stdout
+
+    def _discover(self) -> None:
+        try:
+            result = json.loads(
+                self._command(
+                    "ensure",
+                    "--json",
+                    "--api-min",
+                    "0.1",
+                    "--api-max-exclusive",
+                    "1.0",
+                )
+            )
+            url = result["daemon"]["url"]
+            if result.get("ok") is not True or not isinstance(url, str) or not url:
+                raise ValueError
+            token = self._command("token").strip()
+            if not token:
+                raise ValueError
+        except (ValueError, KeyError, TypeError):
+            raise ConnectionError(
+                "holderctl did not return valid daemon connection details"
+            ) from None
+        self._url, self._token = url, token
+
+    def _connect(self) -> None:
+        if self._local:
+            self._discover()
+        self._client = AuthenticatedClient(
+            base_url=self._url,
+            token=self._token,
+            timeout=httpx.Timeout(self._timeout),
+            httpx_args={"transport": self._transport} if self._transport else {},
+        )
+        self._client.__enter__()
+
+    def __enter__(self) -> Self:
+        if self._closed or self._client is not None:
+            raise ClosedError("Holder contexts cannot be reused")
+        self._connect()
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self._closed = True
+        if self._client is not None:
+            self._client.__exit__(*args)
+
+    def _active(self) -> AuthenticatedClient:
+        if self._closed or self._client is None:
+            raise ClosedError("Use Holder inside with Holder(...) as h")
+        return self._client
+
+    def __iter__(self) -> Iterator[Project]:
+        return iter(self.projects)
+
+    def _call(
+        self, endpoint: Any, *args: Any, write: bool = False, **kwargs: Any
+    ) -> Any:
+        client = self._active()
+        for attempt in range(2):
+            try:
+                response = endpoint.sync_detailed(*args, client=client, **kwargs)
+            except httpx.TransportError:
+                raise ConnectionError(
+                    "Could not communicate with the Holder daemon"
+                ) from None
+            except (ValueError, KeyError, TypeError):
+                raise ProtocolError("Invalid daemon response") from None
+            if (
+                response.status_code == 401
+                and self._local
+                and not write
+                and attempt == 0
+            ):
+                self._discover()
+                # Preserve the pool and custom transport while updating a restarted daemon.
+                http_client = client.get_httpx_client()
+                http_client.base_url = self._url
+                http_client.headers["Authorization"] = f"Bearer {self._token}"
+                continue
+            if isinstance(response.parsed, ErrorResponse):
+                error = response.parsed.error
+                error_type = {401: AuthenticationError, 404: NotFoundError}.get(
+                    response.status_code, APIError
+                )
+                raise error_type(int(response.status_code), error.code, error.message)
+            if response.status_code >= 400:
+                error_type = {401: AuthenticationError, 404: NotFoundError}.get(
+                    response.status_code, APIError
+                )
+                # Undocumented statuses are not parsed by generated endpoints.
+                try:
+                    error = ErrorResponse.from_dict(json.loads(response.content)).error
+                except (ValueError, KeyError, TypeError, AttributeError):
+                    error = None
+                if error is not None:
+                    raise error_type(
+                        int(response.status_code), error.code, error.message
+                    )
+                raise error_type(
+                    int(response.status_code), "http_error", "Daemon request failed"
+                )
+            if (
+                response.parsed is None
+                or getattr(response.parsed, "ok", None) is not True
+            ):
+                raise ProtocolError("Invalid daemon success envelope")
+            return response.parsed.data
+        raise AuthenticationError(
+            401, "unauthorized", "Daemon rejected refreshed credentials"
+        )

holder/collections.py

@@ -0,0 +1,70 @@
+"""Shared lazy iteration and caching for Holder collections."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import TYPE_CHECKING, Any, Generic, Self, TypeVar
+
+if TYPE_CHECKING:
+    from .client import Holder
+
+T = TypeVar("T")
+
+
+class Collection(Generic[T]):
+    """Lazy query with a progressively populated cache and independent iterators."""
+
+    def __init__(self, holder: Holder, query: dict[str, Any] | None = None) -> None:
+        self._holder = holder
+        self._query = dict(query or {})
+        self._cache: list[T] = []
+        self._next: int | str | None = None
+        self._done = False
+        self._generation = 0
+
+    def __iter__(self) -> Iterator[T]:
+        self._holder._active()
+        generation = self._generation
+        index = 0
+        while True:
+            self._holder._active()
+            if generation != self._generation:
+                raise RuntimeError("Collection was refreshed during iteration")
+            if index == len(self._cache):
+                if self._done:
+                    return
+                rows, next_cursor = self._fetch_page()
+                self._cache.extend(rows)
+                self._next = next_cursor
+                self._done = next_cursor is None
+                if not rows:
+                    return
+            yield self._cache[index]
+            index += 1
+
+    def __getitem__(self, index: int) -> T:
+        if not isinstance(index, int):
+            raise TypeError("Collection indices must be integers")
+        if index < 0:
+            raise IndexError("Collection indices must be nonnegative")
+        for position, item in enumerate(self):
+            if position == index:
+                return item
+        raise IndexError("Collection index out of range")
+
+    def all(self) -> Self:
+        return self._clone(self._query)
+
+    def refresh(self) -> Self:
+        self._holder._active()
+        self._cache.clear()
+        self._next = None
+        self._done = False
+        self._generation += 1
+        return self
+
+    def _clone(self, query: dict[str, Any]) -> Self:
+        raise NotImplementedError
+
+    def _fetch_page(self) -> tuple[list[T], int | str | None]:
+        raise NotImplementedError

holder/events.py

@@ -0,0 +1,238 @@
+"""Incremental asyncio transport for GET /events; no entity or recovery policy."""
+
+import asyncio
+import json
+import math
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from typing import Any, Self
+
+import httpx
+
+from .generated import AuthenticatedClient, Client
+
+
+@dataclass(frozen=True)
+class Event:
+    """A complete SSE frame. IDs are opaque; data is retained as UTF-8 text."""
+
+    event: str
+    data: str
+    id: str | None = None
+
+    def json(self) -> Any:
+        return json.loads(self.data)
+
+
+async def _lines(response: httpx.Response) -> AsyncIterator[str]:
+    # SSE recognizes only CR and LF, not Unicode separators inside JSON strings.
+    response.encoding = "utf-8"
+    line: list[str] = []
+    after_cr = False
+    async for chunk in response.aiter_text():
+        for character in chunk:
+            if after_cr and character == "\n":
+                after_cr = False
+                continue
+            after_cr = character == "\r"
+            if character in "\r\n":
+                yield "".join(line)
+                line.clear()
+            else:
+                line.append(character)
+    # No synthetic newline at EOF: partial frames must replay after reconnect.
+
+
+async def _frames(response: httpx.Response) -> AsyncIterator[Event]:
+    data: list[str] = []
+    name = "message"
+    event_id = None
+    first = True
+    async for line in _lines(response):
+        if first:
+            line = line.removeprefix("\ufeff")
+            first = False
+        if not line:
+            if data:
+                yield Event(name, "\n".join(data), event_id)
+            data, name, event_id = [], "message", None
+            continue
+        if line.startswith(":"):
+            continue
+        field, _, value = line.partition(":")
+        value = value.removeprefix(" ")
+        if field == "data":
+            data.append(value)
+        elif field == "event":
+            name = value or "message"
+        elif field == "id" and "\x00" not in value:
+            event_id = value
+    # An unterminated frame is not delivered or acknowledged on disconnect.
+
+
+class _ClosingStream(httpx.AsyncByteStream):
+    """Protect cleanup both at HTTPX's automatic EOF close and context exit."""
+
+    def __init__(self, stream: httpx.AsyncByteStream) -> None:
+        self._stream = stream
+        self._cleanup: asyncio.Task[None] | None = None
+
+    async def __aiter__(self) -> AsyncIterator[bytes]:
+        async for chunk in self._stream:
+            yield chunk
+
+    async def aclose(self) -> None:
+        if self._cleanup is None:
+            self._cleanup = asyncio.create_task(self._stream.aclose())
+        cleanup = self._cleanup
+        # A second task cancellation must not interrupt socket/pool cleanup.
+        cancelled = False
+        while not cleanup.done():
+            try:
+                await asyncio.shield(cleanup)
+            except asyncio.CancelledError:
+                cancelled = True
+        cleanup.result()
+        if cancelled:
+            raise asyncio.CancelledError
+
+
+@asynccontextmanager
+async def _connection(
+    transport: httpx.AsyncClient, **kwargs: Any
+) -> AsyncIterator[httpx.Response]:
+    request = transport.build_request("GET", "/events", **kwargs)
+    response = await transport.send(request, stream=True)
+    response.stream = _ClosingStream(response.stream)
+    try:
+        yield response
+    finally:
+        await response.aclose()
+
+
+class ChangeStream:
+    """Context-managed asyncio iterator over daemon invalidations.
+
+    Pass the same project filter used for /events/cursor. cursor advances when
+    the consumer requests the next event (after processing the previous one).
+    Persist cursor for a later subscription. A ready frame uses its ID, never
+    the newer checkpoint in its data. resync_required is yielded once and stops
+    iteration without advancing cursor: refresh state before subscribing again.
+
+    EOF and HTTPX transport errors reconnect after reconnect_delay seconds.
+    HTTP errors and invalid content types propagate without retry. Read timeout
+    defaults to disabled; connection/write/pool timeouts remain bounded.
+    Cancellation, aclose(), and context exit close the active response. The
+    supplied generated client remains caller-owned. Use asyncio task cancellation
+    or aclose() to interrupt a pending read; only one reader is supported.
+    """
+
+    def __init__(
+        self,
+        client: Client | AuthenticatedClient,
+        *,
+        project_id: str | None = None,
+        last_revision: str | None = None,
+        last_event_id: str | None = None,
+        reconnect_delay: float = 1.0,
+        timeout: httpx.Timeout | None = None,
+    ) -> None:
+        if not math.isfinite(reconnect_delay) or reconnect_delay < 0:
+            raise ValueError("reconnect_delay must be finite and nonnegative")
+        self.cursor = last_event_id
+        self._client = client
+        self._params = {
+            key: value
+            for key, value in {
+                "project_id": project_id,
+                "last_revision": last_revision,
+            }.items()
+            if value is not None
+        }
+        self._delay = reconnect_delay
+        self._timeout = timeout if timeout is not None else httpx.Timeout(10, read=None)
+        self._iterator = self._events()
+        self._pending: asyncio.Task[Event] | None = None
+        self._entered = False
+        self._closed = False
+
+    async def __aenter__(self) -> Self:
+        if self._entered or self._closed:
+            raise RuntimeError("ChangeStream contexts cannot be reused")
+        self._entered = True
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.aclose()
+
+    def __aiter__(self) -> Self:
+        return self
+
+    async def __anext__(self) -> Event:
+        if not self._entered:
+            raise RuntimeError("Use ChangeStream inside async with")
+        if self._closed:
+            raise StopAsyncIteration
+        if self._pending is not None:
+            raise RuntimeError("ChangeStream supports only one reader")
+        pending = asyncio.create_task(anext(self._iterator))
+        self._pending = pending
+        try:
+            return await pending
+        except BaseException:
+            self._closed = True
+            await self._iterator.aclose()
+            raise
+        finally:
+            self._pending = None
+
+    async def aclose(self) -> None:
+        """Stop iteration, including a blocked read or reconnect delay."""
+        self._closed = True
+        pending = self._pending
+        if pending is not None:
+            pending.cancel()
+            try:
+                await pending
+            except (asyncio.CancelledError, StopAsyncIteration):
+                pass
+        await self._iterator.aclose()
+
+    async def _events(self) -> AsyncIterator[Event]:
+        transport = self._client.get_async_httpx_client()
+        while not self._closed:
+            headers = {
+                "Accept": "text/event-stream",
+                "Last-Event-ID": self.cursor or "",
+            }
+            terminal = None
+            try:
+                async with _connection(
+                    transport,
+                    params=self._params,
+                    headers=headers,
+                    timeout=self._timeout,
+                ) as response:
+                    response.raise_for_status()
+                    if (
+                        response.headers.get("content-type", "")
+                        .split(";")[0]
+                        .strip()
+                        .lower()
+                        != "text/event-stream"
+                    ):
+                        raise ValueError("Expected text/event-stream response")
+                    async for event in _frames(response):
+                        if event.event == "resync_required":
+                            terminal = event
+                            break
+                        yield event
+                        if event.id is not None:
+                            self.cursor = event.id or None
+            except httpx.TransportError:
+                pass
+            if terminal is not None:
+                yield terminal
+                return
+            await asyncio.sleep(self._delay)

holder/exceptions.py

@@ -0,0 +1,35 @@
+"""Errors raised by the high-level Holder API."""
+
+
+class HolderError(Exception):
+    """Base error for the high-level client."""
+
+
+class ConnectionError(HolderError):
+    """Daemon discovery, startup or transport failed."""
+
+
+class ClosedError(HolderError):
+    """The client is outside its active context."""
+
+
+class ProtocolError(HolderError):
+    """The daemon returned an invalid or incompatible response."""
+
+
+class APIError(HolderError):
+    """A failed daemon request, with its status and error envelope."""
+
+    def __init__(self, status: int, code: str, message: str) -> None:
+        self.status = status
+        self.code = code
+        self.message = message
+        super().__init__(f"{status} {code}: {message}")
+
+
+class AuthenticationError(APIError):
+    """The daemon rejected the credentials."""
+
+
+class NotFoundError(APIError):
+    """The requested object was not found within its scope."""

holder/generated/__init__.py

@@ -0,0 +1,8 @@
+"""A client library for accessing Holder API"""
+
+from .client import AuthenticatedClient, Client
+
+__all__ = (
+    "AuthenticatedClient",
+    "Client",
+)

holder/generated/api/__init__.py

@@ -0,0 +1 @@
+"""Contains methods for accessing the API"""

holder/generated/api/default/__init__.py

@@ -0,0 +1 @@
+"""Contains endpoint functions for accessing the API"""