libbeachcomber 0.1.0__py3-none-any.whl

libbeachcomber/__init__.py

@@ -0,0 +1,47 @@
+"""beachcomber — Python client SDK for the comb shell-state daemon.
+
+Quick start::
+
+    from beachcomber import Client
+
+    client = Client()
+    result = client.get("git.branch", path="/path/to/repo")
+    if result.is_hit:
+        print(result.data)        # "main"
+        print(result.age_ms)      # 234
+        print(result.stale)       # False
+
+    # Full provider object
+    result = client.get("git", path="/path/to/repo")
+    if result.is_hit:
+        print(result["branch"])   # subscript into dict data
+
+    # Force recomputation
+    client.poke("git", path="/path/to/repo")
+
+    # Persistent connection for multiple queries
+    with client.session() as session:
+        session.set_context("/path/to/repo")
+        branch = session.get("git.branch")
+        host = session.get("hostname")
+
+    # List providers and daemon status
+    providers = client.list()
+    status = client.status()
+"""
+
+from .client import Client, Session
+from .exceptions import CombError, DaemonNotRunning, ProtocolError, ServerError
+from .result import CombResult
+
+__all__ = [
+    "Client",
+    "Session",
+    "CombResult",
+    "CombError",
+    "DaemonNotRunning",
+    "ProtocolError",
+    "ServerError",
+]
+
+__version__ = "0.1.0"

libbeachcomber/client.py

