Skip to main content

beachcomber Python SDK

Python client for the beachcomber (comb) shell-state daemon. It follows the SDK API table (docs/sdk-api.md): the same methods, options, value shapes and error kinds as every other SDK, which tests/test_api_surface.py checks against sdks/api.json.

Requirements

  • Python 3.9+
  • No external dependencies (stdlib ctypes binds directly to the native libbeachcomber.{so,dylib} — no subprocess, no socket code in this SDK)
  • A running comb daemon (or autostart left enabled, the default)
  • libbeachcomber.{so,dylib} discoverable — see "Library discovery" below

Installation

pip install libbeachcomber

Or with uv:

uv add libbeachcomber

Quick start

import os

from libbeachcomber import Client

client = Client()

# What `comb get git.branch` prints in that directory; None on a miss
branch = client.get("git.branch", cwd="/path/to/repo")   # "main"

# A full provider (a dict)
git = client.get("git", cwd="/path/to/repo")
print(git["branch"], git["dirty"])

# The caller's environment for env.* refs; force a run, and wait for it
client.get("aws.profile", cwd="/path/to/repo", env=dict(os.environ))
client.get("git.branch", cwd="/path/to/repo", force=True, wait="forever")
# Answer at once with what is stored, however stale
client.get("git.branch", cwd="/path/to/repo", wait="0")

# The template itself, unrendered: a facet, read like any key
client.get("aws:template.profile")

# Force recomputation
client.refresh("git", path="/path/to/repo")

# Daemon status
status = client.status()

get

client.get(key, cwd=None, env=None, force=False, wait=None) returns the value comb get prints for this key, cwd and env — the bare value, None on a miss. The daemon holds the templates (<provider>:template, seeded from configuration or put) and the client renders them: a plain field is its cached value, a templated one is rendered, and a bare provider name is the whole merged namespace. cwd=None is the global entry. The unrendered halves are facets, read like any key: p:template.x is the template as stored, p:put.x and p:source.x those layers' values.

force=True re-executes every Source the read demands, as comb get --force. wait is how long the read waits for a run it needs before it answers what is stored, as comb get --wait: a duration ("0", "50ms", "2s") or "forever"; anything else is a ParseError. Left out, a stored record waits its Source's budget and a cold read waits for its run. The read may take timeout_ms plus the wait ("forever" has no deadline), so a cold read with no wait can outlast the default 250 ms and raise TimeoutError; its run goes on, and the next read has the value.

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")   # reads at the session's directory
    dirty = session.get("git.dirty")
    hostname = session.get("hostname")

Eval

client.eval(template_str, cwd=None, env=None) renders a template that is stored nowhere — the same value comb eval prints; eval("{{ p.f }}") and get("p.f") agree. The template accepts a single {{ expr }} tag, or literal text/several tags — the former keeps the expression's natural type, the latter is always a string (a source with no tags at all is its literal text).

exec() inside a template runs only on a client created with Client(exec=True); it is off by default, and a template that calls it then fails with exec() is disabled in this context.

Watch

client.watch(key, cwd=None, env=None) streams get's value for that key, cwd and env, again each time it changes:

with client.watch("git.branch", cwd="/path/to/repo") as stream:
    for event in stream:          # ends when the stream does
        print(event.data)         # None is a miss, not the end

stream.next_event(timeout_ms=None) answers the next WatchEvent, or None once the stream has ended; a timeout_ms that runs out with no event raises TimeoutError, and the stream stays open. stream.cancel() ends it from any thread, and stream.close() ends it and frees it.

status(), hello() and introspect(subject, duration_secs=None) are the client's; a session has none of them. status() answers typed CacheRows, hello() a HelloInfo, and introspect() an IntrospectResponse whose daemon is a typed DaemonHealth (with its ReaperStatus and Verdicts) for the daemon subject and whose other is the JSON for the rest.

Client options

client = Client(socket_path="/tmp/beachcomber-1000/sock", timeout_ms=500, connect_timeout_ms=0)
Option Default Meaning
socket_path $BEACHCOMBER_SOCKET, else /tmp/beachcomber-<uid>/sock The daemon's socket.
timeout_ms 250 How long one read or write on the socket may take; at least 1.
connect_timeout_ms 1500 How long connecting keeps retrying before it gives up; 0 is one attempt.
autostart on Start a daemon when none answers an auto-discovered socket.
exec off Whether a template this client renders may call exec().

