Pottery

3.0.1 · active · verified Wed Apr 15

Pottery is a Python library that provides Pythonic interfaces to Redis, enabling developers to use Redis data structures and patterns like distributed locks, caches, and queues with familiar Python `dict`, `list`, and `set` semantics. Currently at version 3.0.1, it maintains an active release cadence with frequent updates and bug fixes, supporting modern Python versions.

Warnings

breaking In 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.
Fix: Update 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`.
gotcha Pottery'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.
Fix: Ensure all data stored in Pottery's Redis containers can be serialized to and deserialized from JSON. Use custom serialization if complex objects are necessary.
gotcha Version 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.
Fix: Be 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.
gotcha The 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.
Fix: Always 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.

Install

pip install pottery Install stable version

Imports

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

Quickstart

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')

view raw JSON →