API Reference

Previous

This page is the generated reference for the public Python modules.

Use the narrative pages first if you are learning ShelfDB. Come back here when you want exact signatures, annotations, class members, or module-level details.

Protocol

Start with the Protocol page for the conceptual overview and module guide.

The sections below show the public shelfdb.protocol package surface and the protocol submodules.

shelfdb.protocol

Shared protocol helpers for ShelfDB.

shelfdb.protocol.schema

Typed protocol shapes and schema models.

shelfdb.protocol.schema

Typed protocol schema declarations for ShelfDB RPC payloads.

ErrorResponseSchema

Bases: Model

Top-level RPC error envelope returned when server execution fails.

QueryRequestSchema

Bases: Model

Top-level RPC request schema for one shelf query pipeline.

QueryStepSchema

Bases: Model

One RPC query step used inside query and transaction request payloads.

RequestTypeSchema

Bases: Model

Minimal discriminator schema used only to route request validation.

RpcErrorSchema

Bases: Model

Structured server-side exception payload sent back to clients.

TransactionRequestSchema

Bases: Model

Top-level RPC request schema for a multi-shelf transaction batch.

TransactionShelfRequestSchema

Bases: Model

One shelf entry inside a transaction request's txs batch.

shelfdb.protocol.query

Serialized query-step builders.

shelfdb.protocol.query

Serialized query-step builders for ShelfDB.

build_query_step 

build_query_step(
    op: str, *args, write: bool = False, **kwargs
) -> QueryStep

Build one serialized query step using an explicit call shape.

prepare_query_step 

prepare_query_step(
    op: str,
    args: tuple[Any, ...],
    kwargs: dict[str, Any],
    *,
    write: bool = False
) -> QueryStep

Build one serialized query step.

shelfdb.protocol.payload

Request and response payload helpers.

shelfdb.protocol.payload

Shared RPC payload helpers for ShelfDB.

shelfdb.protocol.codec

Byte-level request and response codecs.

shelfdb.protocol.codec

Shared protocol byte codecs for ShelfDB.

dumps_request 

dumps_request(payload: Any) -> bytes

Encode one request payload with dill.

dumps_response 

dumps_response(payload: Any) -> bytes

Encode one response payload with msgpack.

loads_request 

loads_request(data: bytes)

Decode one request payload with dill.

loads_response 

loads_response(data: bytes)

Decode one response payload with msgpack.

Package

Top-level package exports such as open(), connect(), and connect_async().

shelfdb

open 

open(path: str) -> DB

Open database, return shelfdb.DB object.

:param path (str): database's directory path.

Local database

Local database, query, and result classes.

shelfdb.shelf

ShelfDB shelf/domain public API.

DB

Database class to manage an LMDB environment and local query execution.

shelf 

shelf(shelf_name: str) -> 'ShelfQuery'

Create a lazy embedded query outside an active transaction.

transaction 

transaction(write: bool = False)

Open one local transaction and yield its explicit transaction handle.

Item

Bases: tuple

Internal tuple-like (key, data) result used by local execution.

LMDBStore

Wrap one named LMDB database with MessagePack-backed persistence helpers.

Attributes

_env Shared LMDB environment used to open transactions. _db Handle for the named database inside _env. _item_type Callable used to wrap decoded (key, data) pairs returned by reads.

__init__ 

__init__(env, db_handle, item_type)

Store the LMDB environment, named database handle, and item wrapper.

Parameters

env Shared LMDB environment that owns the named database. db_handle Handle for the named database inside env. item_type Callable used to wrap decoded (key, data) pairs.

begin 

begin(write: bool = False)

Open a transaction bound to this named database.

delete 

delete(key: str, txn=None)

Delete one key and return LMDB's success result.

items 

items(txn=None) -> Iterator

Yield decoded items, reusing an existing transaction when provided.

key 

key(key: str, txn=None)

Return one decoded item by key, or None when it is missing.

key_range 

key_range(start: str, end: str, txn=None) -> Iterator

Yield decoded items whose keys fall in [start, end).

keys_in 

keys_in(keys: Iterable[str], txn=None)

Return decoded items for each requested key in input order.

put 

put(key: str, data: dict[str, Any], txn=None)

Write one mapping payload, reusing an existing transaction when provided.

put_many 

put_many(
    items: Iterable[tuple[str, dict[str, Any]]], txn=None
)

Write multiple mapping payloads, reusing an existing transaction when provided.

QueryBuilderMixin

Build serialized query steps by cloning the current query object.

Shelf

Executed chainable selection over one LMDB named database.

ShelfQuery

Bases: QueryBuilderMixin

Lazy chainable query over one LMDB named database.

Transaction

Active embedded transaction used for explicit transaction-scoped queries.

shelf 

shelf(shelf_name: str) -> 'ShelfQuery'

Create one query builder bound to this active transaction.

normalize_result 

normalize_result(result: Any)

Convert ShelfDB execution results into plain Python values.

replay_queries 

replay_queries(current, queries: Iterable[QueryStep])

Apply serialized query steps to a shelf-like object.

Client

Sync and async remote client types.

shelfdb.client

ShelfDB client package public API.

Server

Programmatic server type for running ShelfDB over TCP or a Unix socket.

shelfdb.server

ShelfDB server package public API.

ShelfServer

ShelfDB asyncio server

open_db 

open_db(path: str) -> DB

Open database, return shelfdb.DB object.

:param path (str): database's directory path.

CLI

CLI entry points and server configuration helpers.

shelfdb.cli

Cyclopts-powered CLI entrypoint for ShelfDB server and skills.

parse_server_url 

parse_server_url(url: str) -> tuple[str, str | int]

Parse a TCP or Unix server URL into transport-specific values.

skill_install 

skill_install(path: Path | None = None)

Install the bundled ShelfDB AI skill into a Codex skills directory.

Logging

Logging helpers for configuring ShelfDB debug output.

shelfdb.log

ShelfDB logging helpers built on structlog and stdlib logging.

configure_logging 

configure_logging(log_level: str = 'info')

Configure ShelfDB logging using stdlib logging and structlog.

normalize_log_level 

normalize_log_level(log_level: str) -> int

Normalize one textual log level into a stdlib logging level.

Security