walrus

library0.9.8pypypi✓ verified 86d ago

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.

database serialization observability

pip install walrus

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · WALRUS

walrus

databasepythonv0.9.8

Install

1.9s avg

Import

455ms

Disk

22MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.9.8 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.483s · 23.3MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 1.9s · import 0.427s · 24MB

22MB installed

● package 22MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Database

✓ from walrus import Database

✗ import walrus

walrus is designed to be used by importing specific classes like Database, not the top-level module directly.

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

Debug

Known issues

breakingwalrus 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+.

affects: <0.9.0

breakingwalrus 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'`).

affects: <0.7.0

gotchawalrus 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`.

affects: <0.8.2

gotchaPrior 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).

affects: <0.9.1

Errors

Common errors & fixes

AttributeError: 'Redis' object has no attribute 'xpending_range'

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'

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.

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'`.

Upgrade

Version history

0.9.8latest on PyPI · released Jan 15, 2026

Audit

Dependencies

redis-pyrequiredwalrus is built on top of redis-py and requires version 3.0 or newer. Specific walrus versions may require specific redis-py versions due to API changes.

Agent activity

36 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/coleifer/walrus ↗

packagehttps://pypi.org/project/walrus/ ↗

homepagehttps://walrus.readthedocs.io ↗

docshttps://walrus.readthedocs.io/ ↗

changeloghttps://github.com/coleifer/walrus/blob/master/CHANGELOG.md ↗