shelfdb 1.1.1__tar.gz → 2.0.0.dev0__tar.gz

shelfdb-2.0.0.dev0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: shelfdb
+Version: 2.0.0.dev0
+Summary: A tiny documents database for Python
+Keywords: dict,json,database
+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
+
+ShelfDB is a tiny document database for Python that stores JSON-like dictionaries in LMDB.
+
+Docs: build and browse the MkDocs site from `docs-src/`.
+
+## Install
+
+```shell
+pip install shelfdb
+```
+
+## Develop
+
+```shell
+uv sync --dev
+uv run pytest
+uv build
+```
+
+## Local API
+
+Local queries are lazy. Build a query chain and call `.run()` to execute it.
+
+```python
+from datetime import datetime
+
+import shelfdb
+
+db = shelfdb.open("db")
+
+db.shelf("note").put(
+    "note-1",
+    {
+        "title": "Shelf DB",
+        "content": "Simple note",
+        "created_at": datetime.utcnow().isoformat(),
+    },
+).run()
+
+notes = (
+    db.shelf("note")
+    .filter(lambda item: item[1]["title"] == "Shelf DB")
+    .run()
+)
+
+print(sorted(notes, key=lambda item: item[1]["created_at"]))
+```
+
+`run()` returns a one-shot iterator for local multi-item queries. Each item has the server-style
+shape `["key", data]`, so use `item[0]` for the key and `item[1]` for the stored document.
+
+## Server
+
+Start the asyncio server:
+
+```shell
+shelfdb
+```
+
+Or choose an explicit transport:
+
+```shell
+shelfdb --url tcp://127.0.0.1:17000
+shelfdb --url unix:///tmp/shelfdb.sock
+```
+
+Control server logging with stdlib-integrated structlog:
+
+```shell
+shelfdb --log-level info
+shelfdb --log-level debug
+```
+
+If you use the Python client directly, call `shelfdb.log.configure_logging(...)` first to
+see client-side debug logs as well.
+
+## Network Client
+
+RPC queries are also lazy and execute on `.run()`.
+
+```python
+import shelfdb
+
+
+def main():
+    db = shelfdb.connect("tcp://127.0.0.1:17000")
+    note = db.shelf("note").key("note-1").first().run()
+    print(note)
+
+
+main()
+```
+
+## Security
+
+The RPC protocol uses Python object deserialization and can transport Python callables.
+Only use the server with trusted local clients.

shelfdb-2.0.0.dev0/README.md

@@ -0,0 +1,98 @@
+# ShelfDB
+
+ShelfDB is a tiny document database for Python that stores JSON-like dictionaries in LMDB.
+
+Docs: build and browse the MkDocs site from `docs-src/`.
+
+## Install
+
+```shell
+pip install shelfdb
+```
+
+## Develop
+
+```shell
+uv sync --dev
+uv run pytest
+uv build
+```
+
+## Local API
+
+Local queries are lazy. Build a query chain and call `.run()` to execute it.
+
+```python
+from datetime import datetime
+
+import shelfdb
+
+db = shelfdb.open("db")
+
+db.shelf("note").put(
+    "note-1",
+    {
+        "title": "Shelf DB",
+        "content": "Simple note",
+        "created_at": datetime.utcnow().isoformat(),
+    },
+).run()
+
+notes = (
+    db.shelf("note")
+    .filter(lambda item: item[1]["title"] == "Shelf DB")
+    .run()
+)
+
+print(sorted(notes, key=lambda item: item[1]["created_at"]))
+```
+
+`run()` returns a one-shot iterator for local multi-item queries. Each item has the server-style
+shape `["key", data]`, so use `item[0]` for the key and `item[1]` for the stored document.
+
+## Server
+
+Start the asyncio server:
+
+```shell
+shelfdb
+```
+
+Or choose an explicit transport:
+
+```shell
+shelfdb --url tcp://127.0.0.1:17000
+shelfdb --url unix:///tmp/shelfdb.sock
+```
+
+Control server logging with stdlib-integrated structlog:
+
+```shell
+shelfdb --log-level info
+shelfdb --log-level debug
+```
+
+If you use the Python client directly, call `shelfdb.log.configure_logging(...)` first to
+see client-side debug logs as well.
+
+## Network Client
+
+RPC queries are also lazy and execute on `.run()`.
+
+```python
+import shelfdb
+
+
+def main():
+    db = shelfdb.connect("tcp://127.0.0.1:17000")
+    note = db.shelf("note").key("note-1").first().run()
+    print(note)
+
+
+main()
+```
+
+## Security
+
+The RPC protocol uses Python object deserialization and can transport Python callables.
+Only use the server with trusted local clients.

