walrus: Redis Utilities

0.9.8 · active · verified Fri Apr 17

walrus is a Python library providing a set of high-level utilities and abstractions for working with Redis. It offers an object-oriented interface to Redis data structures, including hashes, lists, sets, streams, and also provides features like caching, full-text search, and a graph API. The current version is 0.9.8, with releases occurring periodically, often in response to changes in its underlying `redis-py` dependency.

Common errors

```
AttributeError: 'Redis' object has no attribute 'xpending_range'
```
cause You are likely running an older version of walrus (<0.9.0) with a newer `redis-py` library which has changed the `xpending_range` signature, or vice versa.

fix Upgrade walrus to 0.9.0 or newer to ensure compatibility with `redis-py`'s stream APIs: `pip install --upgrade walrus`. Also ensure `redis-py` is updated: `pip install --upgrade redis`.
```
TypeError: __init__() missing 1 required positional argument: 'db'
```
cause This usually happens when trying to instantiate a walrus data structure (e.g., `Hash`, `Set`) without passing the `Database` instance as the first argument.

fix Always pass your `Database` instance (`db`) to walrus container constructors, e.g., `my_hash = db.Hash('my-key')` instead of `my_hash = Hash('my-key')`.
```
walrus.exceptions.WalrusException: Stream requires redis-py 3.0 or newer.
```
cause You are trying to use Redis Stream features with an older `redis-py` version (less than 3.0), which does not support Streams.

fix Upgrade your `redis-py` dependency to version 3.0 or newer: `pip install --upgrade 'redis>=3.0'`.

Warnings

breaking walrus 0.9.0 introduced a backwards-incompatible change due to `redis-py` altering the signature of its `xpending_range` function. If you are using Redis streams and consumer groups, this update is critical.
Fix: Upgrade walrus to 0.9.0 or newer: `pip install --upgrade walrus`. Ensure your `redis-py` version is compatible with walrus 0.9.0+.
breaking walrus 0.7.0 introduced a dependency on `redis-py` 3.0 or newer. While walrus aims to abstract these changes, direct interaction with `redis-py` commands might require adjustments if upgrading from older `redis-py` versions.
Fix: Upgrade walrus to 0.7.0 or newer: `pip install --upgrade walrus`. If you experience issues, verify your `redis-py` version is 3.0+ (e.g., `pip install 'redis>=3.0'`).
gotcha walrus 0.8.2 transitioned from `HMSET` to `HSET` internally for hash operations, aligning with `redis-py` and Redis server deprecations. While walrus handles this, if you are mixing direct `redis-py` calls with walrus, be aware of the `HMSET` deprecation.
Fix: Upgrade walrus to 0.8.2 or newer: `pip install --upgrade walrus`. When interacting with `redis-py` directly for hash operations, prefer `HSET` over `HMSET`.
gotcha Prior to 0.9.1, `cached` decorators would not cache calls that returned `None`. This behavior changed, so now functions returning `None` are also cached.
Fix: If your application relies on `None` results *not* being cached, you may need to adjust your caching logic or upgrade to 0.9.1+ and implement custom handling for `None` results if the new behavior is problematic. Check `db.cache.cached` options for `ignore_none` or similar parameters if available (though not explicitly mentioned in docs).

Install

pip install walrus Install latest version

Imports

Database
wrong:
```
import walrus
```
correct:
```
from walrus import Database
```
walrus is designed to be used by importing specific classes like Database, not the top-level module directly.

Quickstart

This quickstart demonstrates connecting to a Redis instance and utilizing some of walrus's core features: a Hash for storing structured data, a Set for unique items, and a cached decorator for expensive function calls. Environment variables are used for Redis connection details for robustness.

from walrus import Database

# Connect to Redis (defaults to localhost:6379, db=0)
db = Database(
    host=os.environ.get('REDIS_HOST', 'localhost'),
    port=int(os.environ.get('REDIS_PORT', 6379)),
    db=int(os.environ.get('REDIS_DB', 0))
)

# Use a Hash
user_data = db.Hash('user:123')
user_data['name'] = 'Alice'
user_data['email'] = 'alice@example.com'
print(f"User name: {user_data['name']}")

# Use a Set
tags = db.Set('post:tags:my-post')
tags.add('python', 'redis', 'tutorial')
print(f"Post tags: {list(tags)}")

# Use a Cache
@db.cache.cached()
def get_expensive_data(key):
    print(f"Fetching data for {key}...")
    return {'value': key.upper(), 'timestamp': 'now'}

print(get_expensive_data('test'))
print(get_expensive_data('test')) # This call will be cached

view raw JSON →