libbeachcomber 0.7.0

Python client SDK for the beachcomber (comb) shell-state daemon

beachcomber Python SDK

Python client for the beachcomber (comb) shell-state daemon.

Requirements

• Python 3.9+
• No external dependencies (stdlib only)
• A running comb daemon

Installation

pip install beachcomber

Or with uv:

uv add beachcomber

Quick start

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.refresh("git", path="/path/to/repo")

# Daemon status
status = client.status()

Sessions

For multiple queries use a session to reuse a single connection:

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

client = Client(socket_path="/run/user/1000/beachcomber/sock")

Socket discovery

The SDK discovers the daemon socket at:

1. $BEACHCOMBER_SOCKET (if set and non-empty)
2. $XDG_RUNTIME_DIR/beachcomber/sock (if XDG_RUNTIME_DIR is set)
3. /tmp/beachcomber-<uid>/sock

This mirrors the daemon's bind path; $TMPDIR is not consulted.

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