shelfdb-2.0.0.dev0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["uv_build>=0.11.3,<0.12"]
+build-backend = "uv_build"
+
+[project]
+name = "shelfdb"
+version = "2.0.0.dev0"
+description = "A tiny documents database for Python"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Nitipit Nontasuwan", email = "nitipit@gmail.com" },
+]
+keywords = ["dict", "json", "database"]
+classifiers = [
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "cyclopts>=4.10.2",
+    "dictify>=4.0.0,<4.1",
+    "dill>=0.4.0,<0.5",
+    "lmdb>=1.7.3,<2",
+    "msgpack>=1.1.2,<2",
+    "structlog>=25.1.0,<26",
+    "uvloop>=0.22.0,<0.23; platform_system == 'Linux'",
+]
+
+[project.scripts]
+shelfdb = "shelfdb.cli:main"
+
+[dependency-groups]
+dev = [
+    "dictify>=4.0.0,<4.1",
+    "mkdocs>=1.6.1,<2",
+    "mkdocs-shadcn>=0.10.4,<0.11",
+    "mkdocstrings[python]>=0.29.0,<0.30",
+    "pytest>=8.4.2,<9",
+]
+
+[tool.uv.build-backend]
+module-name = "shelfdb"
+module-root = "src"

{shelfdb-1.1.1 → shelfdb-2.0.0.dev0/src}/shelfdb/__init__.py

@@ -1,3 +1,5 @@
+from .client import connect as connect
+from .client import connect_async as connect_async
 from .shelf import DB
 
 

shelfdb-2.0.0.dev0/src/shelfdb/ai_skill/__init__.py

@@ -0,0 +1 @@
+"""ShelfDB bundled AI skills."""

