shelfdb 2.0.0.dev0__tar.gz → 3.0.1__tar.gz

shelfdb-3.0.1/PKG-INFO

@@ -0,0 +1,130 @@
+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()
+```

shelfdb-3.0.1/README.md

@@ -0,0 +1,111 @@
+# 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()
+```

shelfdb-3.0.1/ai-skill/shelfdb-usage/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: shelfdb-usage
+description: Use when writing, reviewing, or explaining ShelfDB local database code, async client/server code, transactions, or fluent queries.
+---
+
+# ShelfDB usage
+
+Choose access mode from the deployment:
+
+- Use `shelfdb.shelf.DB` when the process can open the LMDB database directly.
+- Use `shelfdb.client.Client` when a separate trusted process runs `shelfdb server`.
+
+## Safety boundary
+
+The remote protocol uses `dill` so queries can contain Python callables. Deserializing a
+request can execute arbitrary code in the server process. Never expose the server to
+untrusted clients or public networks.
+
+## Local API
+
+Use synchronous transactions. Operations execute directly; do not add `.query()`.
+
+```python
+from shelfdb.shelf import DB
+
+with DB("db") as db:
+    with db.transaction(write=False) as tx:
+        users = list(tx.shelf("users").items())
+```
+
+## Remote API
+
+Connect asynchronously, use read transactions by default, and pass `write=True` for
+mutations. Fluent operations only build a remote query; `await ...query()` sends it.
+
+```python
+from shelfdb.client import Client
+
+client = await Client.connect("tcp://127.0.0.1:31337")
+try:
+    async with client.transaction() as tx:
+        users = await tx.shelf("users").items().query()
+finally:
+    await client.close()
+```
+
+## Rules
+
+- Use `client.transaction()` for remote reads.
+- Use `client.transaction(write=True)` for remote mutations.
+- Always close a remote client with `await client.close()`.
+- Keep local and remote terminal behavior distinct.
+- In a ShelfDB source checkout, use `tests/usage/` as executable examples.
+- Consult the current documentation before assuming unsupported query behavior.
+
+Documentation: https://keenlycode.github.io/shelfdb/

shelfdb-3.0.1/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["uv_build>=0.11.3,<0.12"]
+build-backend = "uv_build"
+
+[project]
+name = "shelfdb"
+version = "3.0.1"
+description = "A tiny database for Python"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "cyclopts>=4.10.2,<5",
+    "dill>=0.4.0,<0.5",
+    "lmdb>=1.7.3,<2",
+    "msgpack>=1.2.1,<2",
+]
+
+[[project.authors]]
+name = "Nitipit Nontasuwan"
+email = "nitipit@gmail.com"
+
+[project.scripts]
+shelfdb = "shelfdb.cli:main"
+
+[project.urls]
+Documentation = "https://keenlycode.github.io/shelfdb/"
+Repository = "https://github.com/keenlycode/shelfdb"
+
+[dependency-groups]
+dev = [
+    "mike>=2.1.3,<3",
+    "mkdocs>=1.6.1,<2",
+    "mkdocs-shadcn>=0.10.4,<0.11",
+    "mkdocstrings[python]>=0.29.0,<0.30",
+    "pytest-cov>=7.0.0,<8",
+    "pymdown-extensions>=11.0.0,<12",
+    "pytest>=9.0.0,<10",
+    "ruff>=0.13.0,<0.14",
+    "tinydb>=4.8.2,<5",
+    "ty>=0.0.1a17,<0.0.2",
+]
+
+[tool.uv.build-backend]
+module-name = "shelfdb"
+module-root = "src"
+source-include = ["ai-skill/**"]
+
+[tool.uv.build-backend.data]
+data = "ai-skill"

shelfdb-2.0.0.dev0/pyproject.toml → shelfdb-3.0.1/pyproject.toml.orig

@@ -4,8 +4,8 @@ build-backend = "uv_build"
 
 [project]
 name = "shelfdb"
-version = "2.0.0.dev0"
-description = "A tiny documents database for Python"
+version = "3.0.1"
+description = "A tiny database for Python"
 readme = "README.md"
 requires-python = ">=3.12"
 license = "MIT"
@@ -13,34 +13,40 @@ 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",
+    "cyclopts>=4.10.2,<5",
     "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'",
+    "msgpack>=1.2.1,<2",
 ]
 
 [project.scripts]
 shelfdb = "shelfdb.cli:main"
 
