shelfdb 3.0.1__tar.gz → 3.0.2__tar.gz

{shelfdb-3.0.1 → shelfdb-3.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shelfdb
-Version: 3.0.1
+Version: 3.0.2
 Summary: A tiny database for Python
 Author: Nitipit Nontasuwan
 Author-email: Nitipit Nontasuwan <nitipit@gmail.com>
@@ -49,14 +49,28 @@ 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.
+and version tags. Before tagging, authenticated release maintainers also check
+GitHub's repository alerts:
 
-Serve the docs locally:
+```bash
+uv run python -m dev release-check --github
+```
+
+Serve the docs locally (Zensical dev server; live reload is built in):
 
 ```bash
 uv run 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 python -m dev docs build
+```
+
 Publish the docs with mike to the `docs` branch:
 
 ```bash
@@ -101,6 +115,21 @@ 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.
+
 ## Example
 
 ```python

{shelfdb-3.0.1 → shelfdb-3.0.2}/README.md

@@ -30,14 +30,28 @@ 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.
+and version tags. Before tagging, authenticated release maintainers also check
+GitHub's repository alerts:
 
-Serve the docs locally:
+```bash
+uv run python -m dev release-check --github
+```
+
+Serve the docs locally (Zensical dev server; live reload is built in):
 
 ```bash
 uv run 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 python -m dev docs build
+```
+
 Publish the docs with mike to the `docs` branch:
 
 ```bash
@@ -82,6 +96,21 @@ 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.
+
 ## Example
 
 ```python

{shelfdb-3.0.1 → shelfdb-3.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "shelfdb"
-version = "3.0.1"
+version = "3.0.2"
 description = "A tiny database for Python"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -34,12 +34,9 @@ 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",

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

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "shelfdb"
-version = "3.0.1"
+version = "3.0.2"
 description = "A tiny database for Python"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -33,12 +33,9 @@ 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",

{shelfdb-3.0.1 → shelfdb-3.0.2}/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.0.2}/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.0.2/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()