shelfdb-2.0.0.dev0/src/shelfdb/ai_skill/shelfdb-usage/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: shelfdb-usage
+description: "ShelfDB developer workflow for running the local server and querying it from sync or async Python clients. Use when Codex needs to write or debug ShelfDB server-mode code, client queries, transactions, logging, or examples that call `shelfdb.connect`, `connect_async`, `.run()`, or `tx.commit()`."
+---
+
+# ShelfDB usage
+
+Prefer the simplest mode that fits the task.
+
+## Reference docs
+
+- Read `references/docs/` for mirrored ShelfDB documentation when you need the full narrative docs.
+- Prefer the most specific page for the task: `server-mode.md`, `query-model.md`, `transactions.md`, and `security.md` are the usual first reads.
+
+## Choose the mode
+
+- Use embedded mode with `shelfdb.open(...)` when the process can access the LMDB directory directly.
+- Use server mode only when a separate process or multi-client access is required.
+
+## Start the server
+
+- Run `shelfdb` for the default TCP server on `127.0.0.1:17000` with the `db/` directory.
+- Use `shelfdb --url tcp://HOST:PORT` or `shelfdb --url unix:///path/to/socket.sock` when an explicit transport is needed.
+- Keep the server on loopback or a Unix socket. Treat the RPC layer as trusted-local only.
+
+## Connect from Python
+
+- Use `shelfdb.connect(url)` in sync code.
+- Use `await shelfdb.connect_async(url)` in async code.
+- Await only `connect_async(...)`, `query.run()` in async code, and `tx.commit()`.
+
+## Build queries lazily
+
+- Chain query methods and execute only with `.run()`.
+- Reuse the same query object when you need to run the same pipeline again.
+- Use the same query style in embedded and remote code.
+
+Available operations:
+
+- Read: `key`, `key_range`, `keys_in`, `filter`, `slice`, `first`, `count`
+- Write: `put`, `put_many`, `update`, `replace`, `edit`, `delete`
+
+## Handle results correctly
+
+- Local multi-item `.run()` returns a one-shot iterator of `['key', data]` items; wrap it in `list(...)` if you need reuse.
+- Remote results are normalized into plain Python values.
+- `first()` returns one item or `None`.
+- `put_many()` returns `None`.
+
+## Respect batch and transaction behavior
+
+- Pass iterables to `put_many()` and `keys_in()`, but assume the client materializes them before send.
+- `keys_in()` keeps the requested key order and may repeat keys.
+- Use `client.transaction(write=True)` for remote batches; queue queries with `.run()` and send them with `tx.commit()`.
+- Use `db.transaction(write=True)` for embedded atomic writes; inside a local transaction, use `tx.shelf(...)`, not `db.shelf(...)`.
+
+## Safety checks
+
+- Keep callable `filter()` and `edit()` functions simple and trusted; the protocol uses `dill`.
+- Configure debug logs with `shelfdb.log.configure_logging("debug")` when diagnosing client or server behavior.
+- Do not expose the server to untrusted networks.
+
+## Minimal patterns
+
+```python
+import shelfdb
+
+client = shelfdb.connect("tcp://127.0.0.1:17000")
+note = client.shelf("note").key("note-1").first().run()
+```
+
+```python
+import asyncio
+import shelfdb
+
+
+async def main():
+    client = await shelfdb.connect_async("unix:///tmp/shelfdb.sock")
+    rows = await client.shelf("note").keys_in(["note-1", "note-2"]).run()
+    print(rows)
+
+
+asyncio.run(main())
+```
+
+```python
+tx = client.transaction(write=True)
+tx.shelf("note").put("note-1", {"title": "ShelfDB"}).run()
+tx.commit()
+```

shelfdb-2.0.0.dev0/src/shelfdb/ai_skill/shelfdb-usage/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ShelfDB Usage"
+  short_description: "ShelfDB server/client usage guide"
+  default_prompt: "Use $shelfdb-usage to help with ShelfDB server startup, client queries, and remote transactions."

shelfdb-2.0.0.dev0/src/shelfdb/ai_skill/shelfdb-usage/references/docs/api-reference.md

@@ -0,0 +1,74 @@
+# API Reference
+
+This page is the generated reference for the public Python modules.
+
+Use the narrative pages first if you are learning ShelfDB. Come back here when you want exact
+signatures, annotations, class members, or module-level details.
+
+## Protocol
+
+Start with the [Protocol](protocol.md) page for the conceptual overview and module guide.
+
+The sections below show the public `shelfdb.protocol` package surface and the protocol submodules.
+
+::: shelfdb.protocol
+
+### `shelfdb.protocol.schema`
+
+Typed protocol shapes and schema models.
+
+::: shelfdb.protocol.schema
+
+### `shelfdb.protocol.query`
+
+Serialized query-step builders.
+
+::: shelfdb.protocol.query
+
+### `shelfdb.protocol.payload`
+
+Request and response payload helpers.
+
+::: shelfdb.protocol.payload
+
+### `shelfdb.protocol.codec`
+
+Byte-level request and response codecs.
+
+::: shelfdb.protocol.codec
+
+## Package
+
+Top-level package exports such as `open()`, `connect()`, and `connect_async()`.
+
+::: shelfdb
+
+## Local database
+
+Local database, query, and result classes.
+
+::: shelfdb.shelf
+
+## Client
+
+Sync and async remote client types.
+
+::: shelfdb.client
+
+## Server
+
+Programmatic server type for running ShelfDB over TCP or a Unix socket.
+
+::: shelfdb.server
+
+## CLI
+
+CLI entry points and server configuration helpers.
+
+::: shelfdb.cli
+
+## Logging
+
+Logging helpers for configuring ShelfDB debug output.
+
+::: shelfdb.log

