redis/README.md

# redis

Async Redis wrapper over redis-py's asyncio client — a small, config-free, **fail-loud**
key/value + hash + ttl surface with a raw escape hatch for everything else. First of the
datastore trio (`redis` / `psql` / `mysql`), a sibling of the `mongo` lib.

> **Import name ≠ repo name.** The repo is **`redis`**, the distribution is
> **`redis_store`** — the driver package owns the `redis` import namespace, so the lib
> can't also be `redis`. Install resolves `redis.git`; code does
> `from redis_store import RedisDB`.

## Install

`requirements.txt`:

```
redis_store @ git+ssh://git@git.rethinkstudios.io/rethink-public/redis.git@v0.1.4
```

Direct:

```bash
pip install "redis_store @ git+ssh://git@git.rethinkstudios.io/rethink-public/redis.git@v0.1.4"
```

Pulls `redis>=5.0.1` (redis-py, which ships the asyncio client — **not** the dead standalone
`aioredis`; `5.0.1` is the floor because `5.0.0` lacks the async client's `aclose()`).

Drop the `@v0.1.4` suffix from the line above to install the latest unpinned.

## Usage

```python
from redis_store import RedisDB

# construction is sync and opens no socket; connect() pings to fail loud on bad config
kv = await RedisDB(host="localhost", port=6379, db=0, password=None).connect()

await kv.set("user:1:name", "ada", ex=3600)   # ex = ttl seconds (optional)
name = await kv.get("user:1:name")            # "ada"   (None if absent)
await kv.incr("hits")                          # atomic counter -> int

await kv.hset("user:1", mapping={"name": "ada", "role": "admin"})
role = await kv.hget("user:1", "role")        # "admin"
everything = await kv.hgetall("user:1")        # {"name": "ada", "role": "admin"}

await kv.close()                               # on shutdown
```

Context-manager form:

```python
async with RedisDB(host="localhost") as kv:
    await kv.incr("hits")
```

One client/pool per process — build it once, attach it to your app (`app.kv = ...`), share it.
A failed `connect()`/`__aenter__` ping disconnects the pool before re-raising, so a
discarded `RedisDB` from a failed `async with` doesn't hold a live pool.

## Type contract

`decode_responses=True` by default: keys and string values come back as **`str`** (and
`None` for an absent key). Pass `decode_responses=False` at construction for raw `bytes`.
Counters and counts (`incr`/`decr`/`exists`/`ttl`) always return `int` regardless.

Pool sizing/timeout are `max_connections=` and `pool_timeout=` (how long a caller waits for
a free connection when the pool is saturated; `Optional[float]`, `None` waits forever).
Pass the driver's own `timeout=` in `pool_kwargs` and construction raises a clear
`ValueError` — use `pool_timeout=`.

`ssl=True` maps to `connection_class=redis.asyncio.SSLConnection`, so TLS works via the
documented `pool_kwargs` path (the default connection class has no `ssl` parameter and
would otherwise defer a `TypeError` to `connect()`). Pass ssl-prefixed kwargs alongside
it (`ssl_ca_certs`, `ssl_certfile`, ...) to configure the handshake.

## Error contract — fail loud

Unlike the `mongo` lib (which log-and-swallows, returning a safe default), **this lib
re-raises.** Every wrapped method catches the driver's `RedisError`, logs it via
`logging.getLogger(__name__)`, and raises. A `None` / `[]` / `{}` return is only ever a
real result (absent key, empty hash) — never a swallowed failure. So a caller can trust
that no exception means the op succeeded.

For anything not wrapped — pipelines, pub/sub, `scan`, Lua, transactions — use the raw
escape hatch:

```python
async with kv.client.pipeline() as pipe:
    await pipe.set("a", 1).set("b", 2).execute()
```

`kv.client` is the underlying `redis.asyncio.Redis`: full driver surface, raises,
nothing swallowed.

## Surface

- **key/value:** `get`, `set` (optional `ex` ttl), `delete`, `exists`, `incr`, `decr`
- **hash:** `hget`, `hset` (single `key`/`value` or `mapping=`), `hgetall`, `hdel`
- **expiry/ttl:** `expire`, `ttl` (driver sentinels pass through: `-1` no expiry, `-2`
  key absent)
- **raw:** `client` property → `redis.asyncio.Redis`

Pub/sub and a `pipeline()` wrapper are intentionally **not** wrapped yet — the raw
`client` covers them; they'll be added when a consumer needs the ergonomics.

## Versioning

Releases are tagged `vX.Y.Z`. The install line above pins a release; drop the `@vX.Y.Z`
suffix to install the latest unpinned. Pin deliberately for reproducible installs.