shelfdb 3.0.2__tar.gz → 3.1.0__tar.gz

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

@@ -1,18 +1,20 @@
 Metadata-Version: 2.4
 Name: shelfdb
-Version: 3.0.2
+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
+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
@@ -34,16 +36,29 @@ pip install shelfdb
 
 ## 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 python -m dev release-check
+uv run --directory src python -m dev release-check
 ```
 
 The gate audits locked dependencies, checks formatting, linting, types, supported
@@ -53,13 +68,13 @@ and version tags. Before tagging, authenticated release maintainers also check
 GitHub's repository alerts:
 
 ```bash
-uv run python -m dev release-check --github
+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 python -m dev docs serve --port 9001 --livereload
+uv run --directory src python -m dev docs serve --port 9001 --livereload
 ```
 
 `--livereload` is a legacy compatibility flag and is intentionally ignored by Zensical
@@ -68,19 +83,19 @@ uv run python -m dev docs serve --port 9001 --livereload
 Build docs for verification (Zensical build):
 
 ```bash
-uv run python -m dev docs build
+uv run --directory src python -m dev docs build
 ```
 
 Publish the docs with mike to the `docs` branch:
 
 ```bash
-uv run python -m dev docs publish
+uv run --directory src 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
+uv run --directory src python -m dev docs publish --publish-version 3.0.1 --alias latest --branch docs --remote origin
 ```
 
 ## Server
@@ -130,6 +145,15 @@ client = await Client.connect("unix:///tmp/shelfdb.sock")
 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

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

@@ -15,16 +15,29 @@ pip install shelfdb
 
 ## 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 python -m dev release-check
+uv run --directory src python -m dev release-check
 ```
 
 The gate audits locked dependencies, checks formatting, linting, types, supported
@@ -34,13 +47,13 @@ and version tags. Before tagging, authenticated release maintainers also check
 GitHub's repository alerts:
 
 ```bash
-uv run python -m dev release-check --github
+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 python -m dev docs serve --port 9001 --livereload
+uv run --directory src python -m dev docs serve --port 9001 --livereload
 ```
 
 `--livereload` is a legacy compatibility flag and is intentionally ignored by Zensical
@@ -49,19 +62,19 @@ uv run python -m dev docs serve --port 9001 --livereload
 Build docs for verification (Zensical build):
 
 ```bash
-uv run python -m dev docs build
+uv run --directory src python -m dev docs build
 ```
 
 Publish the docs with mike to the `docs` branch:
 
 ```bash
-uv run python -m dev docs publish
+uv run --directory src 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
+uv run --directory src python -m dev docs publish --publish-version 3.0.1 --alias latest --branch docs --remote origin
 ```
 
 ## Server
@@ -111,6 +124,15 @@ client = await Client.connect("unix:///tmp/shelfdb.sock")
 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

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

@@ -4,14 +4,16 @@ build-backend = "uv_build"
 
 [project]
 name = "shelfdb"
-version = "3.0.2"
+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 = [
@@ -43,10 +45,10 @@ dev = [
     "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.2 → shelfdb-3.1.0}/pyproject.toml.orig

@@ -4,10 +4,10 @@ build-backend = "uv_build"
 
 [project]
 name = "shelfdb"
-version = "3.0.2"
+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 = [
@@ -42,8 +44,10 @@ dev = [
     "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.2 → 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.2 → 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.2 → 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.2 → 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.2/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.2/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.2/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.2/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.2/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"]