Redis
The Redis providers implement the KeyValueStoreProtocol on a Redis server. Redis serves values from memory, so these stores suit small values that are read often, such as cached results, tokens or session state. Whether values survive a server restart depends on the server’s persistence settings, not on hexkit. For values that must be durable, use the MongoDB or S3 stores; for secrets, use Vault.
To use them, install hexkit with the redis extra:
pip install hexkit[redis]Redis KV Store Providers
There is one store per value-type variant: RedisBytesKeyValueStore, RedisStrKeyValueStore, RedisJsonKeyValueStore and RedisDtoKeyValueStore. All four share the configuration, construction and key handling described below.
Configuration
Connection parameters are collected in RedisConfig. Inherit your service’s config class from it (see Configuration), or instantiate it directly:
from hexkit.providers.redis import RedisConfig
config = RedisConfig(redis_url="redis://localhost:6379/0")| Parameter | Description |
|---|---|
redis_url |
The connection URL, in the form redis://[[username]:password@]host[:port][/database], or with rediss:// for TLS. The port defaults to 6379 and the database to 0. Stored as a Pydantic Secret, because it may contain credentials. |
redis_timeout |
Optional socket timeout in whole seconds, applied to every Redis operation, including connection. When exceeded, the operation raises a redis.exceptions.TimeoutError. Defaults to None (no timeout). |
Creating Stores
The recommended way to create a store is the construct() async context manager, which opens a Redis client on entry and closes it on exit:
from pydantic import BaseModel
from hexkit.providers.redis import RedisDtoKeyValueStore
class Book(BaseModel):
id: str
title: str
year: int
async with RedisDtoKeyValueStore.construct(
config=config, dto_model=Book, key_prefix="books:"
) as book_store:
await book_store.set("b1", Book(id="b1", title="Dune", year=1965))
book = await book_store.get("b1")Only the Dto store takes the extra dto_model argument. key_prefix is optional in construct() for all four stores, but the Dto store’s own constructor requires it.
Each construct() call opens its own client with its own connection pool. To let several stores share one client, open it with ConfiguredRedisClient and pass it to the stores’ constructors:
from hexkit.providers.redis import (
ConfiguredRedisClient,
RedisJsonKeyValueStore,
RedisStrKeyValueStore,
)
async with ConfiguredRedisClient(config) as client:
token_store = RedisStrKeyValueStore(
client=client, config=config, key_prefix="tokens:"
)
settings_store = RedisJsonKeyValueStore(
client=client, config=config, key_prefix="settings:"
)
...Value Types
| Store | Accepts | Stored in Redis as |
|---|---|---|
| RedisBytesKeyValueStore | bytes |
The bytes unchanged |
| RedisStrKeyValueStore | str |
UTF-8 text |
| RedisJsonKeyValueStore | dict (a JSON object) |
JSON text |
| RedisDtoKeyValueStore | Instances of dto_model |
The model’s fields as JSON text, validated against dto_model on read |
set() raises a TypeError if a value does not match the store’s type. The Json store accepts only JSON objects, not lists or single values, and no store accepts None. The Dto store converts a model with model_dump() and then json.dumps(), so set() also raises a TypeError for a model with a field that json.dumps() cannot encode, such as a UUID or datetime.
Keys and Prefixes
A store writes each key as key_prefix followed by the key, so the book_store above stores "b1" under the Redis key books:b1. The prefix defaults to an empty string.
All stores on the same Redis database share one keyspace, and a store reads whatever value is stored under its key. Give each store its own prefix, or its own database through the /database part of redis_url. Otherwise, stores that use the same key overwrite each other’s values, and reading another store’s value can return the wrong type without an error. For example, a Json store reads the Str value "123" as the integer 123, and raises a JSONDecodeError only on text that is not JSON.
The stores set no expiry, so a value stays until it is deleted or the server evicts it.
Error Handling
The stores do not translate Redis errors into hexkit errors, so callers see the exceptions of the redis-py client:
redis.exceptions.ConnectionErrorif the server cannot be reached. The client connects lazily, so construct() succeeds and the first operation raises.redis.exceptions.TimeoutErrorif an operation exceedsredis_timeout.
To trace Redis operations, install the opentelemetry-redis extra; see OpenTelemetry.
Redis Test Utils
For integration tests, the test-redis extra provides pytest fixtures based on testcontainers that start a disposable Redis container from the image named in REDIS_IMAGE. The test and all extras do not include it, so install it explicitly:
pip install hexkit[test-redis]All utilities live in hexkit.providers.redis.testutils.
Fixtures
The redis_fixture yields a RedisFixture object under the fixture name redis. Both the container fixture and the Redis fixture must be imported into the test module or its conftest.py for pytest to resolve them, hence the # noqa: F401 comments:
import pytest
from hexkit.providers.redis import RedisDtoKeyValueStore
from hexkit.providers.redis.testutils import (
RedisFixture,
redis_container_fixture, # noqa: F401
redis_fixture, # noqa: F401
)
@pytest.mark.asyncio()
async def test_book_store(redis: RedisFixture):
async with RedisDtoKeyValueStore.construct(
config=redis.config, dto_model=Book, key_prefix="books:"
) as book_store:
await book_store.set("b1", Book(id="b1", title="Dune", year=1965))
assert redis.client.keys("books:*") == [b"books:b1"]The fixtures split the work between two scopes:
redis_container_fixture(fixture nameredis_container) is session-scoped: one Redis container is started per test session and reused by all tests.redis_fixture(fixture nameredis) is function-scoped: it flushes the database before each test, so every test starts with no keys.clean_redis_fixtureis an alias for it.persistent_redis_fixtureis the variant without the flush, for tests that intentionally share state. It also uses the fixture nameredis, so do not import it into the same module asredis_fixture.
If the default scopes or names do not fit your test setup, the factory functions get_redis_container_fixture, get_clean_redis_fixture and get_persistent_redis_fixture create the same fixtures with custom scope and name arguments. For example, get_persistent_redis_fixture(name="redis_persistent") lets both variants be used in one module.
The RedisFixture
A RedisFixture has two attributes and one method:
config: a RedisConfig pointing at the test container, to pass to the stores.client: a synchronousredis.Redisclient for arranging and inspecting state directly, as in thekeys()call above. The stores need an asynchronous client, so do not pass this one to their constructors.flush_db(): deletes all keys from the database.
For unit tests without a container, use the in-memory key-value stores instead. The provider’s own integration tests show further usage.