py-redis (Redis Client Wrapper)

1.1.1 · active · verified Thu Apr 16

py-redis is a convenience wrapper for the official `redis-py` package, simplifying Redis client instantiation. It allows configuring the client via environment variables (REDIS_HOST, REDIS_PORT, REDIS_DB, REDIS_PASSWORD) and provides a single function to get a pre-configured `redis.Redis` instance. The current version is 1.1.1, and its release cadence is infrequent as it primarily provides a thin stable wrapper.

Common errors

```
ModuleNotFoundError: No module named 'pyredis'
```
cause The `py-redis` package is not installed in the current Python environment.

fix pip install py-redis
```
redis.exceptions.ConnectionError: Error 111 connecting to localhost:6379. Connection refused.
```
cause The Redis server is either not running, not accessible from the current machine, or configured on a different host/port than specified.

fix Ensure your Redis server is running and accessible. Verify the host, port, and password provided to `get_redis_client()` or set in environment variables (`REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`) are correct.
```
TypeError: Object of type bytes is not JSON serializable
```
cause You retrieved data from Redis that is still in `bytes` format (because `decode_responses=False` or was omitted), but you're trying to use it where a string is expected (e.g., `json.loads()`).

fix Pass `decode_responses=True` to `get_redis_client()` to automatically decode Redis responses into strings, or manually decode the byte strings using `.decode('utf-8')` after retrieval.
```
ModuleNotFoundError: No module named 'redis'
```
cause The core `redis-py` library, which `py-redis` depends on, is not installed.

fix pip install redis (This is usually handled automatically when `py-redis` is installed, but can occur if dependencies are manipulated or if `py-redis` was installed with `--no-deps`.)

Warnings

gotcha Parameters passed directly to `get_redis_client()` will override any corresponding environment variables (e.g., `REDIS_HOST`, `REDIS_PORT`). Ensure your explicit arguments align with or intentionally override your environment setup.
Fix: Explicitly check both environment variables and `get_redis_client` call arguments to understand the final configuration applied.
gotcha By default, `redis-py` (and thus `py-redis` if `decode_responses` is not set) returns byte strings. If you omit `decode_responses=True`, you'll receive bytes, which can lead to `TypeError` when expecting strings (e.g., in JSON serialization).
Fix: Always explicitly set `decode_responses=True` in `get_redis_client()` if you expect Python strings, or manually decode the byte strings using `.decode('utf-8')` after retrieval.
gotcha As `py-redis` is a thin wrapper around `redis-py`, breaking changes or deprecations in the underlying `redis-py` library (which `py-redis` depends on) can indirectly affect your application, especially if `redis-py` itself is updated.
Fix: Refer to `redis-py`'s changelog for major version updates. Ensure your `redis-py` dependency (either explicit or through `py-redis`'s requirements) is stable and compatible with your `py-redis` version.

Install

pip install py-redis Install py-redis

Imports

get_redis_client
wrong:
```
from redis import Redis
```
correct:
```
from pyredis import get_redis_client
```
While `py-redis` wraps `redis-py`, you should use `get_redis_client` to leverage its environment variable configuration and default settings, rather than directly importing `Redis` from `redis`.

Quickstart

This quickstart demonstrates how to get a Redis client using `get_redis_client`, leveraging environment variables for configuration. It then performs a basic `set` and `get` operation, ensuring `decode_responses=True` for string handling.

import os
from pyredis import get_redis_client

# Configure Redis connection via environment variables for robustness
# Example: REDIS_HOST=localhost REDIS_PORT=6379 REDIS_DB=0 REDIS_PASSWORD=""

# Fallback to defaults if env vars are not set
redis_host = os.environ.get('REDIS_HOST', 'localhost')
redis_port = int(os.environ.get('REDIS_PORT', '6379'))
redis_db = int(os.environ.get('REDIS_DB', '0'))
redis_password = os.environ.get('REDIS_PASSWORD') or None

try:
    # Get a configured Redis client instance
    # decode_responses=True is highly recommended for working with strings
    redis_client = get_redis_client(
        host=redis_host,
        port=redis_port,
        db=redis_db,
        password=redis_password,
        decode_responses=True
    )

    # Test the connection
    redis_client.ping()
    print("Successfully connected to Redis!")

    # Perform a simple operation
    redis_client.set('mykey', 'Hello, py-redis!')
    value = redis_client.get('mykey')
    print(f"Retrieved from Redis: {value}")

    redis_client.delete('mykey') # Clean up

except Exception as e:
    print(f"Could not connect to Redis or an error occurred: {e}")
    print("Please ensure Redis server is running and connection details are correct.")

view raw JSON →