{"id":10346,"library":"walrus","title":"walrus: Redis Utilities","description":"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.","status":"active","version":"0.9.8","language":"en","source_language":"en","source_url":"https://github.com/coleifer/walrus","tags":["redis","database","utilities","data structures","cache","full-text search","streams"],"install":[{"cmd":"pip install walrus","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"walrus 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.","package":"redis-py","optional":false}],"imports":[{"note":"walrus is designed to be used by importing specific classes like Database, not the top-level module directly.","wrong":"import walrus","symbol":"Database","correct":"from walrus import Database"}],"quickstart":{"code":"from walrus import Database\n\n# Connect to Redis (defaults to localhost:6379, db=0)\ndb = Database(\n    host=os.environ.get('REDIS_HOST', 'localhost'),\n    port=int(os.environ.get('REDIS_PORT', 6379)),\n    db=int(os.environ.get('REDIS_DB', 0))\n)\n\n# Use a Hash\nuser_data = db.Hash('user:123')\nuser_data['name'] = 'Alice'\nuser_data['email'] = 'alice@example.com'\nprint(f\"User name: {user_data['name']}\")\n\n# Use a Set\ntags = db.Set('post:tags:my-post')\ntags.add('python', 'redis', 'tutorial')\nprint(f\"Post tags: {list(tags)}\")\n\n# Use a Cache\n@db.cache.cached()\ndef get_expensive_data(key):\n    print(f\"Fetching data for {key}...\")\n    return {'value': key.upper(), 'timestamp': 'now'}\n\nprint(get_expensive_data('test'))\nprint(get_expensive_data('test')) # This call will be cached\n","lang":"python","description":"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."},"warnings":[{"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+.","message":"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.","severity":"breaking","affected_versions":"<0.9.0"},{"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'`).","message":"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.","severity":"breaking","affected_versions":"<0.7.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"<0.8.2"},{"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).","message":"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.","severity":"gotcha","affected_versions":"<0.9.1"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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`.","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.","error":"AttributeError: 'Redis' object has no attribute 'xpending_range'"},{"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')`.","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.","error":"TypeError: __init__() missing 1 required positional argument: 'db'"},{"fix":"Upgrade your `redis-py` dependency to version 3.0 or newer: `pip install --upgrade 'redis>=3.0'`.","cause":"You are trying to use Redis Stream features with an older `redis-py` version (less than 3.0), which does not support Streams.","error":"walrus.exceptions.WalrusException: Stream requires redis-py 3.0 or newer."}]}