Metadata-Version: 2.4
Name: ewoxdbredis
Version: 2.0.1
Summary: Shared synchronous and asynchronous Redis clients, repositories, streams, caches, locks, and durable sessions for Ewox services.
License-Expression: MIT
License-File: LICENSE
Keywords: redis,cache,streams,sessions,distributed-systems
Author: Martin Leo Prüss
Author-email: mleopruss@gmail.com
Requires-Python: >=3.13,<4.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Typing :: Typed
Requires-Dist: ewoxcore (>=1.6.36,<2.0.0)
Requires-Dist: redis (>=7.4.0,<9.0.0)
Requires-Dist: tenacity (>=9.1.4,<10.0.0)
Project-URL: Documentation, https://github.com/mlpruss/ewox-db-redis/tree/master/docs
Project-URL: Homepage, https://github.com/mlpruss/ewox-db-redis
Project-URL: Issues, https://github.com/mlpruss/ewox-db-redis/issues
Project-URL: Repository, https://github.com/mlpruss/ewox-db-redis
Description-Content-Type: text/markdown

# ewoxdbredis

`ewoxdbredis` provides production-oriented Redis infrastructure for Python
services. It includes validated standalone and cluster clients, synchronous
and asynchronous connection lifecycles, environment-scoped repositories,
distributed caching, Redis streams, distributed locks, and durable logical
sessions.

## Requirements

- Python 3.13
- Redis Server 7.4 or newer
- `APP_ENV` for repository and session key isolation

Redis 7.4 is required by hash-field expiration. Other features use commands
available in Redis 7.4 and are tested against both standalone Redis and Redis
Cluster.

## Install

```bash
pip install ewoxdbredis
```

## Asynchronous client and repository

Create one shared client during application startup, call `setup()` before
using it, inject it into providers and repositories, and call `dispose()`
during shutdown.

```python
import asyncio
import logging
import os

from ewoxdbredis.clients.redis_instance_client import RedisInstanceClient
from ewoxdbredis.repositories.redis_expire_repository import (
    RedisExpireRepository,
)
from ewoxdbredis.settings.connection_settings import ConnectionSettings


async def main() -> None:
    os.environ.setdefault("APP_ENV", "development")
    client = RedisInstanceClient(
        ConnectionSettings(host="localhost", port=6379)
    )
    await client.setup()

    try:
        repository = RedisExpireRepository("example")
        connection = client.get_connection()
        await repository.set(connection, "greeting", "hello")
        value: str = await repository.get(connection, "greeting")
        logging.info("Greeting: %s", value)
    finally:
        await client.dispose()


if __name__ == "__main__":
    logging.basicConfig(level=logging.INFO)
    asyncio.run(main())
```

For Redis Cluster, use `RedisClusterClient` with the same lifecycle.
Applications create one shared `IRedisClient` during startup and inject it into
providers and repository implementations.

## Synchronous client

`DBConnection` is the supported synchronous API. Entering the context creates
the configured standalone or cluster connection, validates it with `PING`, and
leaving the context closes it.

```python
from ewoxdbredis.connection.db_connection import DBConnection
from ewoxdbredis.settings.connection_settings import ConnectionSettings


with DBConnection(ConnectionSettings(host="localhost")) as redis:
    redis.set("example", "value")
    assert redis.get("example") == "value"
```

## Capabilities

- Standalone and Redis Cluster async clients with TLS trust configuration,
  mutual TLS, authentication, RESP selection, timeouts, health checks, retries,
  and explicit lifecycle management
- Supported synchronous standalone and cluster access through `DBConnection`
- Scalar, hash, set, and sorted-set repositories with environment-prefixed
  keys and cluster-safe scanning
- Two-level distributed caching with Redis-first writes and optional local L1
- At-least-once Redis stream consumption with retry, bounded concurrency,
  pending-message recovery, dead-letter inspection, replay, and shutdown
- Distributed locks with explicit ownership-loss handling and opt-in renewal
  and fencing tokens
- Durable logical sessions with resume-token rotation, fencing, leases,
  idempotent delivery IDs, browser acknowledgements, and dead-letter replay

## Documentation

- [Configuration and client lifecycle](docs/configuration.md)
- [Repositories and distributed cache](docs/repositories.md)
- [Streams and dead letters](docs/streams.md)
- [Distributed session management](docs/session_management.md)
- [Operations and production guidance](docs/operations.md)
- [Unit and integration testing](docs/testing.md)
- [Release process](docs/release.md)
- [Runnable examples](examples/README.md)

## Development

```bash
poetry install
APP_ENV=unittest poetry run pytest -m "not integration"
poetry check --strict
poetry run ruff check --select F src tests examples scripts
poetry run pyright src/ewoxdbredis
poetry build
poetry run twine check dist/*
python scripts/verify_distribution.py dist
```

Run the standalone and cluster integration suites in self-contained Redis 7.4
containers:

```bash
./scripts/run_integration_tests.sh
```

Docker Engine or Docker Desktop with Compose v2 provisions the complete Redis
test topology. See [docs/testing.md](docs/testing.md) for VS Code unit-test
setup, integration prerequisites, cleanup, and external Redis commands.
See [CONTRIBUTING.md](CONTRIBUTING.md) for the complete verification workflow.

## License

MIT. See [LICENSE](LICENSE).