@@ -0,0 +1,319 @@
+"""Client and Session classes for the beachcomber daemon.
+
+Typical usage::
+
+    from beachcomber import Client
+
+    client = Client()
+    result = client.get("git.branch", path="/path/to/repo")
+    if result.is_hit:
+        print(result.data)
+
+For multiple queries on one connection use a session::
+
+    with client.session() as session:
+        session.set_context("/path/to/repo")
+        branch = session.get("git.branch")
+        status = session.get("git")
+"""
+
+from __future__ import annotations
+
+import io
+import socket
+from contextlib import contextmanager
+from typing import Any, Generator, List, Optional
+
+from .discovery import discover_socket_path
+from .exceptions import DaemonNotRunning, ProtocolError
+from .protocol import (
+    build_context_request,
+    build_get_request,
+    build_list_request,
+    build_poke_request,
+    build_status_request,
+    decode_response,
+)
+from .result import CombResult
+
+# Default socket timeout in seconds (matches Rust client: 100 ms).
+_DEFAULT_TIMEOUT: float = 0.1
+
+
+def _connect(socket_path: str, timeout: float) -> socket.socket:
+    """Open a Unix domain socket connection to the daemon.
+
+    Args:
+        socket_path: Absolute path to the Unix domain socket.
+        timeout: Read/write timeout in seconds.
+
+    Returns:
+        Connected :class:`socket.socket`.
+
+    Raises:
+        DaemonNotRunning: If the connection is refused or the socket does
+            not exist.
+    """
+    try:
+        sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        sock.settimeout(timeout)
+        sock.connect(socket_path)
+        return sock
+    except (ConnectionRefusedError, FileNotFoundError, OSError) as exc:
+        raise DaemonNotRunning(socket_path) from exc
+
+
+def _send_recv(sock: socket.socket, request: bytes) -> dict[str, Any]:
+    """Send a request and read one response line.
+
+    Args:
+        sock: Connected socket.
+        request: Encoded request bytes (must include trailing newline).
+
+    Returns:
+        Parsed response dict (``ok`` has already been verified to be
+        ``True``).
+
+    Raises:
+        ProtocolError: On I/O or parse failure.
+        ServerError: If the daemon returns ``ok: false``.
+    """
+    try:
+        sock.sendall(request)
+    except OSError as exc:
+        raise ProtocolError(f"failed to send request: {exc}") from exc
+
+    # Read until newline using a file-like wrapper.
+    reader = sock.makefile("r", encoding="utf-8")
+    try:
+        line = reader.readline()
+    except OSError as exc:
+        raise ProtocolError(f"failed to read response: {exc}") from exc
+    finally:
+        reader.detach()  # Do not close the underlying socket.
+
+    return decode_response(line)
+
+
+def _result_from_response(resp: dict[str, Any]) -> CombResult:
+    """Build a :class:`CombResult` from a parsed ``get`` response dict."""
+    data = resp.get("data")
+    age_ms = int(resp.get("age_ms", 0) or 0)
+    stale = bool(resp.get("stale", False))
+    return CombResult(ok=True, data=data, age_ms=age_ms, stale=stale)
+
+
+class Client:
+    """One-shot client for the beachcomber daemon.
+
+    Each method opens a new socket connection, sends one request, reads
+    the response, then closes the connection. This is simple and safe
+    for occasional queries.
+
+    For repeated queries (e.g. populating a shell prompt) prefer
+    :meth:`session` which reuses the connection.
+
+    Args:
+        socket_path: Explicit path to the daemon socket. If ``None`` the
+            path is auto-discovered via
+            :func:`~beachcomber.discovery.discover_socket_path`.
+        timeout: Socket read/write timeout in seconds. Default ``0.1``.
+    """
+
+    def __init__(
+        self,
+        socket_path: Optional[str] = None,
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        self._socket_path = socket_path
+        self._timeout = timeout
+
+    def _resolve_path(self) -> str:
+        return self._socket_path or discover_socket_path()
+
+    def get(self, key: str, path: Optional[str] = None) -> CombResult:
+        """Read a cached value from the daemon.
+
+        Args:
+            key: Provider key. Use ``"provider.field"`` for a single
+                scalar (e.g. ``"git.branch"``) or ``"provider"`` for the
+                full provider object (e.g. ``"git"``).
+            path: Working-directory path for per-directory providers.
+                Global providers (e.g. ``"hostname"``) ignore this.
+
+        Returns:
+            :class:`~beachcomber.result.CombResult` with ``is_hit``
+            ``True`` when a cached value exists.
+
+        Raises:
+            DaemonNotRunning: If the socket cannot be reached.
+            ServerError: If the daemon returns an error response.
+            ProtocolError: On I/O or JSON parse failure.
+        """
+        sock = _connect(self._resolve_path(), self._timeout)
+        try:
+            resp = _send_recv(sock, build_get_request(key, path))
+        finally:
+            sock.close()
+        return _result_from_response(resp)
+
+    def poke(self, key: str, path: Optional[str] = None) -> None:
+        """Trigger recomputation of a provider.
+
+        The daemon will recompute the value in the background. This is
+        fire-and-forget — the method returns once the daemon acknowledges
+        the poke.
+
+        Args:
+            key: Provider key to recompute.
+            path: Working-directory path for per-directory providers.
+
+        Raises:
+            DaemonNotRunning: If the socket cannot be reached.
+            ServerError: If the daemon returns an error response.
+            ProtocolError: On I/O or JSON parse failure.
+        """
+        sock = _connect(self._resolve_path(), self._timeout)
+        try:
+            _send_recv(sock, build_poke_request(key, path))
+        finally:
+            sock.close()
+
+    def list(self) -> List[dict[str, Any]]:
+        """Return available providers from the daemon.
+
+        Returns:
+            List of provider dicts. Each dict has at least ``"name"``,
+            ``"global"``, and ``"fields"`` keys.
+
+        Raises:
+            DaemonNotRunning: If the socket cannot be reached.
+            ServerError: If the daemon returns an error response.
+            ProtocolError: On I/O or JSON parse failure.
+        """
+        sock = _connect(self._resolve_path(), self._timeout)
+        try:
+            resp = _send_recv(sock, build_list_request())
+        finally:
+            sock.close()
+        return resp.get("data", [])
+
+    def status(self) -> dict[str, Any]:
+        """Return daemon scheduler and cache status.
+
+        Returns:
+            Status dict as returned by the daemon.
+
+        Raises:
+            DaemonNotRunning: If the socket cannot be reached.
+            ServerError: If the daemon returns an error response.
+            ProtocolError: On I/O or JSON parse failure.
+        """
+        sock = _connect(self._resolve_path(), self._timeout)
+        try:
+            resp = _send_recv(sock, build_status_request())
+        finally:
+            sock.close()
+        return resp.get("data", {})
+
+    @contextmanager
+    def session(self) -> Generator[Session, None, None]:
+        """Open a persistent connection as a context manager.
+
+        Yields a :class:`Session` that reuses a single socket for all
+        operations within the ``with`` block.
+
+        Example::
+
+            with client.session() as session:
+                session.set_context("/my/repo")
+                result = session.get("git.branch")
+
+        Raises:
+            DaemonNotRunning: If the socket cannot be reached.
+        """
+        sock = _connect(self._resolve_path(), self._timeout)
+        session = Session(sock)
+        try:
+            yield session
+        finally:
+            sock.close()
+
+
+class Session:
+    """Persistent connection to the beachcomber daemon.
+
+    Reuses a single Unix domain socket across multiple operations.
+    Create via :meth:`Client.session` rather than directly.
+
+    Args:
+        sock: Already-connected :class:`socket.socket`.
+    """
+
+    def __init__(self, sock: socket.socket) -> None:
+        self._sock = sock
+
+    def set_context(self, path: str) -> None:
+        """Set the default working-directory path for this connection.
+
+        After calling this, :meth:`get` and :meth:`poke` calls do not
+        need an explicit ``path`` argument.
+
+        Args:
+            path: Absolute path to set as the session context.
+
+        Raises:
+            ServerError: If the daemon returns an error response.
+            ProtocolError: On I/O or JSON parse failure.
+        """
+        _send_recv(self._sock, build_context_request(path))
+
+    def get(self, key: str, path: Optional[str] = None) -> CombResult:
+        """Read a cached value using the persistent connection.
+
+        Args:
+            key: Provider key (``"git.branch"``, ``"git"``, etc.).
+            path: Optional path override. If omitted and
+                :meth:`set_context` has been called, the session context
+                is used by the daemon.
+
+        Returns:
+            :class:`~beachcomber.result.CombResult`.
+
+        Raises:
+            ServerError: If the daemon returns an error response.
+            ProtocolError: On I/O or JSON parse failure.
+        """
+        resp = _send_recv(self._sock, build_get_request(key, path))
+        return _result_from_response(resp)
+
+    def poke(self, key: str, path: Optional[str] = None) -> None:
+        """Trigger recomputation via the persistent connection.
+
+        Args:
+            key: Provider key to recompute.
+            path: Optional path override.
+
+        Raises:
+            ServerError: If the daemon returns an error response.
+            ProtocolError: On I/O or JSON parse failure.
+        """
+        _send_recv(self._sock, build_poke_request(key, path))
+
+    def list(self) -> List[dict[str, Any]]:
+        """Return available providers via the persistent connection.
+
+        Returns:
+            List of provider dicts.
+        """
+        resp = _send_recv(self._sock, build_list_request())
+        return resp.get("data", [])
+
+    def status(self) -> dict[str, Any]:
+        """Return daemon status via the persistent connection.
+
+        Returns:
+            Status dict as returned by the daemon.
+        """
+        resp = _send_recv(self._sock, build_status_request())
+        return resp.get("data", {})

libbeachcomber/discovery.py

@@ -0,0 +1,35 @@
+"""Socket path discovery for the beachcomber daemon.
+
+Discovery order:
+1. ``$XDG_RUNTIME_DIR/beachcomber/sock``
+2. ``$TMPDIR/beachcomber-<uid>/sock``
+3. ``/tmp/beachcomber-<uid>/sock``
+"""
+
+import os
+
+
+def get_uid() -> int:
+    """Return the effective user ID of the current process."""
+    return os.geteuid()
+
+
+def discover_socket_path() -> str:
+    """Return the expected socket path for the running daemon.
+
+    Checks the standard locations in order. Returns the first path that
+    *should* exist according to the discovery rules — callers are
+    responsible for verifying the socket is reachable.
+
+    Returns:
+        Absolute path string for the Unix domain socket.
+    """
+    xdg_runtime = os.environ.get("XDG_RUNTIME_DIR", "")
+    if xdg_runtime:
+        candidate = os.path.join(xdg_runtime, "beachcomber", "sock")
+        if os.path.exists(candidate):
+            return candidate
+
+    uid = get_uid()
+    tmpdir = os.environ.get("TMPDIR", "/tmp").rstrip("/")
+    return os.path.join(tmpdir, f"beachcomber-{uid}", "sock")

libbeachcomber/exceptions.py

@@ -0,0 +1,35 @@
+"""Exceptions raised by the beachcomber client."""
+
+
+class CombError(Exception):
+    """Base exception for all beachcomber client errors."""
+
+
+class DaemonNotRunning(CombError):
+    """Raised when the beachcomber daemon socket cannot be connected to.
+
+    This usually means ``comb daemon`` is not running. Start it before
+    using the client.
+    """
+
+    def __init__(self, socket_path: str) -> None:
+        self.socket_path = socket_path
+        super().__init__(
+            f"beachcomber daemon is not running (tried {socket_path})"
+        )
+
+
+class ServerError(CombError):
+    """Raised when the daemon returns ``ok: false`` in its response.
+
+    Attributes:
+        message: The error string from the daemon.
+    """
+
+    def __init__(self, message: str) -> None:
+        self.message = message
+        super().__init__(f"daemon error: {message}")
+
+
+class ProtocolError(CombError):
+    """Raised when a response cannot be parsed as valid JSON or is malformed."""

libbeachcomber/protocol.py

@@ -0,0 +1,119 @@
+"""Newline-delimited JSON protocol helpers for the beachcomber daemon.
+
+All requests are JSON objects with an ``"op"`` field. All responses are
+JSON objects with an ``"ok"`` field that is ``true`` or ``false``.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Optional
+
+from .exceptions import ProtocolError, ServerError
+
+
+def encode_request(op: str, **fields: Any) -> bytes:
+    """Serialise a request object to a newline-terminated JSON bytes value.
+
+    Args:
+        op: The operation name (``"get"``, ``"poke"``, ``"context"``,
+            ``"list"``, or ``"status"``).
+        **fields: Additional key/value pairs to include in the request.
+
+    Returns:
+        UTF-8 encoded JSON followed by a newline byte.
+    """
+    payload: dict[str, Any] = {"op": op}
+    payload.update(fields)
+    return (json.dumps(payload, separators=(",", ":")) + "\n").encode()
+
+
+def decode_response(line: str) -> dict[str, Any]:
+    """Parse a single newline-delimited JSON response line.
+
+    Args:
+        line: A single text line received from the daemon.
+
+    Returns:
+        Parsed response dict.
+
+    Raises:
+        ProtocolError: If the line is not valid JSON or is missing the
+            ``"ok"`` field.
+        ServerError: If the response contains ``"ok": false``.
+    """
+    line = line.strip()
+    if not line:
+        raise ProtocolError("received empty response from daemon")
+
+    try:
+        data: dict[str, Any] = json.loads(line)
+    except json.JSONDecodeError as exc:
+        raise ProtocolError(f"invalid JSON from daemon: {exc}") from exc
+
+    if not isinstance(data, dict):
+        raise ProtocolError(f"expected JSON object, got {type(data).__name__}")
+
+    ok = data.get("ok")
+    if ok is None:
+        raise ProtocolError("response missing 'ok' field")
+
+    if ok is False:
+        error_msg = data.get("error", "unknown error")
+        raise ServerError(str(error_msg))
+
+    return data
+
+
+def build_get_request(key: str, path: Optional[str] = None) -> bytes:
+    """Build a ``get`` request.
+
+    Args:
+        key: Provider key, e.g. ``"git.branch"`` or ``"git"``.
+        path: Optional working-directory path for per-directory providers.
+
+    Returns:
+        Encoded request bytes.
+    """
+    kwargs: dict[str, Any] = {"key": key}
+    if path is not None:
+        kwargs["path"] = path
+    return encode_request("get", **kwargs)
+
+
+def build_poke_request(key: str, path: Optional[str] = None) -> bytes:
+    """Build a ``poke`` request.
+
+    Args:
+        key: Provider key to recompute.
+        path: Optional working-directory path.
+
+    Returns:
+        Encoded request bytes.
+    """
+    kwargs: dict[str, Any] = {"key": key}
+    if path is not None:
+        kwargs["path"] = path
+    return encode_request("poke", **kwargs)
+
+
+def build_context_request(path: str) -> bytes:
+    """Build a ``context`` request to set the default path for a session.
+
+    Args:
+        path: Directory path to set as the connection context.
+
+    Returns:
+        Encoded request bytes.
+    """
+    return encode_request("context", path=path)
+
+
+def build_list_request() -> bytes:
+    """Build a ``list`` request."""
+    return encode_request("list")
+
+
+def build_status_request() -> bytes:
+    """Build a ``status`` request."""
+    return encode_request("status")

libbeachcomber/result.py

@@ -0,0 +1,59 @@
+"""CombResult dataclass returned by client get() calls."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+@dataclass
+class CombResult:
+    """Result of a ``get`` query to the beachcomber daemon.
+
+    Attributes:
+        ok: Whether the daemon responded without error (always ``True``
+            when returned from the client — errors raise exceptions).
+        data: The cached value. ``None`` on a cache miss. May be a string,
+            number, bool, or dict depending on the provider and key.
+        age_ms: How many milliseconds old the cached value is. ``0`` on a
+            miss.
+        stale: ``True`` when the value is past its TTL but no fresh value
+            is available yet.
+        error: Error message string when ``ok`` is ``False``. The client
+            raises :class:`~beachcomber.exceptions.ServerError` for these,
+            so callers typically do not see this field set.
+    """
+
+    ok: bool = True
+    data: Any = None
+    age_ms: int = 0
+    stale: bool = False
+    error: Optional[str] = None
+
+    @property
+    def is_hit(self) -> bool:
+        """``True`` when the cache contains a value for this key."""
+        return self.data is not None
+
+    def __getitem__(self, key: str) -> Any:
+        """Access a field from dict data by subscript.
+
+        Useful when querying a full provider that returns an object,
+        e.g. ``result["branch"]`` after ``client.get("git")``.
+
+        Args:
+            key: Field name to look up in the data dict.
+
+        Returns:
+            The field value.
+
+        Raises:
+            TypeError: If ``data`` is not a dict.
+            KeyError: If ``key`` is not present in the dict.
+        """
+        if not isinstance(self.data, dict):
+            raise TypeError(
+                f"CombResult.data is {type(self.data).__name__}, not dict; "
+                "subscript access is only valid for object responses"
+            )
+        return self.data[key]

libbeachcomber-0.1.0.dist-info/METADATA

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: libbeachcomber
+Version: 0.1.0
+Summary: Python client SDK for the beachcomber (comb) shell-state daemon
+Project-URL: Homepage, https://github.com/NavistAu/beachcomber
+Project-URL: Repository, https://github.com/NavistAu/beachcomber
+Project-URL: Issues, https://github.com/NavistAu/beachcomber/issues
+Author: NavistAu
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Shells
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# beachcomber Python SDK
+
+Python client for the [beachcomber](https://github.com/jhogendorn/beachcomber) (`comb`) shell-state daemon.
+
+## Requirements
+
+- Python 3.9+
+- No external dependencies (stdlib only)
+- A running `comb` daemon
+
+## Installation
+
+```sh
+pip install beachcomber
+```
+
+Or with `uv`:
+
+```sh
+uv add beachcomber
+```
+
+## Quick start
+
+```python
+from beachcomber import Client
+
+client = Client()
+
+# Read a single field
+result = client.get("git.branch", path="/path/to/repo")
+if result.is_hit:
+    print(result.data)    # "main"
+    print(result.age_ms)  # 234
+    print(result.stale)   # False
+
+# Read a full provider (returns dict)
+result = client.get("git", path="/path/to/repo")
+if result.is_hit:
+    print(result["branch"])  # "main"
+    print(result["dirty"])   # False
+
+# Force recomputation
+client.poke("git", path="/path/to/repo")
+
+# List available providers
+providers = client.list()
+
+# Daemon status
+status = client.status()
+```
+
+## Sessions
+
+For multiple queries use a session to reuse a single connection:
+
+```python
+with client.session() as session:
+    session.set_context("/path/to/repo")
+    branch = session.get("git.branch")
+    dirty = session.get("git.dirty")
+    hostname = session.get("hostname")
+```
+
+## Custom socket path
+
+```python
+client = Client(socket_path="/run/user/1000/beachcomber/sock")
+```
+
+## Socket discovery
+
+The SDK discovers the daemon socket at:
+
+1. `$XDG_RUNTIME_DIR/beachcomber/sock`
+2. `$TMPDIR/beachcomber-<uid>/sock`
+3. `/tmp/beachcomber-<uid>/sock`
+
+## Exceptions
+
+| Exception | When raised |
+|---|---|
+| `DaemonNotRunning` | Cannot connect to the socket |
+| `ServerError` | Daemon returns `ok: false` |
+| `ProtocolError` | Malformed JSON or I/O failure |
+| `CombError` | Base class for all SDK errors |

libbeachcomber-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+libbeachcomber/__init__.py,sha256=1peyIUg6de5QRlmQpSNzMlyZJ0Pj3iAavHhFLrArHCg,1219
+libbeachcomber/client.py,sha256=NI7KTwVZ66Klq-bhIpsbgFmKTMrNaOHEhKfVV8ek2co,10323
+libbeachcomber/discovery.py,sha256=4vKonS5cLHo4tPiio6LAWWWMI4CCbs3ENOxf7op1v_U,1039
+libbeachcomber/exceptions.py,sha256=u-4UOMQvXX3NJHVFFC3tjy8HdGTLQGbo9Ou_oFAQ6YM,973
+libbeachcomber/protocol.py,sha256=JDLcdp9uwHC3hEjWM8jqE2En89g6A1zWvZNek2_xDHI,3296
+libbeachcomber/result.py,sha256=kQiCdRXfRyG4jODbJ_Z6BCEUt8b-40Th61zFbAIMncE,2003
+libbeachcomber-0.1.0.dist-info/METADATA,sha256=VYtD3PqBeXaXSQ5TNMxtO-potxCm6wk8XUNvQ7Xa858,2715
+libbeachcomber-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+libbeachcomber-0.1.0.dist-info/RECORD,,

libbeachcomber-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any