+[project.urls]
+Documentation = "https://keenlycode.github.io/shelfdb/"
+Repository = "https://github.com/keenlycode/shelfdb"
+
 [dependency-groups]
 dev = [
-    "dictify>=4.0.0,<4.1",
+    "mike>=2.1.3,<3",
     "mkdocs>=1.6.1,<2",
     "mkdocs-shadcn>=0.10.4,<0.11",
     "mkdocstrings[python]>=0.29.0,<0.30",
-    "pytest>=8.4.2,<9",
+    "pytest-cov>=7.0.0,<8",
+    "pymdown-extensions>=11.0.0,<12",
+    "pytest>=9.0.0,<10",
+    "ruff>=0.13.0,<0.14",
+    "tinydb>=4.8.2,<5",
+    "ty>=0.0.1a17,<0.0.2",
 ]
 
 [tool.uv.build-backend]
 module-name = "shelfdb"
 module-root = "src"
+data = { data = "ai-skill" }
+source-include = ["ai-skill/**"]

shelfdb-3.0.1/src/shelfdb/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    main()

shelfdb-3.0.1/src/shelfdb/cli.py

@@ -0,0 +1,109 @@
+"""Command-line interface for ShelfDB."""
+
+from __future__ import annotations
+
+import shutil
+import sysconfig
+from contextlib import suppress
+from pathlib import Path
+
+from cyclopts import App
+
+from shelfdb.protocol import serve, serve_unix
+from shelfdb.shelf import DB
+from shelfdb.target import parse_target, parse_tcp_location, parse_unix_location
+
+app = App("shelfdb")
+DEFAULT_AI_SKILL_INSTALL_PATH = ".agents/skills/shelfdb-usage"
+
+
+def repo_root() -> Path:
+    return Path(__file__).resolve().parents[2]
+
+
+def bundled_ai_skill_path() -> Path:
+    data_root = Path(sysconfig.get_path("data"))
+    installed_path = data_root / "shelfdb-usage"
+    if installed_path.exists():
+        return installed_path
+
+    repo_path = repo_root() / "ai-skill" / "shelfdb-usage"
+    if repo_path.exists():
+        return repo_path
+
+    raise FileNotFoundError("Bundled ShelfDB AI skill not found.")
+
+
+def install_ai_skill(destination: Path, *, force: bool = False) -> Path:
+    source_file = bundled_ai_skill_path() / "SKILL.md"
+    if not source_file.is_file():
+        raise FileNotFoundError("Bundled ShelfDB SKILL.md not found.")
+
+    if destination.exists():
+        if not destination.is_dir():
+            raise NotADirectoryError(
+                f"AI skill destination is not a directory: {destination}"
+            )
+        if not force:
+            raise FileExistsError(
+                f"AI skill destination already exists: {destination}. Use --force to replace SKILL.md."
+            )
+    else:
+        destination.mkdir(parents=True)
+
+    shutil.copy2(source_file, destination / "SKILL.md")
+    return destination
+
+
+def prompt_ai_skill_install_path(
+    default_path: str = DEFAULT_AI_SKILL_INSTALL_PATH,
+) -> Path:
+    response = input(f"Install ShelfDB AI skill to [{default_path}]: ").strip()
+    return Path(response or default_path)
+
+
+async def run_server(
+    *,
+    db_path: str,
+    url: str = "tcp://127.0.0.1:31337",
+) -> None:
+    scheme, location = parse_target(url)
+    socket_path = None
+
+    with DB(db_path) as db:
+        if scheme == "tcp":
+            host, port = parse_tcp_location(location)
+            server = await serve(db, host=host, port=port)
+        else:
+            socket_path = str(Path(parse_unix_location(location)))
+            server = await serve_unix(db, path=socket_path)
+
+        try:
+            await server.serve_forever()
+        finally:
+            server.close()
+            await server.wait_closed()
+            if socket_path is not None:
+                with suppress(FileNotFoundError):
+                    Path(socket_path).unlink()
+
+
+@app.command
+async def server(
+    db_path: str = "db",
+    url: str = "tcp://127.0.0.1:31337",
+) -> None:
+    """Run the ShelfDB protocol server."""
+    await run_server(db_path=db_path, url=url)
+
+
+@app.command(name="ai-skill-install")
+def ai_skill_install(path: str | None = None, force: bool = False) -> None:
+    """Install the bundled ShelfDB AI skill to a local path."""
+    destination = Path(path) if path is not None else prompt_ai_skill_install_path()
+    installed = install_ai_skill(destination, force=force)
+    print(f"Installed ShelfDB AI skill to {installed}")
+
+
+def main(argv: list[str] | None = None) -> None:
+    app(argv, backend="asyncio", result_action="return_none")

shelfdb-3.0.1/src/shelfdb/client/__init__.py

@@ -0,0 +1,3 @@
+from .client import Client, ClientError, ClientTransaction, RemoteShelfQuery
+
+__all__ = ["Client", "ClientError", "ClientTransaction", "RemoteShelfQuery"]