shelfdb
Tiny LMDB-backed shelf database utilities.
Installation
pip install shelfdb
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")
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
DBobject 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.
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()
1 maintainer
Release files for shelfdb 3.0.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| shelfdb-3.0.2.tar.gz | 16.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| shelfdb-3.0.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 41.1 kB
Release files / shelfdb-3.0.2.tar.gz
| Download URL | shelfdb-3.0.2.tar.gz |
|---|---|
| Size | 16.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d8c8cd2dd644f1f48b9d35261a56e45bfb5a59935ff7e2670c42dc4d4865ce8e
|
|
BLAKE2b-256 checksum How to use checksums |
6b6270cdc7c95fe059c63709168770d392e94498c20aa4e654e539253ac9e0c9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / shelfdb-3.0.2-py3-none-any.whl
| Download URL | shelfdb-3.0.2-py3-none-any.whl |
|---|---|
| Size | 24.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e51016e823e322058178c8dae2e7d68ede6119521d3c075d24350f870bfdcce6
|
|
BLAKE2b-256 checksum How to use checksums |
b57e3b3189bc1a3829da99d0f5afaf1a40deb3c278272e484fc148c3e5862451
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
