shelfdb

Tiny LMDB-backed shelf database utilities.

Installation

pip install shelfdb

Warning

The client/server protocol uses dill to support Python callables. Only use it between trusted processes; do not expose the server to untrusted clients or public networks.

Development

Install development dependencies:

uv sync --dev

Run the complete non-publishing release gate:

uv run python -m dev release-check

The gate audits locked dependencies, checks formatting, linting, types, supported Python versions, strict documentation, release artifacts, metadata, and a clean wheel installation. GitHub Actions runs the same gate on pull requests, main, and version tags. Before tagging, authenticated release maintainers also check GitHub's repository alerts:

uv run python -m dev release-check --github

Serve the docs locally (Zensical dev server; live reload is built in):

uv run python -m dev docs serve --port 9001 --livereload

--livereload is a legacy compatibility flag and is intentionally ignored by Zensical (as Zensical has built-in live reload for docs serving).

Build docs for verification (Zensical build):

uv run python -m dev docs build

Publish the docs with mike to the docs branch:

uv run python -m dev docs publish

Override the publish target when needed:

uv run python -m dev docs publish --publish-version 3.0.1 --alias latest --branch docs --remote origin

Server

Run the protocol server:

shelfdb server

Run the protocol server on a custom address:

shelfdb server --url "tcp://0.0.0.0:17001" --db-path ./db

Client

Connect a client:

from shelfdb.client import Client

client = await Client.connect("tcp://127.0.0.1:31337")

Unix sockets also work:

from shelfdb.client import Client

client = await Client.connect("unix:///tmp/shelfdb.sock")

Example

from shelfdb.client import Client

client = await Client.connect("tcp://127.0.0.1:31337")

try:
    async with client.transaction() as tx:
        users = tx.shelf("users")

        count = await users.count().query()
        alice = await users.key("alice").item().query()
        admins = await users.filter(
            lambda item: item.value["role"] == "admin"
        ).sort(reverse=True).query()

    async with client.transaction(write=True) as tx:
        users = tx.shelf("users")

        await users.put("eve", {"role": "user"}).query()
        await users.key("eve").update(
            lambda item: {**item.value, "role": "admin"}
        ).query()
finally:
    await client.close()