Development

Setup

git clone <repo>
cd redis-stream-queue

python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

pip install -e ".[dev]"          # editable install + test deps

Running Tests

Tests use fakeredis — no real Redis needed.

# All tests
pytest tests/

# Single file
pytest tests/test_consumer.py

# Single test with verbose output
pytest tests/test_consumer.py::test_poison_pill_goes_to_dlq -v -s

# With coverage
pip install pytest-cov
pytest tests/ --cov=src/redis_stream_queue --cov-report=term-missing

Building Documentation Locally

pip install -e ".[docs]"

# Live-reload preview server
mkdocs serve

# One-shot build (promotes warnings to errors)
mkdocs build --strict

Project Structure

src/
└── redis_stream_queue/
    ├── __init__.py     # public exports
    ├── client.py       # StreamClient — connection pool, all X* commands
    ├── producer.py     # StreamProducer — push + ProducerMetrics + all_metrics()
    ├── consumer.py     # StreamConsumer — main loop + all_metrics()
    ├── group.py        # ConsumerConfig + ConsumerGroup (class-level registry, stats, health)
    ├── message.py      # StreamMessage, PendingEntry, StreamStats, ConsumerInfo,
    │                   # ConsumerMetrics, ProducerMetrics, _TpsTracker
    ├── retry.py        # RetryHandler — poison-pill detection + DLQ routing
    ├── serializers.py  # Json / Msgpack / Pickle
    └── exceptions.py
tests/
    conftest.py         # shared fixtures: fake_redis, make_client, registry resets
    test_consumer.py    # consumer loop, metrics, all_metrics, NOGROUP recovery
    test_group.py       # stats, health check, pending details
    test_producer.py    # push, ensure_group, metrics, all_metrics
examples/
    basic_worker.py

Known Limitations

• fetch_by_ids N+1: poison-pill fetch does one XRANGE call per ID. Fine for typical max_deliveries counts (< 10); would benefit from pipeline for very large poison batches.