Install & Compatibility
Where this runs
tested against v3.0.1 · 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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.506s · 23.7MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.1s · import 0.450s · 24MB
22MB installed
● package 22MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
RedisDict
✓ from pottery import RedisDict
RedisList
✓ from pottery import RedisList
RedisDeque
✓ from pottery import RedisDeque
RedisSet
✓ from pottery import RedisSet
RedisCounter
✓ from pottery import RedisCounter
RedisSimpleQueue
✓ from pottery import RedisSimpleQueue
Redlock
✓ from pottery import Redlock
AIORedlock
✓ from pottery import AIORedlock
NextID
✓ from pottery import NextID
AIONextID
✓ from pottery import AIONextID
redis_cache
✓ from pottery import redis_cache
BloomFilter
✓ from pottery import BloomFilter
This quickstart demonstrates how to connect to Redis and use `Pottery`'s `RedisDict` which behaves like a standard Python dictionary but is backed by Redis. It covers initialization, adding, accessing, and deleting elements.
import os
from redis import Redis
from pottery import RedisDict
# Ensure Redis is running, e.g., via Docker: docker run -p 6379:6379 redis
# For demonstration, we connect to a local Redis instance.
# In production, use environment variables for Redis URL.
redis_url = os.environ.get('REDIS_URL', 'redis://localhost:6379/1')
redis = Redis.from_url(redis_url)
# Create a Redis-backed dictionary
tel = RedisDict({'jack': 4098, 'sape': 4139}, redis=redis, key='telephone_book')
# Use it like a regular Python dictionary
tel['guido'] = 4127
print(f"Current telephone book: {tel}")
print(f"Jack's number: {tel['jack']}")
del tel['sape']
print(f"After deleting sape: {tel}")
# Check if a key exists
print(f"'guido' in tel: {'guido' in tel}")
# Clean up (optional for quickstart)
redis.delete('telephone_book')
Debug
Known issues
breakingIn version 3.0.0, the `Redlock` class changed its time unit consistency. The `auto_release_time` argument and the return value of `Redlock.locked()` are now in seconds, whereas they were previously in milliseconds.fixUpdate any code using `Redlock` to pass and interpret time values in seconds instead of milliseconds. For example, `auto_release_time=10000` (10 seconds) should now be `auto_release_time=10`.
affects: >=3.0.0
gotchaPottery's Redis-backed data structures (e.g., `RedisDict`, `RedisList`, `RedisSet`) require all keys and values to be JSON serializable. Non-serializable objects will raise errors.fixEnsure all data stored in Pottery's Redis containers can be serialized to and deserialized from JSON. Use custom serialization if complex objects are necessary.
affects: All versions
gotchaVersion 3.0.1 introduced warnings for O(n) operations on Redis-backed containers. While Python's built-in `list` has O(1) indexed access, `RedisList` has O(n) access by index, which can lead to performance bottlenecks if not considered.fixBe mindful of performance characteristics when using `RedisList`. For frequent indexed access, consider alternative Redis structures or Python's `collections.deque` if first/last element access is primary, which `RedisDeque` mirrors effectively.
affects: >=3.0.1
gotchaThe comparison behavior (`==`) for `RedisDeque` and `RedisList` was adjusted in versions 2.3.3-2.3.5 to align more closely with Python's native `collections.deque` and `list` behavior, preventing unexpected equality between different Redis-backed types or with Python native types. Earlier versions might have returned `True` for `RedisDeque(...) == RedisList(...)` even if they refer to the same Redis key.fixAlways explicitly compare the `key` and `redis` client instance if you intend to check if two Pottery objects refer to the same underlying Redis resource, rather than relying solely on object equality, especially across different types or Redis instances.
affects: All versions prior to 2.3.6 (fixed in 2.3.3-2.3.5)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pottery'
The 'pottery' library is not installed in your current Python environment, or the Python interpreter cannot find it in its search paths.
fixYou need to install the library using pip: `pip install pottery`
AttributeError: 'dict' object has no attribute 'startswith'
This error typically occurs when you pass a dictionary as the `key` argument to a `pottery` Redis data structure (like `RedisDict`), instead of providing a string representing the Redis key name.
fixThe `key` argument should be a string that names the Redis key for the data structure, not the initial data. Initial data should be passed as the first positional argument. Example: `RedisDict({'item1': 'value1'}, redis=redis_client, key='my_redis_dict_key')` pottery.exceptions.KeyExistsError: <key_name>
You are attempting to instantiate a `pottery` Redis data structure (e.g., `RedisDict`) with a `key` that already exists in Redis, and `pottery` prevents overwriting it by default to avoid accidental data loss.
fixTo fix this, you can either ensure the key does not exist before instantiation (e.g., `redis_client.delete('my_key_name')`) or retrieve the existing instance if you intend to work with it. If you explicitly want to overwrite, you would typically delete the key first or handle the data within the existing structure. redis.exceptions.ConnectionError: Error 111 connecting to localhost:6379. Connection refused.
Your application failed to connect to the Redis server. This usually means the Redis server is not running, is running on a different host or port, or a firewall is blocking the connection.
fixEnsure the Redis server is running and accessible from your application's environment on the specified host and port (default is `localhost:6379`). You may need to start the Redis server, check its configuration (e.g., `redis.conf`), or adjust firewall rules. For example, `redis-cli ping` can test connectivity.
Upgrade
Version history
3.0.1latest on PyPI · released Mar 21, 2025
Audit
Dependencies
redisrequiredPottery is a wrapper library for Redis, requiring a Redis client like `redis-py` (installed as `redis`) for communication with Redis servers.