shelfdb 2.0.0.dev0__tar.gz → 2.1.0rc1__tar.gz

shelfdb-2.1.0rc1/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: shelfdb
+Version: 2.1.0rc1
+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: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Dist: cyclopts>=4.10.2
+Requires-Dist: dictify>=4.0.0,<4.1
+Requires-Dist: dill>=0.4.0,<0.5
+Requires-Dist: lmdb>=1.7.3,<2
+Requires-Dist: msgpack>=1.1.2,<2
+Requires-Dist: structlog>=25.1.0,<26
+Requires-Dist: uvloop>=0.22.0,<0.23 ; sys_platform == 'linux'
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# shelfdb
+
+Tiny LMDB-backed shelf database utilities.
+
+## 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()
+```

shelfdb-2.1.0rc1/README.md

@@ -0,0 +1,63 @@
+# shelfdb
+
+Tiny LMDB-backed shelf database utilities.
+
+## 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()
+```

shelfdb-2.1.0rc1/ai-skill/shelfdb-usage/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: shelfdb-usage
+description: Use ShelfDB correctly in this repository when writing code, tests, docs, examples, or answering questions about ShelfDB usage. Trigger this skill when work involves starting the ShelfDB server, using the async remote client, using the local direct DB API, choosing between local and remote access, or pointing users to the right ShelfDB docs and examples.
+---
+
+# ShelfDB usage
+
+Use ShelfDB in one of two modes:
+
+- **Remote client/server**: start `shelfdb server`, connect with `shelfdb.client.Client`, open async transactions, and end remote reads or writes with `await ...query()`.
+- **Local direct DB**: open `shelfdb.shelf.DB(...)`, use local transactions, and run queries directly without `.query()`.
+
+## Core rules
+
+- Prefer the **remote client** flow for application code and flexible deployment.
+- Use **local DB access** only when the process can open the database directly.
+- For remote usage, remember: builder methods do nothing until `await .query()`.
+- For local usage, do not add `.query()`; local operations run directly.
+- Use `client.transaction()` for reads and `client.transaction(write=True)` for mutations.
+- Close remote clients with `await client.close()`.
+- Start the server with `shelfdb server`; default URL is `tcp://127.0.0.1:31337` and default DB path is `db`.
+
+## Read the bundled docs for details
+
+Read the skill-local docs under `ai-skill/shelfdb-usage/docs/` as needed:
+
+- `docs/index.md` — overview, fit, and navigation
+- `docs/usage/installation.md` — install and CLI verification
+- `docs/usage/server.md` — server startup and URL formats
+- `docs/usage/remote.md` — async client usage and `.query()` behavior
+- `docs/usage/local.md` — direct local DB usage
+- `docs/api/index.md` — API reference index
+- `docs/api/client.md` — remote client API
+- `docs/api/local.md` — local DB API
+- `docs/api/cli.md` — CLI reference
+
+## Practical guidance
+
+- If the user asks for app code that talks to a running ShelfDB instance, use the remote client API.
+- If the user asks for simple in-process storage examples, use `DB(...)` and local transactions.
+- If the user is confused about why nothing happens remotely, check whether `.query()` is missing.
+- If the user needs a server command example, prefer `shelfdb server --db-path ./db --url tcp://127.0.0.1:31337` unless they need a Unix socket.

shelfdb-2.1.0rc1/ai-skill/shelfdb-usage/docs/api/cli.md

