Metadata-Version: 2.4
Name: burner-redis
Version: 0.1.7
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: 3
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: pytest-asyncio ; extra == 'dev'
Requires-Dist: maturin ; extra == 'dev'
Requires-Dist: redis ; extra == 'dev'
Provides-Extra: dev
License-File: LICENSE
Summary: An embedded, in-process Redis-compatible database
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/PrefectHQ/burner-redis
Project-URL: Issues, https://github.com/PrefectHQ/burner-redis/issues
Project-URL: Repository, https://github.com/PrefectHQ/burner-redis

# burner-redis

> **Experimental:** This library is under active development and not yet ready for production use. APIs may change without notice.

An embedded, in-process Redis-compatible database written in Rust with Python bindings. Drop-in replacement for `redis.asyncio.Redis` that runs inside the host process with no external server needed.

Built to back [docket](https://github.com/chrisguidry/docket) and self-hosted [Prefect](https://github.com/PrefectHQ/prefect) servers without requiring a separate Redis deployment.

## Installation

```bash
pip install burner-redis
```

Requires Python 3.10+. Pre-built wheels available for Linux (x86_64, aarch64), macOS (x86_64, arm64), and Windows (x86_64, arm64).

## Quick start

```python
from burner_redis import BurnerRedis

db = BurnerRedis()

# Use like redis.asyncio.Redis
await db.set("key", "value")
value = await db.get("key")

# Persistence across restarts
db = BurnerRedis(persistence_path="data.dat")
await db.set("key", "value")
# Data is saved on process exit and reloaded on next start
```

## Supported commands

### Strings
`SET` (with NX/EX/PX), `GET`, `MGET`, `DELETE`, `EXISTS`, `KEYS`, `TTL`, `EXPIRE`

### Hashes
`HSET`, `HGET`, `HDEL`, `HGETALL`, `HVALS`, `HEXISTS`, `HINCRBY`

### Sets
`SADD`, `SMEMBERS`, `SISMEMBER`, `SREM`

### Sorted sets
`ZADD`, `ZREM`, `ZRANGE` (with WITHSCORES), `ZRANGEBYSCORE` (with WITHSCORES/LIMIT), `ZRANGESTORE`, `ZREMRANGEBYSCORE`, `ZCARD`, `ZSCORE`, `ZCOUNT`

### Streams
`XADD`, `XREAD`, `XLEN`, `XRANGE`, `XDEL`, `XTRIM`, `XGROUP CREATE`, `XGROUP DESTROY`, `XREADGROUP`, `XACK`, `XAUTOCLAIM`, `XCLAIM`, `XINFO GROUPS`, `XINFO CONSUMERS`, `XPENDING`, `XPENDING RANGE`

### Pub/Sub
`PUBLISH`, `SUBSCRIBE`, `UNSUBSCRIBE`, `PSUBSCRIBE`, `PUNSUBSCRIBE`, `PUBSUB CHANNELS`, `PUBSUB NUMSUB`, `PUBSUB NUMPAT`

### Scripting
`EVAL`, `EVALSHA`, `SCRIPT LOAD`, `SCRIPT EXISTS`

### Python-layer features
- **Pipeline** &mdash; buffer commands and execute in batch, matching `redis.asyncio.Redis.pipeline()` semantics
- **Lock** &mdash; distributed-style locking with atomic Lua-based release, matching `redis.asyncio.Redis.lock()` semantics
- **PubSub** &mdash; async message listener with channel and pattern subscriptions
- **Script** &mdash; register and call Lua scripts, matching `redis.asyncio.Redis.register_script()`

## Persistence

Pass `persistence_path` to save state to disk on shutdown and restore on startup:

```python
db = BurnerRedis(persistence_path="burner-redis.dat")
```

- Crash-safe writes (atomic temp file + rename)
- Expired keys excluded from snapshots
- Manual save available via `await db.save()` or `await db.save(path="custom.dat")`
- MessagePack binary format

## redis-py compatibility

burner-redis implements a subset of the `redis.asyncio.Redis` interface — enough to back [docket](https://github.com/chrisguidry/docket) and common Prefect server workflows, but not the full redis-py API. Commands not yet implemented will raise `NotImplementedError`.

When the `redis` package is installed, exceptions subclass `redis.exceptions.ResponseError` and `redis.exceptions.NoScriptError` so existing error handling works unchanged.

## Development

```bash
# Prerequisites: Rust 1.85+, Python 3.10+, uv

# Development build
uv run maturin develop

# Run tests
uv run pytest

# Run Rust tests
cargo test
```

## Packaging notes

Wheel builds use a vendored Lua 5.4 by default so `pip install burner-redis` does not require a
system Lua.

Packaging systems that already provide Lua can opt out of vendoring and link against that copy
instead:

```bash
maturin build --release --no-default-features
```

If auto-detection is not available, point Cargo at the packaged Lua library explicitly:

```bash
LUA_LIB_NAME=lua
LUA_LIB=/path/to/lib
```

## License

MIT

