prismdb 0.1.0__tar.gz

prismdb-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: prismdb
+Version: 0.1.0
+Summary: Pure-Python client for PrismDB over the binary wire protocol (no native build).
+Author: The Prism authors
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/HafizMMoaz/prism-db/tree/main/sdks/python#readme
+Project-URL: Repository, https://github.com/HafizMMoaz/prism-db
+Project-URL: Issues, https://github.com/HafizMMoaz/prism-db/issues
+Keywords: prismdb,prism,database,client,driver,sql,document,key-value,multi-model
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Database :: Front-Ends
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# prismdb (Python)
+
+A **pure-Python** client for [PrismDB](https://github.com/HafizMMoaz/prism-db), speaking the binary
+wire protocol directly over a TCP (or TLS) socket. No native extension, no build
+toolchain — it runs anywhere CPython does.
+
+> Implements `docs/specs/wire-protocol.md`. The byte layouts are kept in lockstep
+> with the Rust `prism-protocol` crate and the reference Node SDK.
+
+## Install
+
+```bash
+pip install prismdb
+```
+
+Requires Python ≥ 3.8. No dependencies.
+
+## Quick start
+
+```python
+from prismdb import Client, Q, U
+
+db = Client.connect(host="127.0.0.1", port=4444, username="admin", password="admin")
+with db:
+    # SQL
+    db.sql("CREATE TABLE users (id BIGINT PRIMARY KEY, name TEXT, age BIGINT)")
+    db.sql("INSERT INTO users VALUES (1,'alice',30),(2,'bob',25)")
+    res = db.sql("SELECT name, age FROM users WHERE age >= 30 ORDER BY age")
+    print(res.rows)  # [{'name': 'alice', 'age': 30}]
+
+    # Key/value
+    db.kv.put("sessions", "sid-1", "payload")
+    v = db.kv.get("sessions", "sid-1")          # bytes | None
+
+    # Documents, with query operators
+    db.doc.insert_one("people", {"name": "carol", "age": 41, "city": "NYC"})
+    adults = db.doc.find("people", Q.and_(Q.eq("city", "NYC"), Q.gt("age", 30)))
+
+    # A transaction is atomic across all three models
+    db.begin()
+    db.sql("INSERT INTO users VALUES (3,'dave',50)")
+    db.kv.put("sessions", "sid-2", "tx")
+    db.commit()                                  # or db.abort()
+```
+
+`Client` is a context manager; leaving the `with` block closes the connection.
+
+## API
+
+### `Client.connect(host="127.0.0.1", port=4444, *, username=None, password=None, database=None, tls=None, ...)`
+
+Performs the `Hello`/`Auth` handshake. Omit `username` to skip authentication
+(only useful against a server that doesn't require it). Pass `tls=True` (or an
+`ssl.SSLContext`) for TLS. On a multi-database server, pass `database=` to select
+it at connect; otherwise run `db.sql("USE <name>")` yourself.
+
+### SQL — `db.sql(text, params=None, *, return_rows=True)`
+
+Returns a `SqlResult` with `.columns`, `.rows` (list of dicts keyed by column
+name), `.raw` (cells in column order), and `.affected_rows` (int).
+
+### KV — `db.kv`
+
+`get(ns, key) -> bytes | None`, `put(ns, key, value)`, `delete(ns, key)`. Keys
+and values are `str` (UTF-8) or `bytes`.
+
+### Documents — `db.doc`
+
+`insert_one` / `insert_many` (return the assigned `ObjectId`s), `find` / `find_one`,
+`count`, `update_one` / `update_many`, `delete_one` / `delete_many`. Build filters
+with `Q` and updates with `U`:
+
+```python
+Q.all()
+Q.eq("f", v); Q.ne; Q.gt; Q.lt; Q.gte; Q.lte
+Q.in_("f", [a, b]); Q.nin("f", [a, b])
+Q.exists("f", True)
+Q.and_(a, b); Q.or_(a, b); Q.not_(a)
+
+db.doc.update_one("people", Q.eq("name", "carol"), [
+    U.set("city", "Boston"),
+    U.inc("age", 1),
+    U.unset("temp"),
+])
+```
+
+### Transactions — `db.begin(mode="read_write")`, `db.commit(idempotency_key=0)`, `db.abort()`
+
+One `Client` is one server session, so calls between `begin()` and `commit()`
+run in that transaction. `commit(idempotency_key=...)` makes a retried commit safe.
+
+### Value mapping
+
+Python → wire: `None`→Null, `bool`→Bool, `int`→Int64, `float`→Double,
+`str`→Str, `bytes`→Binary, `datetime`→Timestamp, `ObjectId`→ObjectId. Use
+`int32(n)`, `float64(n)`, `timestamp(us)` to force a type. On decode, Int64 and
+Timestamp come back as `int`.
+
+## Develop
+
+```bash
+python -m unittest discover -s tests   # unit tests (no server needed)
+
+# end-to-end against a running server:
+prismd run ./data 127.0.0.1:4444
+PRISM_HOST=127.0.0.1 PRISM_PORT=4444 python examples/quickstart.py
+```
+
+## Status / limitations
+
+- Streamed (multi-frame) SQL/document results are not yet reassembled (the
+  current server replies in a single frame).
+- KV `range`/`scan` are follow-ups.
+- The client is synchronous; one `Client` owns one connection. Use a `Client`
+  per thread, or one per concurrent transaction.

prismdb-0.1.0/README.md

@@ -0,0 +1,115 @@
+# prismdb (Python)
+
+A **pure-Python** client for [PrismDB](https://github.com/HafizMMoaz/prism-db), speaking the binary
+wire protocol directly over a TCP (or TLS) socket. No native extension, no build
+toolchain — it runs anywhere CPython does.
+
+> Implements `docs/specs/wire-protocol.md`. The byte layouts are kept in lockstep
+> with the Rust `prism-protocol` crate and the reference Node SDK.
+
+## Install
+
+```bash
+pip install prismdb
+```
+
+Requires Python ≥ 3.8. No dependencies.
+
+## Quick start
+
+```python
+from prismdb import Client, Q, U
+
+db = Client.connect(host="127.0.0.1", port=4444, username="admin", password="admin")
+with db:
+    # SQL
+    db.sql("CREATE TABLE users (id BIGINT PRIMARY KEY, name TEXT, age BIGINT)")
+    db.sql("INSERT INTO users VALUES (1,'alice',30),(2,'bob',25)")
+    res = db.sql("SELECT name, age FROM users WHERE age >= 30 ORDER BY age")
+    print(res.rows)  # [{'name': 'alice', 'age': 30}]
+
+    # Key/value
+    db.kv.put("sessions", "sid-1", "payload")
+    v = db.kv.get("sessions", "sid-1")          # bytes | None
+
+    # Documents, with query operators
+    db.doc.insert_one("people", {"name": "carol", "age": 41, "city": "NYC"})
+    adults = db.doc.find("people", Q.and_(Q.eq("city", "NYC"), Q.gt("age", 30)))
+
+    # A transaction is atomic across all three models
+    db.begin()
+    db.sql("INSERT INTO users VALUES (3,'dave',50)")
+    db.kv.put("sessions", "sid-2", "tx")
+    db.commit()                                  # or db.abort()
+```
+
+`Client` is a context manager; leaving the `with` block closes the connection.
+
+## API
+
+### `Client.connect(host="127.0.0.1", port=4444, *, username=None, password=None, database=None, tls=None, ...)`
+
+Performs the `Hello`/`Auth` handshake. Omit `username` to skip authentication
+(only useful against a server that doesn't require it). Pass `tls=True` (or an
+`ssl.SSLContext`) for TLS. On a multi-database server, pass `database=` to select
+it at connect; otherwise run `db.sql("USE <name>")` yourself.
+
+### SQL — `db.sql(text, params=None, *, return_rows=True)`
+
+Returns a `SqlResult` with `.columns`, `.rows` (list of dicts keyed by column
+name), `.raw` (cells in column order), and `.affected_rows` (int).
+
+### KV — `db.kv`
+
+`get(ns, key) -> bytes | None`, `put(ns, key, value)`, `delete(ns, key)`. Keys
+and values are `str` (UTF-8) or `bytes`.
+
+### Documents — `db.doc`
+
+`insert_one` / `insert_many` (return the assigned `ObjectId`s), `find` / `find_one`,
+`count`, `update_one` / `update_many`, `delete_one` / `delete_many`. Build filters
+with `Q` and updates with `U`:
+
+```python
+Q.all()
+Q.eq("f", v); Q.ne; Q.gt; Q.lt; Q.gte; Q.lte
+Q.in_("f", [a, b]); Q.nin("f", [a, b])
+Q.exists("f", True)
+Q.and_(a, b); Q.or_(a, b); Q.not_(a)
+
+db.doc.update_one("people", Q.eq("name", "carol"), [
+    U.set("city", "Boston"),
+    U.inc("age", 1),
+    U.unset("temp"),
+])
+```
+
+### Transactions — `db.begin(mode="read_write")`, `db.commit(idempotency_key=0)`, `db.abort()`
+
+One `Client` is one server session, so calls between `begin()` and `commit()`
+run in that transaction. `commit(idempotency_key=...)` makes a retried commit safe.
+
+### Value mapping
+
+Python → wire: `None`→Null, `bool`→Bool, `int`→Int64, `float`→Double,
+`str`→Str, `bytes`→Binary, `datetime`→Timestamp, `ObjectId`→ObjectId. Use
+`int32(n)`, `float64(n)`, `timestamp(us)` to force a type. On decode, Int64 and
+Timestamp come back as `int`.
+
+## Develop
+
+```bash
+python -m unittest discover -s tests   # unit tests (no server needed)
+
+# end-to-end against a running server:
+prismd run ./data 127.0.0.1:4444
+PRISM_HOST=127.0.0.1 PRISM_PORT=4444 python examples/quickstart.py
+```
+
+## Status / limitations
+
+- Streamed (multi-frame) SQL/document results are not yet reassembled (the
+  current server replies in a single frame).
+- KV `range`/`scan` are follow-ups.
+- The client is synchronous; one `Client` owns one connection. Use a `Client`
+  per thread, or one per concurrent transaction.

prismdb-0.1.0/prismdb/__init__.py

@@ -0,0 +1,43 @@
+"""prismdb — a pure-Python client for PrismDB over the binary wire protocol
+(``docs/specs/wire-protocol.md``). No native build, no C extensions.
+
+    from prismdb import Client, Q, U
+
+    with Client.connect(host="127.0.0.1", port=4444, username="admin", password="admin") as db:
+        db.sql("CREATE TABLE users (id BIGINT PRIMARY KEY, name TEXT)")
+        db.sql("INSERT INTO users VALUES (1, 'alice')")
+        print(db.sql("SELECT * FROM users").rows)
+"""
+
+from .client import Client, SqlResult
+from .document import Document
+from .errors import ErrorCode, ErrorInfo, PrismError, PrismServerError, ProtocolError
+from .query import DocQuery, Q
+from .update import DocUpdate, U
+from .value import TAG, ObjectId, Typed, Value, float64, int32, int64, timestamp
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Client",
+    "SqlResult",
+    "Document",
+    "Q",
+    "DocQuery",
+    "U",
+    "DocUpdate",
+    "ObjectId",
+    "Typed",
+    "Value",
+    "TAG",
+    "int32",
+    "int64",
+    "float64",
+    "timestamp",
+    "PrismError",
+    "PrismServerError",
+    "ProtocolError",
+    "ErrorInfo",
+    "ErrorCode",
+    "__version__",
+]

prismdb-0.1.0/prismdb/_codec.py

@@ -0,0 +1,177 @@
+"""Low-level binary codec: a growable little-endian ``Writer``, a bounds-checked
+``Reader``, and the length-prefixed frame helpers. The byte layouts mirror
+``crates/prism-protocol/src/codec.rs`` exactly (all multi-byte integers LE)."""
+
+from __future__ import annotations
+
+import struct
+
+from .errors import ProtocolError
+
+_U64_MASK = (1 << 64) - 1
+_U128_MASK = (1 << 128) - 1
+
+
+class Writer:
+    """A growable little-endian writer over a bytearray."""
+
+    __slots__ = ("_buf",)
+
+    def __init__(self) -> None:
+        self._buf = bytearray()
+
+    def u8(self, v: int) -> None:
+        self._buf.append(v & 0xFF)
+
+    def u16(self, v: int) -> None:
+        self._buf += struct.pack("<H", v & 0xFFFF)
+
+    def u32(self, v: int) -> None:
+        self._buf += struct.pack("<I", v & 0xFFFFFFFF)
+
+    def i32(self, v: int) -> None:
+        self._buf += struct.pack("<i", _to_signed(v, 32))
+
+    def u64(self, v: int) -> None:
+        self._buf += struct.pack("<Q", v & _U64_MASK)
+
+    def i64(self, v: int) -> None:
+        self._buf += struct.pack("<q", _to_signed(v, 64))
+
+    def f64(self, v: float) -> None:
+        self._buf += struct.pack("<d", v)
+
+    def u128(self, v: int) -> None:
+        """A 128-bit unsigned integer as 16 little-endian bytes."""
+        x = v & _U128_MASK
+        self._buf += struct.pack("<QQ", x & _U64_MASK, (x >> 64) & _U64_MASK)
+
+    def raw(self, b: bytes) -> None:
+        self._buf += b
+
+    def str_u16(self, s: str) -> None:
+        """A UTF-8 string with a u16 length prefix."""
+        b = s.encode("utf-8")
+        self.u16(len(b))
+        self._buf += b
+
+    def str_u32(self, s: str) -> None:
+        """A UTF-8 string with a u32 length prefix."""
+        b = s.encode("utf-8")
+        self.u32(len(b))
+        self._buf += b
+
+    def bytes_u16(self, b: bytes) -> None:
+        """A byte string with a u16 length prefix."""
+        self.u16(len(b))
+        self._buf += b
+
+    def bytes_u32(self, b: bytes) -> None:
+        """A byte string with a u32 length prefix."""
+        self.u32(len(b))
+        self._buf += b
+
+    def out(self) -> bytes:
+        return bytes(self._buf)
+
+
+class Reader:
+    """A bounds-checked little-endian reader over a bytes-like object."""
+
+    __slots__ = ("_buf", "_p")
+
+    def __init__(self, buf: bytes) -> None:
+        self._buf = buf
+        self._p = 0
+
+    def _need(self, n: int) -> None:
+        if self._p + n > len(self._buf):
+            raise ProtocolError(f"truncated: need {n} bytes at offset {self._p}")
+
+    def u8(self) -> int:
+        self._need(1)
+        v = self._buf[self._p]
+        self._p += 1
+        return v
+
+    def u16(self) -> int:
+        self._need(2)
+        v = struct.unpack_from("<H", self._buf, self._p)[0]
+        self._p += 2
+        return v
+
+    def u32(self) -> int:
+        self._need(4)
+        v = struct.unpack_from("<I", self._buf, self._p)[0]
+        self._p += 4
+        return v
+
+    def i32(self) -> int:
+        self._need(4)
+        v = struct.unpack_from("<i", self._buf, self._p)[0]
+        self._p += 4
+        return v
+
+    def u64(self) -> int:
+        self._need(8)
+        v = struct.unpack_from("<Q", self._buf, self._p)[0]
+        self._p += 8
+        return v
+
+    def i64(self) -> int:
+        self._need(8)
+        v = struct.unpack_from("<q", self._buf, self._p)[0]
+        self._p += 8
+        return v
+
+    def f64(self) -> float:
+        self._need(8)
+        v = struct.unpack_from("<d", self._buf, self._p)[0]
+        self._p += 8
+        return v
+
+    def u128(self) -> int:
+        self._need(16)
+        lo, hi = struct.unpack_from("<QQ", self._buf, self._p)
+        self._p += 16
+        return (hi << 64) | lo
+
+    def raw(self, n: int) -> bytes:
+        self._need(n)
+        s = self._buf[self._p : self._p + n]
+        self._p += n
+        return bytes(s)
+
+    def str_u16(self) -> str:
+        return self.raw(self.u16()).decode("utf-8")
+
+    def str_u32(self) -> str:
+        return self.raw(self.u32()).decode("utf-8")
+
+    def bytes_u16(self) -> bytes:
+        return self.raw(self.u16())
+
+    def bytes_u32(self) -> bytes:
+        return self.raw(self.u32())
+
+    def remaining(self) -> int:
+        return len(self._buf) - self._p
+
+    def expect_end(self) -> None:
+        """Raise unless every byte has been consumed."""
+        if self.remaining() != 0:
+            raise ProtocolError(f"{self.remaining()} trailing byte(s) after message")
+
+
+def _to_signed(v: int, bits: int) -> int:
+    """Wrap ``v`` into a signed ``bits``-wide integer (two's complement)."""
+    mask = (1 << bits) - 1
+    v &= mask
+    if v >= 1 << (bits - 1):
+        v -= 1 << bits
+    return v
+
+
+def frame_encode(payload: bytes) -> bytes:
+    """Wrap a payload in a ``[len:u32][payload]`` frame."""
+    return struct.pack("<I", len(payload)) + payload