@@ -0,0 +1,56 @@
+# CLI Reference
+
+ShelfDB currently provides one main CLI command for running the server.
+
+## `shelfdb server`
+
+Run the ShelfDB protocol server.
+
+```bash
+$ shelfdb server --help
+Usage: shelfdb server [ARGS]
+
+Run the ShelfDB protocol server.
+
+╭─ Parameters ─────────────────────────────────────────────────────────────────╮
+│ DB-PATH --db-path  [default: db]                                             │
+│ URL --url          [default: tcp://127.0.0.1:31337]                          │
+╰──────────────────────────────────────────────────────────────────────────────╯
+```
+
+### Options
+
+- `--db-path PATH` — database directory path, default: `db`
+- `--url URL` — server target URL, default: `tcp://127.0.0.1:31337`
+
+Supported URL styles:
+
+- `tcp://127.0.0.1:31337`
+- `unix:///tmp/shelfdb.sock`
+- `unix://tmp/shelfdb.sock`
+
+### Examples
+
+Run with the default TCP address:
+
+```bash
+shelfdb server
+```
+
+Run on a specific TCP address:
+
+```bash
+shelfdb server --db-path ./db --url tcp://0.0.0.0:31337
+```
+
+Run on a Unix socket:
+
+```bash
+shelfdb server --db-path ./db --url unix:///tmp/shelfdb.sock
+```
+
+Run on a relative Unix socket path:
+
+```bash
+shelfdb server --url unix://tmp/shelfdb.sock
+```

shelfdb-2.1.0rc1/ai-skill/shelfdb-usage/docs/api/client.md

@@ -0,0 +1,217 @@
+# Client API
+
+Use the client API when your application talks to a running ShelfDB server over TCP or Unix sockets.
+
+## `Client`
+
+`Client` is the main entry point for remote usage.
+
+Typical flow:
+
+1. connect with `Client.connect(...)`
+2. open a transaction with `client.transaction(...)`
+3. work with a shelf inside the transaction
+4. execute remote reads or writes with `.query()`
+5. close the client with `client.close()`
+
+## `Client.connect(target: str) -> Client`
+
+Connect to a ShelfDB server.
+
+Supported targets:
+
+- `tcp://127.0.0.1:31337`
+- `unix:///tmp/shelfdb.sock`
+- `unix://tmp/shelfdb.sock`
+
+```python
+from shelfdb.client import Client
+
+client = await Client.connect("tcp://127.0.0.1:31337")
+```
+
+## `client.transaction(*, write: bool = False) -> ClientTransaction`
+
+Open a remote transaction.
+
+Use the default `write=False` for read-only work. Use `write=True` for mutations.
+
+```python
+async with client.transaction() as tx:
+    users = tx.shelf("users")
+    count = await users.count().query()
+```
+
+## `client.close() -> None`
+
+Close the client connection.
+
+```python
+await client.close()
+```
+
+## Query object from `tx.shelf(name)`
+
+Inside a client transaction, `tx.shelf("users")` returns a remote query object.
+
+Builder methods only build query state locally. Remote execution happens only when you await `.query()`.
+
+```python
+users = tx.shelf("users")
+alice = await users.key("alice").item().query()
+```
+
+## Selection methods
+
+### `key(key: str) -> RemoteShelfQuery`
+
+Select one key.
+
+```python
+alice = await users.key("alice").item().query()
+```
+
+### `keys_range(start: str, stop: str | None = None) -> RemoteShelfQuery`
+
+Select keys in the half-open range `[start, stop)`.
+
+```python
+result = await users.keys_range("bob", "d").query()
+```
+
+### `keys() -> RemoteShelfQuery`
+
+Project the current selection to keys.
+
+```python
+result = await users.items().keys().query()
+```
+
+### `items() -> RemoteShelfQuery`
+
+Project the current selection to loaded key/value items.
+
+```python
+result = await users.items().query()
+```
+
+### `asc() -> RemoteShelfQuery`
+
+Use ascending key order.
+
+### `desc() -> RemoteShelfQuery`
+
+Use descending key order.
+
+```python
+result = await users.desc().query()
+```
+
+## Transform methods
+
+### `filter(fn) -> RemoteShelfQuery`
+
+Filter matching items.
+
+```python
+admins = await users.filter(
+    lambda item: item.value["role"] == "admin"
+).query()
+```
+
+### `slice(start: int | None = None, stop: int | None = None, step: int | None = None) -> RemoteShelfQuery`
+
+Slice the current selection.
+
+```python
+result = await users.sort(reverse=True).slice(0, 2).query()
+```
+
+### `sort(key=None, reverse: bool = False) -> RemoteShelfQuery`
+
+Sort the current selection.
+
+```python
+result = await users.sort(reverse=True).query()
+```
+
+## Terminal execution
+
+### `query() -> Any`
+
+Execute the built remote query or action.
+
+This is the only terminal method on the remote client.
+
+```python
+count = await users.count().query()
+```
+
+## Read actions
+
+### `count() -> RemoteShelfQuery`
+
+Build an action that returns the number of selected items.
+
+```python
+count = await users.count().query()
+```
+
+### `exists() -> RemoteShelfQuery`
+
+Build an action that returns whether the selection exists.
+
+```python
+exists = await users.key("alice").exists().query()
+```
+
+### `item() -> RemoteShelfQuery`
+
+Build an action that returns exactly one item.
+
+Raises an error if zero or more than one item matches.
+
+```python
+alice = await users.key("alice").item().query()
+```
+
+## Write actions
+
+### `put(key: str, value: Any) -> RemoteShelfQuery`
+
+Build an action that stores one key/value pair.
+
+```python
+await users.put("alice", {"role": "admin"}).query()
+```
+
+### `put_many(items: list[Item]) -> RemoteShelfQuery`
+
+Build an action that stores multiple items.
+
+```python
+from shelfdb.shelf import Item
+
+await users.put_many([
+    Item("alice", {"role": "admin"}),
+    Item("bob", {"role": "user"}),
+]).query()
+```
+
+### `update(fn) -> RemoteShelfQuery`
+
+Build an action that updates the selected items using `fn`.
+
+```python
+await users.key("alice").update(
+    lambda item: {**item.value, "active": True}
+).query()
+```
+
+### `delete() -> RemoteShelfQuery`
+
+Build an action that deletes the selected items.
+
+```python
+await users.key("alice").delete().query()
+```

