shelfdb 2.0.0__tar.gz → 2.0.0.dev0__tar.gz

{shelfdb-2.0.0 → shelfdb-2.0.0.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shelfdb
-Version: 2.0.0
+Version: 2.0.0.dev0
 Summary: A tiny documents database for Python
 Keywords: dict,json,database
 Author: Nitipit Nontasuwan

{shelfdb-2.0.0 → shelfdb-2.0.0.dev0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "shelfdb"
-version = "2.0.0"
+version = "2.0.0.dev0"
 description = "A tiny documents database for Python"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -38,7 +38,7 @@ dev = [
     "mkdocs>=1.6.1,<2",
     "mkdocs-shadcn>=0.10.4,<0.11",
     "mkdocstrings[python]>=0.29.0,<0.30",
-    "pytest>=8.4.2,<10",
+    "pytest>=8.4.2,<9",
 ]
 
 [tool.uv.build-backend]

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 → shelfdb-2.0.0.dev0}/src/shelfdb/ai_skill/shelfdb-usage/references/docs/embedded-mode.md

@@ -149,8 +149,7 @@ db.close()
 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 and update `tx.result`. Remote
-client transactions queue their steps until `tx.commit()` or a clean `with` / `async with` exit
-stores the commit result on `tx.result`.
+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.

{shelfdb-2.0.0 → shelfdb-2.0.0.dev0}/src/shelfdb/ai_skill/shelfdb-usage/references/docs/server-mode.md

@@ -147,21 +147,18 @@ Remote transaction queries queue their steps when you call `.run()`, unlike embe
 where `.run()` executes immediately inside the `with` block.
 
 !!! info "Information:"
-    Call `tx.commit()` to send the batch, or use `with client.transaction(...) as tx:` / `async with`
-    to auto-commit and store the commit result on `tx.result`.
+    Call `tx.commit()` to send the batch.
 
 ```python
-with client.transaction(write=True) as tx:
-    tx.shelf("note").put("note-1", {"title": "ShelfDB"}).run()
-    tx.shelf("user").put("user-1", {"name": "alice"}).run()
-
-print(tx.result)
+tx = client.transaction(write=True)
+tx.shelf("note").put("note-1", {"title": "ShelfDB"}).run()
+tx.shelf("user").put("user-1", {"name": "alice"}).run()
+tx.commit()
 ```
 
-`tx.commit()` returns the last queued query result, or `None` for an empty transaction, and stores
-that value on `tx.result`.
+`tx.commit()` returns the last queued query result, or `None` for an empty transaction.
 
-For async code, use `async with` or `await tx.commit()` instead.
+For async code, use `await tx.commit()` instead.
 
 Transaction queries must belong to the transaction they are queued into.
 

{shelfdb-2.0.0 → shelfdb-2.0.0.dev0}/src/shelfdb/ai_skill/shelfdb-usage/references/docs/transactions.md

@@ -5,8 +5,8 @@ ShelfDB supports database transactions for two main purposes:
 - **consistent reads** with a stable snapshot
 - **atomic writes** that either all commit or all roll back
 
-Embedded transactions execute each query when you call `.run()` inside the `with` block and keep the latest result on `tx.result`.
-Client transactions queue each query on `.run()` and store the commit result on `tx.result` when you call `tx.commit()` or use `with` / `async with`.
+Embedded transactions execute each query when you call `.run()` inside the `with` block.
+Client transactions queue each query on `.run()` and execute the batch later with `tx.commit()`.
 
 ## Read transactions
 
@@ -56,7 +56,6 @@ except RuntimeError:
 ```
 
 After that error, the update is not committed.
-`tx.result` still reflects the last successful query result from inside the aborted block.
 
 ## Read your own writes
 
@@ -114,15 +113,8 @@ tx.shelf("note").put("note-1", {"title": "hello"}).run()
 tx.commit()
 ```
 
-`tx.commit()` returns the last queued query result, or `None` for an empty transaction, and stores that value on `tx.result`.
+`tx.commit()` returns the last queued query result, or `None` for an empty transaction.
 
-You can also write:
-
-```python
-with client.transaction(write=True) as tx:
-    tx.shelf("note").put("note-1", {"title": "hello"}).run()
-```
-
-For async code, use `async with` or `await tx.commit()` instead.
+For async code, use `await tx.commit()` instead.
 
 See [Server Mode](server-mode.md) for connection setup and the shared remote query model.

{shelfdb-2.0.0 → shelfdb-2.0.0.dev0}/src/shelfdb/client/_impl.py

@@ -174,7 +174,6 @@ class AsyncClientTransaction:
         self._write = write
         self._txs: list[TransactionShelfRequest] = []
         self._ran = False
-        self.result = None
 
     def _enqueue(self, query: AsyncTransactionQuery):
         if self._ran:
@@ -195,23 +194,13 @@ class AsyncClientTransaction:
 
         return AsyncTransactionQuery(self, require_shelf_name(shelf_name))
 
-    async def __aenter__(self):
-        return self
-
-    async def __aexit__(self, exc_type, exc, tb):
-        if exc_type is None and not self._ran:
-            await self.commit()
-        return False
-
     async def commit(self):
         if self._ran:
             raise RuntimeError("Transaction already ran.")
 
         self._ran = True
         payload = make_transaction_request(self._write, self._txs)
-        result = await self._client._request(payload)
-        self.result = result
-        return result
+        return await self._client._request(payload)
 
     async def run(self):
         return await self.commit()
@@ -320,7 +309,6 @@ class SyncClientTransaction:
         self._write = write
         self._txs: list[TransactionShelfRequest] = []
         self._ran = False
-        self.result = None
 
     def _enqueue(self, query: SyncTransactionQuery):
         if self._ran:
@@ -341,23 +329,13 @@ class SyncClientTransaction:
 
         return SyncTransactionQuery(self, require_shelf_name(shelf_name))
 
-    def __enter__(self):
-        return self
-
-    def __exit__(self, exc_type, exc, tb):
-        if exc_type is None and not self._ran:
-            self.commit()
-        return False
-
     def commit(self):
         if self._ran:
             raise RuntimeError("Transaction already ran.")
 
         self._ran = True
         payload = make_transaction_request(self._write, self._txs)
-        result = self._client._request(payload)
-        self.result = result
-        return result
+        return self._client._request(payload)
 
     def run(self):
         return self.commit()

{shelfdb-2.0.0 → shelfdb-2.0.0.dev0}/src/shelfdb/server/rpc.py

@@ -11,14 +11,15 @@ def run_query_request(db, shelf, queries):
 
 def run_transaction_request(db, write, txs):
     """Execute one transaction request and return its last result."""
+    last_result = None
     with db.transaction(write=write) as tx:
         for tx_payload in txs:
             match tx_payload:
                 case {"shelf": shelf, "queries": queries}:
-                    replay_queries(tx.shelf(shelf), queries).run()
+                    last_result = replay_queries(tx.shelf(shelf), queries).run()
                 case _:
                     raise ValueError("Transaction payload item is invalid.")
-    return tx.result
+    return last_result
 
 
 def run_request(db, payload):

{shelfdb-2.0.0 → shelfdb-2.0.0.dev0}/src/shelfdb/shelf/core.py

@@ -34,7 +34,6 @@ class Transaction:
         self._db = db
         self.txn = txn
         self.write = write
-        self.result = None
 
     def shelf(self, shelf_name: str) -> "ShelfQuery":
         """Create one query builder bound to this active transaction."""
@@ -322,12 +321,7 @@ class ShelfQuery(QueryBuilderMixin):
             with self._db.transaction(write=True):
                 return self._run_queries()
 
-        result = self._run_queries()
-        if self._tx_context is not None:
-            if isinstance(result, Iterator):
-                result = list(result)
-            self._tx_context.result = result
-        return result
+        return self._run_queries()
 
     def _has_write_step(self) -> bool:
         return any(query.get("write") is True for query in self.queries)

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

@@ -1,115 +0,0 @@
----
-name: shelfdb-usage
-description: "ShelfDB developer workflow for embedded and server-mode usage, including local transactions, client queries, logging, and examples that call `shelfdb.open`, `connect`, `connect_async`, `.run()`, or `tx.commit()`."
----
-
-# ShelfDB usage
-
-Prefer embedded mode first; use server mode only when you need a separate process or multiple trusted local clients.
-
-## Reference docs
-
-- Read `references/docs/` for mirrored ShelfDB documentation when you need the full narrative docs.
-- Prefer the most specific page for the task: `embedded-mode.md`, `server-mode.md`, `transactions.md`, `query-model.md`, and `security.md` are the usual first reads.
-
-## Choose the mode
-
-- Use `shelfdb.open(path)` when the Python process can access the LMDB directory directly.
-- Use server mode when you need a process boundary, a remote client, or shared access from several trusted local processes.
-- Keep server mode on loopback or a Unix socket. Treat the RPC layer as trusted-local only.
-
-## 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.
-- Use `shelfdb --db ./data/app-db` to choose a different database path.
-- Use `shelfdb --log-level debug` when you need server-side diagnostics.
-
-## Connect from Python
-
-- Use `shelfdb.connect(url)` in sync code.
-- Use `await shelfdb.connect_async(url)` in async code.
-- Await only `connect_async(...)`, remote query `.run()` calls, and `tx.commit()`.
-- Embedded transactions are sync `with db.transaction(...)` blocks, and their `.run()` calls execute immediately inside the block.
-- Remote transaction queries like `tx.shelf(...).run()` only queue work and return `None`; remote transactions also support `with` / `async with`, and `tx.commit()` returns the last queued result and stores it on `tx.result`.
-
-## 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`
-
-Selection rules:
-
-- Call `keys_in()` on the base shelf before chaining other selection steps.
-- `replace()`, `update()`, and `edit()` require an existing selection.
-- `delete()` is the mutator that is safe on a missing key.
-
-## 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`.
-- In transactions, `tx.result` stores the latest result; for remote transactions, `tx.commit()` returns the last queued result or `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 `db.transaction()` when you need a consistent snapshot.
-- Use `db.transaction(write=True)` when you need several local queries to commit together.
-- Single embedded write queries are already atomic by default. Inside a local transaction, use `tx.shelf(...)`, not `db.shelf(...)`.
-- Use `client.transaction(write=True)` for remote batches; queue queries with `.run()` and send them with `tx.commit()` or `await tx.commit()`.
-- Local transaction blocks commit on success and roll back on error.
-- Nested local transactions are not supported.
-
-## 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
-
-db = shelfdb.open("db")
-note = db.shelf("note").key("note-1").first().run()
-```
-
-```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
-import shelfdb
-
-client = shelfdb.connect("tcp://127.0.0.1:17000")
-tx = client.transaction(write=True)
-tx.shelf("note").put("note-1", {"title": "ShelfDB"}).run()
-tx.commit()
-```