shelfdb-2.0.0.dev0/src/shelfdb/ai_skill/shelfdb-usage/references/docs/embedded-mode.md

@@ -0,0 +1,155 @@
+# Embedded Mode
+
+Use `shelfdb.open()` when you want ShelfDB as an embedded database inside your Python process.
+
+This is the default way to use the project: your Python process talks directly to LMDB and no
+separate server is required.
+
+## Open a database
+
+```python
+import shelfdb
+
+db = shelfdb.open("db")
+```
+
+`db` is a `shelfdb.DB` object.
+
+## Choose a shelf
+
+A shelf is a named collection of keyed documents.
+
+```python
+notes = db.shelf("note")
+users = db.shelf("user")
+```
+
+Each shelf name is independent, so you can organize documents by purpose.
+
+## Read data
+
+Read everything in a shelf:
+
+```python
+all_notes = db.shelf("note").run()
+print(list(all_notes))
+```
+
+Read one item by key:
+
+```python
+note = db.shelf("note").key("note-1").first().run()
+```
+
+Filter matching items:
+
+```python
+matching = list(db.shelf("note").filter(lambda item: item[1]["title"] == "updated").run())
+```
+
+Range and slice:
+
+```python
+selected = list(
+    db.shelf("note")
+    .key_range("note-1", "note-5")
+    .slice(0, 5)
+    .run()
+)
+```
+
+Fetch exact keys:
+
+```python
+picked = list(db.shelf("note").keys_in(["note-1", "note-3"]).run())
+```
+
+If you need custom ordering, sort the returned Python values yourself after `.run()`.
+
+Count matches:
+
+```python
+count = db.shelf("note").count().run()
+```
+
+## Write data
+
+Insert or replace one document:
+
+```python
+db.shelf("note").put("note-1", {"title": "hello"}).run()
+db.shelf("note").put("note-1", {"title": "updated"}).run()
+```
+
+Write many documents:
+
+```python
+db.shelf("note").put_many(
+    [
+        ("note-1", {"title": "hello"}),
+        ("note-2", {"title": "world"}),
+    ]
+).run()
+```
+
+Merge fields into existing documents:
+
+```python
+db.shelf("note").key("note-1").update({"views": 1}).run()
+```
+
+Replace a full document:
+
+```python
+db.shelf("note").key("note-1").replace({"title": "replaced"}).run()
+```
+
+Transform with a function:
+
+```python
+db.shelf("note").key("note-1").edit(
+    lambda item: {"title": item[1]["title"], "status": "published"}
+).run()
+```
+
+Delete matching items:
+
+```python
+db.shelf("note").key("note-1").delete().run()
+```
+
+`update()`, `replace()`, and `edit()` require an existing selection. If nothing matches, they
+raise an error instead of silently creating a new document. All write queries run atomically by
+default, even outside `db.transaction(write=True)`; use an explicit write transaction when you
+need multiple queries to commit together. `delete()` is safe on a missing key and returns an
+empty result. `put_many()` writes multiple documents and returns `None`.
+
+Embedded multi-item `run()` results are one-shot iterators.
+
+## Result types
+
+Embedded execution uses these main types:
+
+- `shelfdb.DB` for the database
+- `shelfdb.shelf.ShelfQuery` for lazy embedded query builders
+- one-shot iterators from `run()` for executed selections
+
+Each yielded item uses the server-style shape `["key", {"title": "example"}]`.
+
+## Close the database
+
+When you are done with the embedded database:
+
+```python
+db.close()
+```
+
+## Transactions
+
+For consistent reads and atomic writes, use `with db.transaction(...) as tx:` and create
+transaction-scoped queries with `tx.shelf(...)`.
+
+Inside the block, embedded `.run()` calls execute immediately. Remote client transactions queue
+their steps until `tx.commit()`.
+
+See [Transactions](transactions.md) for the full behavior and examples.