shelfdb-2.1.0rc1/ai-skill/shelfdb-usage/docs/api/index.md

@@ -0,0 +1,14 @@
+# API Reference
+
+This section documents the public usage surface of ShelfDB.
+
+It complements the usage guides:
+
+- the usage pages explain the workflow and mental model
+- the API pages list the public entry points, signatures, and common examples
+
+Available reference pages:
+
+- [Client API](client.md)
+- [Local DB API](local.md)
+- [CLI Reference](cli.md)

shelfdb-2.1.0rc1/ai-skill/shelfdb-usage/docs/api/local.md

@@ -0,0 +1,157 @@
+# Local DB API
+
+Use the local API when your code can open the database directly.
+
+## `DB`
+
+`DB` is the main entry point for direct local usage.
+
+## `DB(path: str, *, map_size: int = 1024 * 1024 * 1024, max_dbs: int = 128)`
+
+Open a local ShelfDB database.
+
+```python
+from shelfdb.shelf import DB
+
+with DB("./db") as db:
+    ...
+```
+
+## `db.transaction(*, write: bool = True) -> Transaction`
+
+Open a local transaction.
+
+Use `write=True` for writes and `write=False` for read-only access.
+
+```python
+with DB("./db") as db:
+    with db.transaction(write=False) as tx:
+        users = tx.shelf("users")
+        count = users.count()
+```
+
+## Query object from `tx.shelf(name)`
+
+Inside a local transaction, `tx.shelf("users")` returns a query object.
+
+Unlike remote client usage, local queries run directly and do not end with `.query()`.
+
+```python
+users = tx.shelf("users")
+alice = users.key("alice").item()
+```
+
+## Selection methods
+
+### `key(key: str) -> ShelfQuery`
+
+Select one key.
+
+### `keys_range(start: str, stop: str | None = None) -> ShelfQuery`
+
+Select keys in the half-open range `[start, stop)`.
+
+### `keys() -> ShelfQuery`
+
+Project the current selection to keys.
+
+### `items() -> ShelfQuery`
+
+Project the current selection to loaded key/value items.
+
+### `asc() -> ShelfQuery`
+
+Use ascending key order.
+
+### `desc() -> ShelfQuery`
+
+Use descending key order.
+
+```python
+result = list(users.desc())
+```
+
+## Transform methods
+
+### `filter(fn) -> ShelfQuery`
+
+Filter matching items.
+
+```python
+admins = list(users.filter(lambda item: item.value["role"] == "admin"))
+```
+
+### `slice(start: int | None = None, stop: int | None = None, step: int | None = None) -> ShelfQuery`
+
+Slice the current selection.
+
+```python
+result = list(users.sort(reverse=True).slice(0, 2))
+```
+
+### `sort(key=None, reverse: bool = False) -> ShelfQuery`
+
+Sort the current selection.
+
+```python
+result = list(users.sort(reverse=True))
+```
+
+## Read methods
+
+### `count() -> int`
+
+Return the number of selected items.
+
+### `exists() -> bool`
+
+Return whether the current selection contains at least one item.
+
+### `item() -> Item`
+
+Return exactly one selected item.
+
+Raises an error if zero or more than one item matches.
+
+```python
+alice = users.key("alice").item()
+```
+
+## Write methods
+
+### `put(key: str, value: Any) -> MutationResult`
+
+Store one key/value pair.
+
+```python
+users.put("alice", {"role": "admin"})
+```
+
+### `put_many(items: Iterable[Item]) -> list[MutationResult]`
+
+Store multiple items.
+
+```python
+from shelfdb.shelf import Item
+
+users.put_many([
+    Item("alice", {"role": "admin"}),
+    Item("bob", {"role": "user"}),
+])
+```
+
+### `update(fn) -> list[MutationResult]`
+
+Update the selected items using `fn`.
+
+```python
+users.key("alice").update(lambda item: {**item.value, "active": True})
+```
+
+### `delete() -> list[MutationResult]`
+
+Delete the selected items.
+
+```python
+users.key("alice").delete()
+```

