kevy 5.1.0__tar.gz

kevy-5.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: kevy
+Version: 5.1.0
+Summary: First-party Python client for kevy — the pure-Rust Redis-compatible engine (embedded + remote, blocking + asyncio).
+Author: GOLIA K.K.
+License-Expression: MIT OR Apache-2.0
+Project-URL: Homepage, https://kevy.golia.jp
+Project-URL: Documentation, https://kevy.golia.jp
+Project-URL: Repository, https://github.com/goliajp/kevy
+Project-URL: Changelog, https://kevy.golia.jp/changelog/
+Project-URL: Issues, https://github.com/goliajp/kevy/issues
+Keywords: kevy,redis,resp,key-value,database,asyncio
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Database
+Classifier: Topic :: Database :: Front-Ends
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pytest-asyncio>=0.21; extra == "test"
+Requires-Dist: pytest-timeout>=2; extra == "test"
+
+# kevy — Python client
+
+First-party Python client for **kevy**, the pure-Rust, Redis-compatible
+engine. One package ships **both faces** (contract §1.4): a blocking
+`Client` and an asyncio `AsyncClient` — the same shape as redis-py's
+`redis` + `redis.asyncio`.
+
+```sh
+pip install kevy
+```
+
+```python
+import kevy
+
+# Remote — native RESP2/3 over TCP. Standard library only.
+r = kevy.connect("kevy://127.0.0.1:6379")
+r.set("k", "v")
+assert r.get(b"k") == b"v"
+
+# Asyncio — same package, same results.
+ac = await kevy.AsyncClient.connect("kevy://127.0.0.1:6379")
+await ac.set("k", "v")
+
+# Embedded (in-process), over the C ABI with ctypes. Needs the engine —
+# see below; this line raises a message naming where to get it otherwise.
+c = kevy.connect("mem://app")        # or  file:///var/lib/app
+```
+
+## The embedded engine
+
+`mem://` and `file://` run kevy inside your process through
+`libkevy_ffi`, a per-platform native library. A Python wheel does not
+carry it: it would work on the handful of targets we happened to build
+and nowhere else, while the remote client above works everywhere
+CPython does. So the engine comes from the engine's own repository —
+
+```sh
+git clone https://github.com/goliajp/kevy
+cd kevy && cargo build --release -p kevy-ffi   # → target/release/
+```
+
+— and is found automatically from a kevy checkout, or by pointing
+`KEVY_FFI_LIB` at the built library. Without it, the first embedded call
+raises an error saying exactly this. Nothing else in the API differs.
+
+## One URL, two transports (§1.1)
+
+| Scheme | Backend |
+|---|---|
+| `mem://` | embedded, isolated in-memory store |
+| `mem://<name>` | embedded, shared by name (pub/sub works cross-connect) |
+| `file:///abs/path` | embedded, persistent (snapshot + AOF) |
+| `kevy://` / `redis://` / `tcp://` | remote RESP over TCP |
+
+`rediss://` / `kevys://` (TLS) and `redis://user:pass@host` (AUTH) are
+rejected — kevy has neither.
+
+## Embedded door (§5)
+
+`kevy.open_mem()` / `kevy.open_persistent(dir)` return a `DB` — the
+in-process store over `libkevy_ffi`, driven by ctypes (no C-extension
+build). Every verb is reachable through `db.cmd(*argv) -> Reply`; `db.get`
+/ `db.set` are the scalar fast paths; `db.subscribe(chan)` gives a polled
+(`next()`) + blocking (`wait(ms)`) subscription. The library is located via
+`$KEVY_FFI_LIB` or the repo `target/{release,debug}` build.
+
+## Command families
+
+Every family of the contract (§3): core string/generic, hash, list, set,
+sorted set, sorted-set algebra, hash-field TTL, declarative indexes
+(`idx_*`, remote-only) — with any other `IDX.*` subcommand reachable through
+the raw `do(*argv)` / `idx_query_raw` escape hatches — change feed
+(`feed_*`), pub/sub
+(`Subscriber` / `AsyncSubscriber`), transactions (`Transaction`),
+pipelines, blocking pops (`blpop`/`brpop`/`bzpopmin`), and the cluster
+client (`ClusterClient`). Bytes and `str` are both accepted; the wire is
+bytes (§7).
+
+## Errors (§2)
+
+Raised as a `KevyError` hierarchy inspectable by type: `StoreError`
+(`WrongTypeError`, `NotIntegerError`, …), `ProtocolError`, `IoError`,
+`UnsupportedError`, `InvalidInputError`, `NotFoundError`, `ReadOnlyError`,
+`TimedOutError`, `ClosedError`.
+
+## Tests
+
+```
+pip install -e '.[test]'
+pytest                       # embedded + remote (spawns a real kevy server)
+```
+
+Remote tests build and boot `kevy` on a temp port; they skip cleanly if the
+server binary is absent (`cargo build --release -p kevy`).

