{"id":6412,"library":"pottery","title":"Pottery","description":"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.","status":"active","version":"3.0.1","language":"en","source_language":"en","source_url":"https://github.com/brainix/pottery","tags":["Redis","data structures","distributed locks","caching","asyncio","queues"],"install":[{"cmd":"pip install pottery","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Pottery is a wrapper library for Redis, requiring a Redis client like `redis-py` (installed as `redis`) for communication with Redis servers.","package":"redis"}],"imports":[{"symbol":"RedisDict","correct":"from pottery import RedisDict"},{"symbol":"RedisList","correct":"from pottery import RedisList"},{"symbol":"RedisDeque","correct":"from pottery import RedisDeque"},{"symbol":"RedisSet","correct":"from pottery import RedisSet"},{"symbol":"RedisCounter","correct":"from pottery import RedisCounter"},{"symbol":"RedisSimpleQueue","correct":"from pottery import RedisSimpleQueue"},{"symbol":"Redlock","correct":"from pottery import Redlock"},{"symbol":"AIORedlock","correct":"from pottery import AIORedlock"},{"symbol":"NextID","correct":"from pottery import NextID"},{"symbol":"AIONextID","correct":"from pottery import AIONextID"},{"symbol":"redis_cache","correct":"from pottery import redis_cache"},{"symbol":"BloomFilter","correct":"from pottery import BloomFilter"}],"quickstart":{"code":"import os\nfrom redis import Redis\nfrom pottery import RedisDict\n\n# Ensure Redis is running, e.g., via Docker: docker run -p 6379:6379 redis\n# For demonstration, we connect to a local Redis instance.\n# In production, use environment variables for Redis URL.\nredis_url = os.environ.get('REDIS_URL', 'redis://localhost:6379/1')\nredis = Redis.from_url(redis_url)\n\n# Create a Redis-backed dictionary\ntel = RedisDict({'jack': 4098, 'sape': 4139}, redis=redis, key='telephone_book')\n\n# Use it like a regular Python dictionary\ntel['guido'] = 4127\nprint(f\"Current telephone book: {tel}\")\nprint(f\"Jack's number: {tel['jack']}\")\n\ndel tel['sape']\nprint(f\"After deleting sape: {tel}\")\n\n# Check if a key exists\nprint(f\"'guido' in tel: {'guido' in tel}\")\n\n# Clean up (optional for quickstart)\nredis.delete('telephone_book')","lang":"python","description":"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."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.0.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions prior to 2.3.6 (fixed in 2.3.3-2.3.5)"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}