Metadata-Version: 2.4
Name: shelfdb
Version: 3.0.1
Summary: A tiny database for Python
Author: Nitipit Nontasuwan
Author-email: Nitipit Nontasuwan <nitipit@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Dist: cyclopts>=4.10.2,<5
Requires-Dist: dill>=0.4.0,<0.5
Requires-Dist: lmdb>=1.7.3,<2
Requires-Dist: msgpack>=1.2.1,<2
Requires-Python: >=3.12
Project-URL: Documentation, https://keenlycode.github.io/shelfdb/
Project-URL: Repository, https://github.com/keenlycode/shelfdb
Description-Content-Type: text/markdown

# shelfdb

Tiny LMDB-backed shelf database utilities.

## Installation

```bash
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:

```bash
uv sync --dev
```

Run the complete non-publishing release gate:

```bash
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.

Serve the docs locally:

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

Publish the docs with mike to the `docs` branch:

```bash
uv run python -m dev docs publish
```

Override the publish target when needed:

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

## Server

Run the protocol server:

```bash
shelfdb server
```

Run the protocol server on a custom address:

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

## Client

Connect a client:

```python
from shelfdb.client import Client

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

Unix sockets also work:

```python
from shelfdb.client import Client

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

## Example

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