Skip to main content

shelfdb

Tiny LMDB-backed shelf database utilities.

Installation

pip install shelfdb

Development

Python 3.12–3.14 is supported. Development uses Python 3.14, selected by .python-version; compatibility checks cover Python 3.12 and 3.14. Python 3.15 is temporarily excluded because the released dill cannot serialize query callbacks on it; support will be reassessed after an upstream fix is released.

Install development dependencies:

uv sync --dev

Development tooling lives in src/dev/, outside the published shelfdb package. Use --directory src to run its module; workflow commands resolve paths from the repository root. Documentation macros live in src/macros.py.

Unit tests mirror src/ under tests/unit/: shelfdb/, dev/, and macros_test.py. Integration tests cover cross-layer behavior; tests/usage/ contains executable usage examples.

Run the complete non-publishing release gate:

uv run --directory src 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 --directory src python -m dev release-check --github

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

uv run --directory src 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 --directory src python -m dev docs build

Publish the docs with mike to the docs branch:

uv run --directory src python -m dev docs publish

Override the publish target when needed:

uv run --directory src 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")

Transaction behavior

  • Readers use independent LMDB snapshots and do not join the writer queue.
  • Remote write transactions queue, one writer at a time, across connections served by the same DB object on one event loop. Independent local writers and other server processes are outside this queue.
  • A normal exit from async with client.transaction(write=True) commits; an exception escaping the context rolls back the whole transaction. Catching a query error inside the context leaves commit/rollback up to you.
  • Keep transactions short: perform external HTTP/LLM calls before opening them. Long-lived readers can delay page reuse; long-lived writers hold up the queue.

See remote transaction usage for coordination limits and details on partial updates and error handling.

Large results

Remote messages are buffered, not streamed. The former 1 MiB cap is removed; only the unsigned 32-bit payload length remains (4 GiB minus 1 byte). Large queries can still exhaust memory, so paginate bulk reads with .slice(...). Store large assets externally and keep references in ShelfDB.

See pagination and its limits.

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()

Metadata

Release files for shelfdb 3.2.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 shelfdb 3.2.1
File Size Uploaded Provenance Actions
shelfdb-3.2.1.tar.gz 18.2 kB Without provenance Details for shelfdb-3.2.1.tar.gz

Built distribution (wheel)

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

Total release size: 41.9 kB

Release files / shelfdb-3.2.1.tar.gz

Download URL shelfdb-3.2.1.tar.gz
Size 18.2 kB
Tags Source
SHA-256 checksum
How to use checksums
644e1f3b86ffb2435e4f08c69a5fb0939777cd499d9c996e5cf0acea36bcd332
BLAKE2b-256 checksum
How to use checksums
08ed2d6c2d76a4d2bc29f87cd9101939fd96f093d3512b2de7c72779030e97a0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / shelfdb-3.2.1-py3-none-any.whl

Download URL shelfdb-3.2.1-py3-none-any.whl
Size 23.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
10e7ed6fd6c512216a2ca830ccf4ef58ba882e5eabc4f57d770f9b192fcc1ebf
BLAKE2b-256 checksum
How to use checksums
61dd2209e172f8e548d7edd7560635a9bacce9b37e7c9ce7a9e8d50efe758f4e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for shelfdb 3.2.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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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.

Release history Release notifications | RSS feed

This release

3.2.1 This release

2 release files No provenance

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