The defaults are the library's (bc_client_new): this SDK passes on the options you give and adds none of its own.

Library discovery

This SDK is a ctypes binding over libbeachcomber's C ABI — no socket code or wire-protocol framing lives in Python; the native library owns the connection (including the daemon socket's own auto-discovery and autostart). It is loaded on first use.

The library is found by the one rule every SDK follows (docs/sdk-api.md, "Library discovery"). The file is libbeachcomber.dylib on macOS and libbeachcomber.so on every other platform, and the SDK tries, in order:

  1. $BEACHCOMBER_LIB, when it is set and not empty. It is then the only candidate: a path set on purpose that does not load is an error, not a reason to load some other library.
  2. Beside comb: <dir>/../lib/<file>, where <dir> is the directory of the first executable comb on $PATH, its symlinks resolved. A Homebrew comb is a symlink into the Cellar, and the library sits in the Cellar beside it.
  3. The system loader, given the bare file name.

When none loads, LibraryNotFoundError names every candidate and why each failed; there is no fallback to spawning comb as a subprocess. The tests check this against the shared fixture, sdks/discovery.json.

Socket discovery

Once the library is loaded, the daemon socket path itself is resolved by libbeachcomber (not this SDK): $BEACHCOMBER_SOCKET if set, else a stable per-user default. Pass Client(socket_path=...) to override it directly.

Exceptions

Every exception is one CombError subclass per error kind, carrying .kind (the slug, matching the C ABI envelope's error.kind), .message (the ABI's message, unchanged — str(exc) is the same) and .library_version (the loaded library's bc_version()), so callers should not need to string-match str(exc).

Exception .kind When raised
DaemonNotRunningError daemon_not_running No daemon answers, and none was started
ConnectionFailedError connection_failed An explicit socket_path could not be connected to
IoError io_error A read or write on the socket failed
ParseError parse_error A request, a response or a template could not be read
ServerError server_error The daemon refused the request, or a template failed to render
TimeoutError timeout A read or write ran out timeout_ms, or next_event ran out its timeout_ms
BusyError busy A session or watch is in use by another caller
PanicError panic The library panicked; the panic was caught at the boundary
LibraryNotFoundError library_not_found No libbeachcomber was found where discovery looks
LibrarySymbolError library_symbol The library found lacks a function this SDK calls
UnsupportedError unsupported A transport cannot do this operation (never raised here: this SDK has one transport)
CombError varies Base class for all of them

Running tests

cd sdks/python
uv run --with pytest python -m pytest                # unit and integration tests
COMB_BIN=/path/to/comb python3 conformance_runner.py # the shared fixtures under tests/conformance/

The integration tests spawn a comb daemon and load libbeachcomber from the workspace's debug build (../../target/debug/, made by cargo build) unless BEACHCOMBER_LIB / COMB_BIN are set.

Metadata

Release files for libbeachcomber 0.10.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for libbeachcomber 0.10.1
File Size Uploaded Provenance Actions
libbeachcomber-0.10.1.tar.gz 26.9 kB With provenance Details for libbeachcomber-0.10.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for libbeachcomber 0.10.1
File Interpreter ABI Platform Actions
libbeachcomber-0.10.1-py3-none-any.whl Python 3 none any Details for libbeachcomber-0.10.1-py3-none-any.whl

Total release size: 45.1 kB

Release files / libbeachcomber-0.10.1.tar.gz

Download URL libbeachcomber-0.10.1.tar.gz
Size 26.9 kB
Tags Source
SHA-256 checksum
How to use checksums
3159ebe4c67dd65413c78ac7a57c3ad0b2a2ec42b16c26c99f7ac375aa47dc08
BLAKE2b-256 checksum
How to use checksums
e3fb3f664a97a9a9bc0679971f32493db83181a57c071739c888944bbdf7493b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.

Transparency log

Release files / libbeachcomber-0.10.1-py3-none-any.whl

Download URL libbeachcomber-0.10.1-py3-none-any.whl
Size 18.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
78284f4ecafca7e96f5f7ee17904af0e9c96e9b644f5aaf60eefc21051a427ef
BLAKE2b-256 checksum
How to use checksums
5e8dbbc81cba4ba476ef86e76de96b0ca1cb38311e2c1777383d169e8763da9d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.

Transparency log

Security for libbeachcomber 0.10.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for libbeachcomber-0.10.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page