zydecodb 0.9.0b4__tar.gz

zydecodb-0.9.0b4/.gitignore

@@ -0,0 +1,74 @@
+# Node.js
+node_modules/
+dist/
+experiments/**/*.js
+
+# Compiled binaries
+experiments/write_heavy/write_heavy
+clients/go/user_backend
+
+# Rust
+/target
+**/*.rs.bk
+
+# Runtime data (dev)
+*.sock
+/.zydecodb-data/
+/.zydecodb-run/
+
+# Soak run artifacts (baselines in docs/soak-baselines/ are committed)
+/soak-runs/**/data/
+/soak-runs/**/wal/
+/soak-runs/**/*.log
+/soak-runs/**/*.jsonl
+
+# Python
+__pycache__/
+*.py[cod]
+.pytest_cache/
+*.egg-info/
+.venv/
+
+# Fuzzing
+/fuzz/corpus/
+/fuzz/artifacts/
+/fuzz/target/
+
+# Coverage
+/coverage/
+*.profraw
+lcov.info
+
+# Secrets / credentials (never commit)
+.env
+.env.*
+!.env.example
+keys.toml
+**/keys.toml
+!config/zydecodb.keys.example.toml
+*.pem
+*.key
+*.p12
+*.pfx
+tls.crt
+tls.key
+
+# IDE
+/.idea/
+/.vscode/
+*.swp
+.DS_Store
+
+# Empty stub left over from an earlier packaging experiment
+/.github/workflows/publish-python.yml
+
+# Website / Marketing (deployed from this tree via scripts/deploy-website.sh;
+# keep the marketing site and ops scripts local unless explicitly force-added)
+/website/
+/scripts/*
+!/scripts/install.sh
+!/scripts/deploy-website.sh
+
+# Internal / Archived Docs
+/docs/archive/
+/docs/soak-baselines/

zydecodb-0.9.0b4/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: zydecodb
+Version: 0.9.0b4
+Summary: Official Python driver for ZydecoDB.
+Project-URL: Homepage, https://github.com/dataparade/zydecodb
+Project-URL: Source, https://github.com/dataparade/zydecodb
+Author: Dataparade
+License: MIT
+Keywords: database,document-store,nosql,zydecodb
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Database :: Front-Ends
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ZydecoDB Python driver
+
+Official Python client for [ZydecoDB](../../README.md). Pure standard library,
+no runtime dependencies.
+
+## Install
+
+```bash
+pip install zydecodb
+```
+
+Requires Python 3.9+. (Working from a checkout of this repo:
+`pip install -e clients/python`.)
+
+## Quick start
+
+```python
+from zydecodb import Client
+
+# Plain TCP (localhost). For TLS: Client(..., api_key="YOUR_KEY", tls=True)
+with Client("127.0.0.1", 9470, api_key="YOUR_KEY") as db:
+    users = db.collection("users")
+    users.create_index(["email"], unique=True)
+
+    uid = users.insert_one({"email": "ada@example.com", "name": "Ada", "age": 30})
+
+    for u in users.find({"age": {"$gte": 18}}, sort=[("age", True)]):
+        print(u["name"], u["age"])
+
+    users.update_one({"_id": uid}, {"$inc": {"age": 1}})
+    print(users.count_documents())
+```
+
+## What you get
+
+- **Connection pooling.** `Client` owns a thread-safe pool (`pool_size`,
+  default 8) and is safe to share across threads.
+- **Automatic retries with backoff.** Transient transport failures and server
+  `EngineBusy` responses are retried (full-jitter exponential backoff) for
+  operations that are safe to repeat. Operator updates and deletes are never
+  retried automatically.
+- **Keepalive.** Idle pooled connections are validated with a `Ping` on
+  checkout and transparently replaced if dead.
+- **Typed error taxonomy.** Non-OK responses raise a specific subclass:
+  `ConflictError` (unique-index violation), `AuthError`, `ServerBusyError`,
+  `InvalidRequestError`, or the base `ServerError` — each carrying the wire
+  `status` byte. Transport problems raise `ConnectionError`.
+- **`Collection` API.** `insert_one/many`, `find`/`find_one`,
+  `update_one/many`, `delete_one/many`, `count_documents`, `distinct`,
+  `create_index`, with `$`-operators, sort, projection, and skip/limit.
+  Pagination is repeatable-read across pages.
+- **Raw KV with TTL.** Side-channel `put` (with `expires_at`), `get`, and `delete` methods on `Client` for session data that needs a time-to-live.
+- **TLS.** Pass `tls=True` for system CA defaults, or an `ssl.SSLContext` for custom roots / verification.
+
+## Durability
+
+Writes are durable (fsync-on-commit) by default. For latency-sensitive,
+loss-tolerant writes, pass `relaxed=True` to acknowledge before the fsync.
+It is available on every write: `insert_one`, `replace_one`, `update_one`,
+`update_many`, `delete_one`, and `delete_many`.
+
+```python
+users.insert_one(doc, relaxed=True)
+users.update_one({"_id": "ada"}, {"$inc": {"hits": 1}}, relaxed=True)
+users.delete_many({"stale": True}, relaxed=True)
+```
+
+## Running the tests
+
+Unit tests for the wire codecs need no server:
+
+```bash
+cd clients/python
+pip install -e ".[dev]"
+pytest tests/test_protocol.py
+```
+
+Integration tests run against a live server selected by environment variables
+(skipped automatically if it is unreachable):
+
+```bash
+ZYDECODB_TEST_HOST=127.0.0.1 ZYDECODB_TEST_PORT=9470 pytest
+```

zydecodb-0.9.0b4/README.md

@@ -0,0 +1,83 @@
+# ZydecoDB Python driver
+
+Official Python client for [ZydecoDB](../../README.md). Pure standard library,
+no runtime dependencies.
+
+## Install
+
+```bash
+pip install zydecodb
+```
+
+Requires Python 3.9+. (Working from a checkout of this repo:
+`pip install -e clients/python`.)
+
+## Quick start
+
+```python
+from zydecodb import Client
+
+# Plain TCP (localhost). For TLS: Client(..., api_key="YOUR_KEY", tls=True)
+with Client("127.0.0.1", 9470, api_key="YOUR_KEY") as db:
+    users = db.collection("users")
+    users.create_index(["email"], unique=True)
+
+    uid = users.insert_one({"email": "ada@example.com", "name": "Ada", "age": 30})
+
+    for u in users.find({"age": {"$gte": 18}}, sort=[("age", True)]):
+        print(u["name"], u["age"])
+
+    users.update_one({"_id": uid}, {"$inc": {"age": 1}})
+    print(users.count_documents())
+```
+
+## What you get
+
+- **Connection pooling.** `Client` owns a thread-safe pool (`pool_size`,
+  default 8) and is safe to share across threads.
+- **Automatic retries with backoff.** Transient transport failures and server
+  `EngineBusy` responses are retried (full-jitter exponential backoff) for
+  operations that are safe to repeat. Operator updates and deletes are never
+  retried automatically.
+- **Keepalive.** Idle pooled connections are validated with a `Ping` on
+  checkout and transparently replaced if dead.
+- **Typed error taxonomy.** Non-OK responses raise a specific subclass:
+  `ConflictError` (unique-index violation), `AuthError`, `ServerBusyError`,
+  `InvalidRequestError`, or the base `ServerError` — each carrying the wire
+  `status` byte. Transport problems raise `ConnectionError`.
+- **`Collection` API.** `insert_one/many`, `find`/`find_one`,
+  `update_one/many`, `delete_one/many`, `count_documents`, `distinct`,
+  `create_index`, with `$`-operators, sort, projection, and skip/limit.
+  Pagination is repeatable-read across pages.
+- **Raw KV with TTL.** Side-channel `put` (with `expires_at`), `get`, and `delete` methods on `Client` for session data that needs a time-to-live.
+- **TLS.** Pass `tls=True` for system CA defaults, or an `ssl.SSLContext` for custom roots / verification.
+
+## Durability
+
+Writes are durable (fsync-on-commit) by default. For latency-sensitive,
+loss-tolerant writes, pass `relaxed=True` to acknowledge before the fsync.
+It is available on every write: `insert_one`, `replace_one`, `update_one`,
+`update_many`, `delete_one`, and `delete_many`.
+
+```python
+users.insert_one(doc, relaxed=True)
+users.update_one({"_id": "ada"}, {"$inc": {"hits": 1}}, relaxed=True)
+users.delete_many({"stale": True}, relaxed=True)
+```
+
+## Running the tests
+
+Unit tests for the wire codecs need no server:
+
+```bash
+cd clients/python
+pip install -e ".[dev]"
+pytest tests/test_protocol.py
+```
+
+Integration tests run against a live server selected by environment variables
+(skipped automatically if it is unreachable):
+
+```bash
+ZYDECODB_TEST_HOST=127.0.0.1 ZYDECODB_TEST_PORT=9470 pytest
+```

zydecodb-0.9.0b4/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "zydecodb"
+version = "0.9.0b4"
+description = "Official Python driver for ZydecoDB."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Dataparade" }]
+keywords = ["zydecodb", "database", "document-store", "nosql"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Database :: Front-Ends",
+]
+# Pure stdlib: no runtime dependencies.
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://github.com/dataparade/zydecodb"
+Source = "https://github.com/dataparade/zydecodb"
+
+[tool.hatch.build.targets.wheel]
+packages = ["zydecodb"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

zydecodb-0.9.0b4/tests/test_conformance.py

@@ -0,0 +1,136 @@
+"""Conformance: the Python codec must match the shared wire vectors byte-for-byte.
+
+The vectors in `clients/conformance/vectors.json` are generated from the Rust
+server encoders (the protocol authority). Running the Python codec against them
+proves it cannot silently drift from the server. See `clients/conformance/README.md`.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from zydecodb import _protocol as proto
+
+VECTORS_PATH = Path(__file__).resolve().parents[2] / "conformance" / "vectors.json"
+
+
+def _load():
+    with VECTORS_PATH.open(encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+VECTORS = _load()
+
+
+def _json_field(s: str):
+    """An opaque pre-serialized JSON field -> the object Python re-serializes to
+    the same bytes (empty string means "absent")."""
+    return None if s == "" else json.loads(s)
+
+
+def _encode_request(kind: str, inp: dict) -> bytes:
+    if kind == "Put":
+        return proto.encode_put(
+            bytes.fromhex(inp["key_hex"]),
+            bytes.fromhex(inp["value_hex"]),
+            expires_at=inp["expires_at"],
+        )
+    if kind == "Get":
+        return proto.encode_key(bytes.fromhex(inp["key_hex"]))
+    if kind == "Del":
+        return proto.encode_key(bytes.fromhex(inp["key_hex"]))
+    if kind == "DocPut":
+        return proto.encode_doc_put(
+            inp["collection"], inp["doc_id"], _json_field(inp["body_json"]),
+            relaxed=inp["relaxed"],
+        )
+    if kind == "DocDel":
+        return proto.encode_doc_del(inp["collection"], inp["doc_id"])
+    if kind == "IndexDef":
+        return proto.encode_index_def(
+            inp["collection"], inp["index_name"], inp["fields"], unique=inp["unique"]
+        )
+    if kind == "QueryById":
+        return proto.encode_query_by_id(inp["collection"], inp["doc_id"])
+    if kind == "QueryIndexRange":
+        return proto.encode_query_index_range(
+            inp["collection"], inp["index_name"],
+            lo=_json_field(inp["lo_json"]), hi=_json_field(inp["hi_json"]),
+            page_size=inp["limit"], cursor=bytes.fromhex(inp["cursor_hex"]),
+        )
+    if kind == "Find":
+        proj = inp["projection"]
+        mode = {"none": None, "include": proto.PROJ_INCLUDE, "exclude": proto.PROJ_EXCLUDE}[proj["mode"]]
+        projection = None if mode is None else (mode, proj["fields"])
+        return proto.encode_find(
+            inp["collection"], _json_field(inp["filter_json"]),
+            [tuple(s) for s in inp["sort"]], projection,
+            inp["skip"], inp["limit"], bytes.fromhex(inp["cursor_hex"]),
+        )
+    if kind == "Update":
+        return proto.encode_update(
+            inp["collection"], _json_field(inp["filter_json"]),
+            _json_field(inp["update_json"]), multi=inp["multi"], relaxed=inp["relaxed"],
+        )
+    if kind == "Delete":
+        return proto.encode_delete(
+            inp["collection"], _json_field(inp["filter_json"]),
+            multi=inp["multi"], relaxed=inp["relaxed"],
+        )
+    if kind == "Count":
+        return proto.encode_count(inp["collection"], _json_field(inp["filter_json"]))
+    if kind == "Distinct":
+        return proto.encode_distinct(
+            inp["collection"], inp["field"], _json_field(inp["filter_json"])
+        )
+    if kind == "SessionInit":
+        return inp["api_key"].encode("utf-8")
+    if kind == "Ping":
+        return b""
+    raise AssertionError(f"unhandled request kind: {kind}")
+
+
+@pytest.mark.parametrize("vec", VECTORS["requests"], ids=lambda v: v["name"])
+def test_request_payload_matches(vec):
+    payload = _encode_request(vec["kind"], vec["input"])
+    assert payload.hex() == vec["payload_hex"], vec["name"]
+    envelope = proto.encode_header(vec["command"], len(payload)) + payload
+    assert envelope.hex() == vec["envelope_hex"], vec["name"]
+
+
+@pytest.mark.parametrize("vec", VECTORS["responses"], ids=lambda v: v["name"])
+def test_response_decode_matches(vec):
+    assert vec["kind"] == "QueryPage"
+    rows, cursor = proto.decode_page(bytes.fromhex(vec["bytes_hex"]))
+    expected_rows = vec["decoded"]["rows"]
+    assert len(rows) == len(expected_rows), vec["name"]
+    for (doc_id, body), exp in zip(rows, expected_rows):
+        assert doc_id.decode("utf-8") == exp["doc_id"]
+        assert body.decode("utf-8") == exp["body_json"]
+    expected_cursor = vec["decoded"]["next_cursor_hex"]
+    if expected_cursor is None:
+        assert cursor == b""
+    else:
+        assert cursor.hex() == expected_cursor
+
+
+def test_command_codes_match_vectors():
+    cmds = VECTORS["commands"]
+    assert proto.CMD_DOC_PUT == cmds["DocPut"]
+    assert proto.CMD_FIND == cmds["Find"]
+    assert proto.CMD_UPDATE == cmds["Update"]
+    assert proto.CMD_DELETE == cmds["Delete"]
+    assert proto.CMD_COUNT == cmds["Count"]
+    assert proto.CMD_INDEX_DEF == cmds["IndexDef"]
+    assert proto.CMD_SESSION_INIT == cmds["SessionInit"]
+
+
+def test_status_codes_match_vectors():
+    st = VECTORS["statuses"]
+    assert proto.STATUS_OK == st["Ok"]
+    assert proto.STATUS_ENGINE_BUSY == st["EngineBusy"]
+    assert proto.STATUS_UNAUTHORIZED == st["Unauthorized"]
+    assert proto.STATUS_FORBIDDEN == st["Forbidden"]

zydecodb-0.9.0b4/tests/test_live.py

@@ -0,0 +1,95 @@
+"""Integration tests against a live ZydecoDB server.
+
+Set ZYDECODB_TEST_HOST / ZYDECODB_TEST_PORT (and optionally ZYDECODB_TEST_API_KEY)
+to point at a running server. The whole module is skipped when the server is not
+reachable, so a plain `pytest` run stays green offline; CI starts a server first.
+"""
+
+import os
+import socket
+import uuid
+
+import pytest
+
+from zydecodb import Client, ConflictError
+
+HOST = os.environ.get("ZYDECODB_TEST_HOST", "127.0.0.1")
+PORT = int(os.environ.get("ZYDECODB_TEST_PORT", "9470"))
+API_KEY = os.environ.get("ZYDECODB_TEST_API_KEY") or None
+
+
+def _server_up() -> bool:
+    try:
+        with socket.create_connection((HOST, PORT), timeout=1.0):
+            return True
+    except OSError:
+        return False
+
+
+pytestmark = pytest.mark.skipif(
+    not _server_up(), reason=f"no ZydecoDB server at {HOST}:{PORT}"
+)
+
+
+@pytest.fixture()
+def db():
+    client = Client(HOST, PORT, api_key=API_KEY)
+    yield client
+    client.close()
+
+
+@pytest.fixture()
+def coll(db):
+    # A unique collection per test keeps runs isolated.
+    return db.collection(f"pytest_{uuid.uuid4().hex[:12]}")
+
+
+def test_ping(db):
+    db.ping()
+
+
+def test_insert_find_update_delete(coll):
+    coll.create_index(["age"])
+    ids = coll.insert_many(
+        [
+            {"name": "Ada", "age": 30, "city": "London"},
+            {"name": "Bo", "age": 25, "city": "NOLA"},
+            {"name": "Cy", "age": 40, "city": "NOLA"},
+        ]
+    )
+    assert len(ids) == 3
+
+    got = list(coll.find({"age": {"$gte": 30}}, sort=[("age", True)]))
+    assert [d["name"] for d in got] == ["Ada", "Cy"]
+
+    res = coll.update_one({"name": "Bo"}, {"$inc": {"age": 10}})
+    assert res["matched"] == 1 and res["modified"] == 1
+    assert coll.find_one({"name": "Bo"})["age"] == 35
+
+    assert coll.count_documents() == 3
+    assert sorted(coll.distinct("city")) == ["London", "NOLA"]
+
+    assert coll.delete_many({"city": "NOLA"}) == 2
+    assert coll.count_documents() == 1
+
+
+def test_unique_index_conflict(coll):
+    coll.create_index(["email"], unique=True)
+    coll.insert_one({"email": "a@b.com"})
+    with pytest.raises(ConflictError):
+        coll.insert_one({"email": "a@b.com"})
+
+
+def test_pagination_is_stable(coll):
+    coll.create_index(["n"])
+    coll.insert_many([{"n": i} for i in range(25)])
+    seen = [d["n"] for d in coll.find({"n": {"$gte": 0}}, page_size=10)]
+    assert sorted(seen) == list(range(25))
+    assert len(seen) == 25  # no duplicates across pages
+
+
+def test_get_by_id(coll):
+    doc_id = coll.insert_one({"name": "Zee"})
+    fetched = coll.get(doc_id)
+    assert fetched["name"] == "Zee"
+    assert coll.get("does-not-exist") is None

zydecodb-0.9.0b4/tests/test_protocol.py

@@ -0,0 +1,84 @@
+"""Server-independent unit tests for the wire codecs and error taxonomy."""
+
+import struct
+
+import pytest
+
+from zydecodb import (
+    AuthError,
+    ConflictError,
+    InvalidRequestError,
+    ServerBusyError,
+    ServerError,
+)
+from zydecodb import _protocol as proto
+from zydecodb.collection import _encode_projection
+from zydecodb.errors import from_status
+
+
+def _encode_page(rows, cursor=b""):
+    out = struct.pack(">I", len(rows))
+    for doc_id, body in rows:
+        out += struct.pack(">I", len(doc_id)) + doc_id
+        out += struct.pack(">I", len(body)) + body
+    out += struct.pack(">I", len(cursor)) + cursor
+    return out
+
+
+def test_decode_page_roundtrip():
+    rows = [(b"u1", b'{"a":1}'), (b"u2", b"")]
+    buf = _encode_page(rows, cursor=b"NEXT")
+    decoded_rows, cursor = proto.decode_page(buf)
+    assert decoded_rows == rows
+    assert cursor == b"NEXT"
+
+
+def test_decode_empty_page():
+    decoded_rows, cursor = proto.decode_page(_encode_page([]))
+    assert decoded_rows == []
+    assert cursor == b""
+
+
+def test_doc_put_carries_relaxed_flag():
+    durable = proto.encode_doc_put("c", "id", {"x": 1}, relaxed=False)
+    relaxed = proto.encode_doc_put("c", "id", {"x": 1}, relaxed=True)
+    assert durable[-1] == 0
+    assert relaxed[-1] == proto.FLAG_RELAXED
+
+
+def test_update_and_delete_trailing_flags():
+    upd = proto.encode_update("c", {"_id": "x"}, {"$set": {"n": 1}}, multi=True, relaxed=True)
+    # ...multi byte, then relaxed flag byte.
+    assert upd[-2] == 1 and upd[-1] == proto.FLAG_RELAXED
+    dele = proto.encode_delete("c", {"a": 1}, multi=False, relaxed=False)
+    assert dele[-2] == 0 and dele[-1] == 0
+
+
+@pytest.mark.parametrize(
+    "status,exc",
+    [
+        (proto.STATUS_CONFLICT, ConflictError),
+        (proto.STATUS_UNAUTHORIZED, AuthError),
+        (proto.STATUS_FORBIDDEN, AuthError),
+        (proto.STATUS_ENGINE_BUSY, ServerBusyError),
+        (proto.STATUS_PROTOCOL_ERROR, InvalidRequestError),
+        (proto.STATUS_INVALID_KEY, InvalidRequestError),
+        (proto.STATUS_ERROR, ServerError),
+    ],
+)
+def test_status_maps_to_exception(status, exc):
+    err = from_status(status, "Op", b"detail")
+    assert isinstance(err, exc)
+    assert err.status == status
+    assert "Op failed" in str(err)
+
+
+def test_projection_encoding():
+    assert _encode_projection(None) is None
+    assert _encode_projection({"name": 1}) == (proto.PROJ_INCLUDE, ["name"])
+    assert _encode_projection({"secret": 0}) == (proto.PROJ_EXCLUDE, ["secret"])
+
+
+def test_projection_rejects_mixed():
+    with pytest.raises(Exception):
+        _encode_projection({"a": 1, "b": 0})

zydecodb-0.9.0b4/zydecodb/__init__.py

@@ -0,0 +1,43 @@
+"""ZydecoDB Python driver.
+
+Quick start::
+
+    from zydecodb import Client
+
+    with Client("127.0.0.1", 9470, api_key="...") as db:
+        users = db.collection("users")
+        users.create_index(["email"], unique=True)
+        uid = users.insert_one({"email": "a@b.com", "name": "Ada"})
+        for u in users.find({"name": "Ada"}):
+            print(u)
+"""
+
+from .client import Client, generate_id
+from .collection import Collection
+from .errors import (
+    AuthError,
+    ConfigError,
+    ConflictError,
+    ConnectionError,
+    InvalidRequestError,
+    ServerBusyError,
+    ServerError,
+    ZydecoError,
+)
+
+__version__ = "0.9.0b1"
+
+__all__ = [
+    "Client",
+    "Collection",
+    "generate_id",
+    "ZydecoError",
+    "ConfigError",
+    "ConnectionError",
+    "ServerError",
+    "AuthError",
+    "ConflictError",
+    "InvalidRequestError",
+    "ServerBusyError",
+    "__version__",
+]