kevy-5.1.0/README.md

@@ -0,0 +1,94 @@
+# kevy — Python client
+
+First-party Python client for **kevy**, the pure-Rust, Redis-compatible
+engine. One package ships **both faces** (contract §1.4): a blocking
+`Client` and an asyncio `AsyncClient` — the same shape as redis-py's
+`redis` + `redis.asyncio`.
+
+```sh
+pip install kevy
+```
+
+```python
+import kevy
+
+# Remote — native RESP2/3 over TCP. Standard library only.
+r = kevy.connect("kevy://127.0.0.1:6379")
+r.set("k", "v")
+assert r.get(b"k") == b"v"
+
+# Asyncio — same package, same results.
+ac = await kevy.AsyncClient.connect("kevy://127.0.0.1:6379")
+await ac.set("k", "v")
+
+# Embedded (in-process), over the C ABI with ctypes. Needs the engine —
+# see below; this line raises a message naming where to get it otherwise.
+c = kevy.connect("mem://app")        # or  file:///var/lib/app
+```
+
+## The embedded engine
+
+`mem://` and `file://` run kevy inside your process through
+`libkevy_ffi`, a per-platform native library. A Python wheel does not
+carry it: it would work on the handful of targets we happened to build
+and nowhere else, while the remote client above works everywhere
+CPython does. So the engine comes from the engine's own repository —
+
+```sh
+git clone https://github.com/goliajp/kevy
+cd kevy && cargo build --release -p kevy-ffi   # → target/release/
+```
+
+— and is found automatically from a kevy checkout, or by pointing
+`KEVY_FFI_LIB` at the built library. Without it, the first embedded call
+raises an error saying exactly this. Nothing else in the API differs.
+
+## One URL, two transports (§1.1)
+
+| Scheme | Backend |
+|---|---|
+| `mem://` | embedded, isolated in-memory store |
+| `mem://<name>` | embedded, shared by name (pub/sub works cross-connect) |
+| `file:///abs/path` | embedded, persistent (snapshot + AOF) |
+| `kevy://` / `redis://` / `tcp://` | remote RESP over TCP |
+
+`rediss://` / `kevys://` (TLS) and `redis://user:pass@host` (AUTH) are
+rejected — kevy has neither.
+
+## Embedded door (§5)
+
+`kevy.open_mem()` / `kevy.open_persistent(dir)` return a `DB` — the
+in-process store over `libkevy_ffi`, driven by ctypes (no C-extension
+build). Every verb is reachable through `db.cmd(*argv) -> Reply`; `db.get`
+/ `db.set` are the scalar fast paths; `db.subscribe(chan)` gives a polled
+(`next()`) + blocking (`wait(ms)`) subscription. The library is located via
+`$KEVY_FFI_LIB` or the repo `target/{release,debug}` build.
+
+## Command families
+
+Every family of the contract (§3): core string/generic, hash, list, set,
+sorted set, sorted-set algebra, hash-field TTL, declarative indexes
+(`idx_*`, remote-only) — with any other `IDX.*` subcommand reachable through
+the raw `do(*argv)` / `idx_query_raw` escape hatches — change feed
+(`feed_*`), pub/sub
+(`Subscriber` / `AsyncSubscriber`), transactions (`Transaction`),
+pipelines, blocking pops (`blpop`/`brpop`/`bzpopmin`), and the cluster
+client (`ClusterClient`). Bytes and `str` are both accepted; the wire is
+bytes (§7).
+
+## Errors (§2)
+
+Raised as a `KevyError` hierarchy inspectable by type: `StoreError`
+(`WrongTypeError`, `NotIntegerError`, …), `ProtocolError`, `IoError`,
+`UnsupportedError`, `InvalidInputError`, `NotFoundError`, `ReadOnlyError`,
+`TimedOutError`, `ClosedError`.
+
+## Tests
+
+```
+pip install -e '.[test]'
+pytest                       # embedded + remote (spawns a real kevy server)
+```
+
+Remote tests build and boot `kevy` on a temp port; they skip cleanly if the
+server binary is absent (`cargo build --release -p kevy`).

kevy-5.1.0/kevy/__init__.py

