shelfdb 3.0.1__tar.gz → 3.1.0__tar.gz

shelfdb-3.1.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: shelfdb
+Version: 3.1.0
+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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+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, <3.15
+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
+
+Python 3.12–3.14 is supported. Development uses Python 3.14, selected by
+`.python-version`; compatibility checks cover Python 3.12 and 3.14. Python 3.15
+is temporarily excluded because the released `dill` cannot serialize query
+callbacks on it; support will be reassessed after an upstream fix is released.
+
+Install development dependencies:
+
+```bash
+uv sync --dev
+```
+
+Development tooling lives in `src/dev/`, outside the published `shelfdb` package.
+Use `--directory src` to run its module; workflow commands resolve paths from the
+repository root. Documentation macros live in `src/macros.py`.
+
+Unit tests mirror `src/` under `tests/unit/`: `shelfdb/`, `dev/`, and
+`macros_test.py`. Integration tests cover cross-layer behavior; `tests/usage/`
+contains executable usage examples.
+
+Run the complete non-publishing release gate:
+
+```bash
+uv run --directory src 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:
+
+```bash
+uv run --directory src python -m dev release-check --github
+```
+
+Serve the docs locally (Zensical dev server; live reload is built in):
+
+```bash
+uv run --directory src 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):
+
+```bash
+uv run --directory src python -m dev docs build
+```
+
+Publish the docs with mike to the `docs` branch:
+
+```bash
+uv run --directory src python -m dev docs publish
+```
+
+Override the publish target when needed:
+
+```bash
+uv run --directory src 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")
+```
+
+## 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 `DB` object 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](docs-src/usage/remote.md#concurrent-transactions)
+for coordination limits and details on partial updates and error handling.
+
+## Large results
+
+Remote messages are buffered, not streamed. The former 1 MiB cap is removed;
+only the unsigned 32-bit payload length remains (4 GiB minus 1 byte). Large
+queries can still exhaust memory, so paginate bulk reads with `.slice(...)`.
+Store large assets externally and keep references in ShelfDB.
+
+See [pagination and its limits](docs-src/usage/remote.md#large-results-and-pagination).
+
+## 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.1.0/README.md

@@ -0,0 +1,162 @@
+# 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
+
+Python 3.12–3.14 is supported. Development uses Python 3.14, selected by
+`.python-version`; compatibility checks cover Python 3.12 and 3.14. Python 3.15
+is temporarily excluded because the released `dill` cannot serialize query
+callbacks on it; support will be reassessed after an upstream fix is released.
+
+Install development dependencies:
+
+```bash
+uv sync --dev
+```
+
+Development tooling lives in `src/dev/`, outside the published `shelfdb` package.
+Use `--directory src` to run its module; workflow commands resolve paths from the
+repository root. Documentation macros live in `src/macros.py`.
+
+Unit tests mirror `src/` under `tests/unit/`: `shelfdb/`, `dev/`, and
+`macros_test.py`. Integration tests cover cross-layer behavior; `tests/usage/`
+contains executable usage examples.
+
+Run the complete non-publishing release gate:
+
+```bash
+uv run --directory src 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:
+
+```bash
+uv run --directory src python -m dev release-check --github
+```
+
+Serve the docs locally (Zensical dev server; live reload is built in):
+
+```bash
+uv run --directory src 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):
+
+```bash
+uv run --directory src python -m dev docs build
+```
+
+Publish the docs with mike to the `docs` branch:
+
+```bash
+uv run --directory src python -m dev docs publish
+```
+
+Override the publish target when needed:
+
+```bash
+uv run --directory src 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")
+```
+
+## 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 `DB` object 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](docs-src/usage/remote.md#concurrent-transactions)
+for coordination limits and details on partial updates and error handling.
+
+## Large results
+
+Remote messages are buffered, not streamed. The former 1 MiB cap is removed;
+only the unsigned 32-bit payload length remains (4 GiB minus 1 byte). Large
+queries can still exhaust memory, so paginate bulk reads with `.slice(...)`.
+Store large assets externally and keep references in ShelfDB.
+
+See [pagination and its limits](docs-src/usage/remote.md#large-results-and-pagination).
+
+## 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 → shelfdb-3.1.0}/pyproject.toml

@@ -4,14 +4,16 @@ build-backend = "uv_build"
 
 [project]
 name = "shelfdb"
-version = "3.0.1"
+version = "3.1.0"
 description = "A tiny database for Python"
 readme = "README.md"
-requires-python = ">=3.12"
+requires-python = ">=3.12,<3.15"
 license = "MIT"
 license-files = ["LICENSE"]
 classifiers = [
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Operating System :: OS Independent",
 ]
 dependencies = [
@@ -34,22 +36,19 @@ 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",
+    "zensical==0.0.52",
+    "mike @ git+https://github.com/squidfunk/mike.git@2d4ad799442f4592db8ad53b179bfb33db8c69ac",
     "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.pytest.ini_options]
+addopts = ["--import-mode=importlib"]
+pythonpath = ["src"]
+
 [tool.uv.build-backend]
 module-name = "shelfdb"
 module-root = "src"
-source-include = ["ai-skill/**"]
-
-[tool.uv.build-backend.data]
-data = "ai-skill"

{shelfdb-3.0.1 → shelfdb-3.1.0}/pyproject.toml.orig

@@ -4,10 +4,10 @@ build-backend = "uv_build"
 
 [project]
 name = "shelfdb"
-version = "3.0.1"
+version = "3.1.0"
 description = "A tiny database for Python"
 readme = "README.md"
-requires-python = ">=3.12"
+requires-python = ">=3.12,<3.15"
 license = "MIT"
 license-files = ["LICENSE"]
 authors = [
@@ -15,6 +15,8 @@ authors = [
 ]
 classifiers = [
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Operating System :: OS Independent",
 ]
 dependencies = [
@@ -33,20 +35,19 @@ 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",
+    "zensical==0.0.52",
+    "mike @ git+https://github.com/squidfunk/mike.git@2d4ad799442f4592db8ad53b179bfb33db8c69ac",
     "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.pytest.ini_options]
+addopts = ["--import-mode=importlib"]
+pythonpath = ["src"]
+
 [tool.uv.build-backend]
 module-name = "shelfdb"
 module-root = "src"
-data = { data = "ai-skill" }
-source-include = ["ai-skill/**"]

shelfdb-3.1.0/src/shelfdb/cli.py

@@ -0,0 +1,53 @@
+"""Command-line interface for ShelfDB."""
+
+from __future__ import annotations
+
+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")
+
+
+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)
+
+
+def main(argv: list[str] | None = None) -> None:
+    app(argv, backend="asyncio", result_action="return_none")

{shelfdb-3.0.1 → shelfdb-3.1.0}/src/shelfdb/client/client.py

@@ -6,7 +6,7 @@ from asyncio import StreamReader, StreamWriter, open_connection, open_unix_conne
 from contextlib import suppress
 from typing import Any
 
-from shelfdb.protocol import read_response, write_request
+from shelfdb.protocol.protocol import read_response, write_request
 from shelfdb.protocol.query_result import denormalize_query_result
 from shelfdb.shelf import Item
 from shelfdb.target import parse_target, parse_tcp_location, parse_unix_location

shelfdb-3.1.0/src/shelfdb/protocol/__init__.py

@@ -0,0 +1,59 @@
+"""Wire helpers, with backward-compatible lazy server-side exports."""
+
+from importlib import import_module
+from typing import TYPE_CHECKING
+
+from .protocol import (
+    MAX_FRAME_SIZE,
+    decode_request,
+    decode_response,
+    encode_request,
+    encode_response,
+    frame_payload,
+    read_payload,
+    read_request,
+    read_response,
+    write_payload,
+    write_request,
+    write_response,
+)
+
+if TYPE_CHECKING:
+    from .server import handle_client, serve, serve_unix
+    from .session import Session
+
+
+def __getattr__(name: str):
+    if name in {"handle_client", "serve", "serve_unix"}:
+        module = import_module(".server", __name__)
+    elif name == "Session":
+        module = import_module(".session", __name__)
+    else:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    value = getattr(module, name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(__all__))
+
+
+__all__ = [
+    "MAX_FRAME_SIZE",
+    "decode_request",
+    "decode_response",
+    "encode_request",
+    "encode_response",
+    "frame_payload",
+    "handle_client",
+    "read_payload",
+    "read_request",
+    "read_response",
+    "Session",
+    "serve",
+    "serve_unix",
+    "write_payload",
+    "write_request",
+    "write_response",
+]

{shelfdb-3.0.1 → shelfdb-3.1.0}/src/shelfdb/protocol/protocol.py

@@ -10,7 +10,8 @@ import dill
 import msgpack
 
 _FRAME_HEADER: Final = struct.Struct(">I")
-MAX_FRAME_SIZE: Final = 1024 * 1024
+# The unsigned 32-bit length header is the only frame-size limit.
+MAX_FRAME_SIZE: Final = (1 << 32) - 1
 
 
 class WritableStream(Protocol):
@@ -20,9 +21,9 @@ class WritableStream(Protocol):
 
 
 def frame_payload(payload: bytes) -> bytes:
-    """Prefix payload bytes with a 4-byte big-endian length."""
+    """Prefix a buffered payload with its unsigned 32-bit big-endian length."""
     if len(payload) > MAX_FRAME_SIZE:
-        raise ValueError("payload exceeds max frame size")
+        raise ValueError("payload exceeds 32-bit frame length (4294967295 bytes)")
     return _FRAME_HEADER.pack(len(payload)) + payload
 
 
@@ -50,8 +51,6 @@ async def read_payload(reader: StreamReader) -> bytes:
     """Read one length-prefixed payload from a stream."""
     size_data = await reader.readexactly(_FRAME_HEADER.size)
     (size,) = _FRAME_HEADER.unpack(size_data)
-    if size > MAX_FRAME_SIZE:
-        raise ValueError("frame exceeds max frame size")
     return await reader.readexactly(size)
 
 

{shelfdb-3.0.1 → shelfdb-3.1.0}/src/shelfdb/protocol/server.py

@@ -12,16 +12,39 @@ from shelfdb.shelf import DB
 
 from .protocol import read_request, write_response
 from .session import Session
+from .write_admission import WriteLease
+
+
+class _ConnectionReader(asyncio.StreamReader):
+    """Observe transport EOF/errors without a second consumer of request bytes."""
+
+    def __init__(self):
+        super().__init__()
+        self.disconnected = asyncio.Event()
+
+    def feed_eof(self) -> None:
+        self.disconnected.set()
+        super().feed_eof()
+
+    def set_exception(self, exc) -> None:
+        self.disconnected.set()
+        super().set_exception(exc)
+
+
+def _protocol_factory(db: DB) -> asyncio.StreamReaderProtocol:
+    reader = _ConnectionReader()
+    return asyncio.StreamReaderProtocol(reader, partial(handle_client, db=db))
 
 
 async def handle_client(
-    reader: asyncio.StreamReader,
+    reader: _ConnectionReader,
     writer: asyncio.StreamWriter,
     *,
     db: DB,
 ) -> None:
     """Serve one client connection with one session."""
     session = Session(db)
+    lease = WriteLease(db)
 
     try:
         while True:
@@ -34,19 +57,35 @@ async def handle_client(
                 break
 
             try:
+                if (
+                    isinstance(command, dict)
+                    and command.get("cmd") == "begin"
+                    and command.get("mode") == "write"
+                    and not session.active
+                ):
+                    if not await lease.acquire(reader.disconnected):
+                        break
                 response = session.handle(command)
             except Exception as exc:
                 response = {"ok": False, "error": str(exc)}
+            finally:
+                # A failed begin and any terminal transaction path give up admission.
+                # Query errors intentionally leave an active transaction usable.
+                if not session.active:
+                    lease.release()
 
             try:
                 await write_response(writer, response)
             except Exception:
                 break
     finally:
-        session.close()
-        writer.close()
-        with suppress(Exception):
-            await writer.wait_closed()
+        try:
+            session.close()
+        finally:
+            lease.release()
+            writer.close()
+            with suppress(Exception):
+                await writer.wait_closed()
 
 
 async def serve(
@@ -56,7 +95,9 @@ async def serve(
     port: int = 0,
 ) -> asyncio.Server:
     """Start the minimal ShelfDB protocol server."""
-    return await asyncio.start_server(partial(handle_client, db=db), host, port)
+    return await asyncio.get_running_loop().create_server(
+        partial(_protocol_factory, db), host, port
+    )
 
 
 class _UnixServer:
@@ -101,7 +142,9 @@ async def serve_unix(
     socket_path = Path(path)
     with suppress(FileNotFoundError):
         socket_path.unlink()
-    server = await asyncio.start_unix_server(partial(handle_client, db=db), socket_path)
+    server = await asyncio.get_running_loop().create_unix_server(
+        partial(_protocol_factory, db), socket_path
+    )
     return _UnixServer(server, socket_path)
 
 

{shelfdb-3.0.1 → shelfdb-3.1.0}/src/shelfdb/protocol/session.py

@@ -94,8 +94,10 @@ class Session:
     def close(self) -> None:
         tx = self._tx
         if tx is not None:
-            tx.tx.abort()
-            self._clear_transaction()
+            try:
+                tx.tx.abort()
+            finally:
+                self._clear_transaction()
 
     def _begin(self, mode: str | None) -> dict[str, Any]:
         if mode not in {"read", "write"}:
@@ -115,16 +117,25 @@ class Session:
 
     def _commit(self) -> dict[str, Any]:
         tx = self._require_tx()
-        if tx.is_write:
-            tx.commit()
-        else:
-            tx.tx.abort()
-        self._clear_transaction()
+        try:
+            if tx.is_write:
+                tx.commit()
+            else:
+                tx.tx.abort()
+        except Exception:
+            # LMDB may already have consumed the handle on commit failure.
+            # Best-effort abort also covers failures before commit reached LMDB.
+            try:
+                tx.tx.abort()
+            except Exception:
+                pass
+            raise
+        finally:
+            self._clear_transaction()
         return _ok({"committed": True})
 
     def _rollback(self) -> dict[str, Any]:
-        self._require_tx().tx.abort()
-        self._clear_transaction()
+        self.close()
         return _ok({"rolled_back": True})
 
     def _query(

shelfdb-3.1.0/src/shelfdb/protocol/write_admission.py

@@ -0,0 +1,49 @@
+"""Event-loop-local writer admission, shared by listeners serving one DB.
+
+This coordinates only server-side writers. It does not make synchronous LMDB
+operations or independent local writers nonblocking.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from weakref import WeakKeyDictionary
+
+from shelfdb.shelf import DB
+
+_GATES: WeakKeyDictionary[DB, asyncio.Lock] = WeakKeyDictionary()
+
+
+class WriteLease:
+    """One connection's ownership of a DB's writer gate (not the transaction)."""
+
+    def __init__(self, db: DB):
+        self._gate = _GATES.setdefault(db, asyncio.Lock())
+        self.held = False
+
+    async def acquire(self, disconnected: asyncio.Event) -> bool:
+        """Wait without reading the stream; EOF/cancellation cannot leak a grant."""
+        waiting = asyncio.create_task(self._gate.acquire())
+        closed = asyncio.create_task(disconnected.wait())
+        try:
+            await asyncio.wait((waiting, closed), return_when=asyncio.FIRST_COMPLETED)
+            if disconnected.is_set():
+                return False
+            waiting.result()
+            self.held = True
+            return True
+        finally:
+            # No await between checking a grant and returning an abandoned one.
+            # A pending Lock.acquire handles its own cancellation safely.
+            if not self.held and waiting.done() and not waiting.cancelled():
+                if waiting.exception() is None and waiting.result():
+                    self._gate.release()
+            waiting.cancel()
+            closed.cancel()
+            await asyncio.gather(waiting, closed, return_exceptions=True)
+
+    def release(self) -> None:
+        """Release only this connection's grant, at most once."""
+        if self.held:
+            self.held = False
+            self._gate.release()

{shelfdb-3.0.1 → shelfdb-3.1.0}/src/shelfdb/shelf/__init__.py

@@ -1,4 +1,5 @@
 from .db import DB
-from .shelf import UNDEF, Item, MutationResult, ShelfQuery
+from .query import ShelfQuery
+from .schema import UNDEF, Item, MutationResult
 
 __all__ = ["DB", "UNDEF", "Item", "MutationResult", "ShelfQuery"]

{shelfdb-3.0.1 → shelfdb-3.1.0}/src/shelfdb/shelf/db.py

@@ -9,8 +9,8 @@ from typing import Any
 import lmdb
 
 # lib: local
-from .shelf.query import ShelfQuery
-from .shelf.shelf import ShelfCursor, ShelfStore
+from .query import ShelfQuery
+from .storage import ShelfCursor, ShelfStore
 
 LmdbEnvironment = Any
 LmdbTransaction = Any

{shelfdb-3.0.1/src/shelfdb/shelf → shelfdb-3.1.0/src/shelfdb}/shelf/query.py

@@ -20,7 +20,7 @@ from itertools import islice
 from typing import Any
 
 from .schema import UNDEF, Item, MutationResult
-from .shelf import ShelfCursor, ShelfStore
+from .storage import ShelfCursor, ShelfStore
 
 type Transform = Callable[[Iterator[Item]], Iterator[Item]]
 

shelfdb-3.0.1/PKG-INFO

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

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

@@ -1,56 +0,0 @@
----
-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/src/shelfdb/cli.py

@@ -1,109 +0,0 @@
-"""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/protocol/__init__.py

@@ -1,35 +0,0 @@
-from .protocol import (
-    MAX_FRAME_SIZE,
-    decode_request,
-    decode_response,
-    encode_request,
-    encode_response,
-    frame_payload,
-    read_payload,
-    read_request,
-    read_response,
-    write_payload,
-    write_request,
-    write_response,
-)
-from .server import handle_client, serve, serve_unix
-from .session import Session
-
-__all__ = [
-    "MAX_FRAME_SIZE",
-    "decode_request",
-    "decode_response",
-    "encode_request",
-    "encode_response",
-    "frame_payload",
-    "handle_client",
-    "read_payload",
-    "read_request",
-    "read_response",
-    "Session",
-    "serve",
-    "serve_unix",
-    "write_payload",
-    "write_request",
-    "write_response",
-]

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

@@ -1,4 +0,0 @@
-from .query import ShelfQuery
-from .schema import UNDEF, Item, MutationResult
-
-__all__ = ["UNDEF", "Item", "MutationResult", "ShelfQuery"]