shelfdb-2.1.0rc1/ai-skill/shelfdb-usage/docs/index.md

@@ -0,0 +1,67 @@
+# ShelfDB
+
+ShelfDB is a simple, fast key-value database for Python asyncio apps.
+
+Store Python values like `str`, `int`, `dict`, `list`, and `bytes` with transactions, query chaining, and flexible local or client/server access over TCP or Unix sockets.
+
+## Quick example
+
+```python
+from shelfdb.shelf import DB
+
+with DB("./db") as db:
+    with db.transaction(write=True) as tx:
+        users = tx.shelf("users")
+        users.put("alice", {"role": "admin", "age": 30})
+
+    with db.transaction(write=False) as tx:
+        users = tx.shelf("users")
+        alice = users.key("alice").item()
+        print(alice)
+```
+
+Other access styles:
+
+- [Remote client usage over TCP](usage/remote.md)
+- [Remote client usage over Unix sockets](usage/remote.md)
+
+## Key features
+
+- **Simple key-value model** for application data
+- **Asyncio-friendly client usage** for Python async applications
+- **Transactions** for reads and writes
+- **Client/server access** over TCP or Unix sockets
+- **Local direct access** when your code can open the database itself
+- **Chainable query style** for readable data access
+
+## Where ShelfDB fits
+
+ShelfDB fits between TinyDB and SQLite for Python application storage.
+
+| Feature | ShelfDB | SQLite | TinyDB |
+| --- | --- | --- | --- |
+| Type of data store | Key-value store | Relational SQL database | Document database |
+| Asyncio-friendly client usage | Yes | Limited / adapter-based | No |
+| Transactions | Yes | Yes | No |
+| Client/server access | Yes | Not the usual model | No |
+| Local direct access | Yes | Yes | Yes |
+| Chainable Python query style | Yes | No | Yes |
+
+ShelfDB is a good fit when you want something simpler than a SQL workflow, but more structured and deployable than a tiny in-process document store.
+
+## When to use it
+
+ShelfDB fits well when you want:
+
+- a simple database for Python asyncio applications
+- application state, metadata, caches, queues, or internal tools
+- a local database today with the option to move to client/server access later
+- something simpler than SQL for app storage
+- something more structured than a tiny JSON-style store
+
+## Next steps
+
+- Start with [Installation](usage/installation.md)
+- Learn how to [run the server](usage/server.md)
+- See [remote client usage](usage/remote.md)
+- See [local database usage](usage/local.md)