@@ -0,0 +1,148 @@
+"""kevy — the first-party Python client for the pure-Rust, Redis-compatible
+kevy engine.
+
+One package, both faces (contract §1.4): a blocking :class:`Client` and an
+asyncio :class:`AsyncClient`, exactly as redis-py ships ``redis`` +
+``redis.asyncio``. A single ``connect(url)`` chooses the backend from the URL
+scheme (§1.1): ``mem://`` / ``file://`` open the in-process **embedded**
+engine (a ctypes binding over the C ABI ``libkevy_ffi`` — the new Python
+embedded door, §5); ``kevy://`` / ``redis://`` / ``tcp://`` open a native
+RESP2/3 TCP client. The wire is bytes; every key/value is binary-safe (§7).
+
+    import kevy
+
+    c = kevy.connect("mem://app")          # embedded, blocking
+    c.set("k", "v"); print(c.get(b"k"))    # -> b"v"
+
+    ac = await kevy.AsyncClient.connect("kevy://127.0.0.1:6379")
+    await ac.set("k", "v")
+
+Errors are raised as a :class:`KevyError` hierarchy inspectable by type (§2).
+"""
+
+from __future__ import annotations
+
+from ._client import Client
+from ._client_async import AsyncClient
+from ._cluster import ClusterClient, crc16, key_hash_slot
+from ._embedded import DB, Sub, abi, open_mem, open_persistent, version
+from ._enums import EvictionPolicy, HExpireCond, IdxType, RespVersion, ZAggregate
+from ._errors import (
+    ClosedError,
+    InvalidInputError,
+    IoError,
+    KevyError,
+    NoSuchKeyError,
+    NotFloatError,
+    NotFoundError,
+    NotIntegerError,
+    OutOfMemoryStoreError,
+    OutOfRangeError,
+    OverflowStoreError,
+    ProtocolError,
+    ReadOnlyError,
+    StoreError,
+    StoreErrorKind,
+    TimedOutError,
+    UnsupportedError,
+    WrongTypeError,
+)
+from ._pipeline import PipelineBuf
+from ._reply import Reply, ReplyKind
+from ._subscriber import Subscriber
+from ._subscriber_async import AsyncSubscriber
+from ._transaction import Transaction, TransactionReplies
+from ._transaction_async import AsyncTransaction
+from ._types import (
+    FeedBatch,
+    FeedFrame,
+    IdxInfo,
+    IdxPage,
+    IdxRow,
+    PubsubEvent,
+    PubsubKind,
+    Ranked,
+    ZMember,
+    ZPopHit,
+    KV,
+)
+
+__version__ = "5.1.0"
+
+
+def connect(url: str) -> Client:
+    """Open a blocking :class:`Client` for ``url`` (§1.1). Equivalent to
+    :meth:`Client.connect`."""
+    return Client.connect(url)
+
+
+async def aconnect(url: str) -> AsyncClient:
+    """Open an asyncio :class:`AsyncClient` for ``url`` (§1.4). Equivalent to
+    :meth:`AsyncClient.connect`."""
+    return await AsyncClient.connect(url)
+
+
+__all__ = [
+    "__version__",
+    "connect",
+    "aconnect",
+    # clients
+    "Client",
+    "AsyncClient",
+    "ClusterClient",
+    "Subscriber",
+    "AsyncSubscriber",
+    "Transaction",
+    "AsyncTransaction",
+    "TransactionReplies",
+    "PipelineBuf",
+    # embedded store
+    "DB",
+    "Sub",
+    "open_mem",
+    "open_persistent",
+    "abi",
+    "version",
+    # reply / enums
+    "Reply",
+    "ReplyKind",
+    "ZAggregate",
+    "HExpireCond",
+    "IdxType",
+    "RespVersion",
+    "EvictionPolicy",
+    # data types
+    "ZMember",
+    "KV",
+    "ZPopHit",
+    "IdxRow",
+    "IdxPage",
+    "IdxInfo",
+    "Ranked",
+    "FeedFrame",
+    "FeedBatch",
+    "PubsubEvent",
+    "PubsubKind",
+    # cluster helpers
+    "crc16",
+    "key_hash_slot",
+    # errors
+    "KevyError",
+    "StoreError",
+    "StoreErrorKind",
+    "WrongTypeError",
+    "NotIntegerError",
+    "OverflowStoreError",
+    "OutOfRangeError",
+    "NoSuchKeyError",
+    "NotFloatError",
+    "OutOfMemoryStoreError",
+    "IoError",
+    "ProtocolError",
+    "ReadOnlyError",
+    "InvalidInputError",
+    "NotFoundError",
+    "UnsupportedError",
+    "TimedOutError",
+    "ClosedError",
+]