pottery

Redlock provides a safe and reliable lock to coordinate access to resources shared across threads, processes, and machines using Redis. It implements the Python threading.Lock API.

Best Practices:

• Instantiate per use: It is safest to instantiate a new Redlock object every time you need to protect a resource rather than sharing instances. Use the key to identify the resource.
• Avoid single points of failure: In production, use 5 Redis masters so the lock remains available even if 2 masters are lost.
• Manage timeouts: Locks are automatically released to prevent deadlocks. Ensure your critical section completes well within the auto_release_time (default is 10 seconds).

Install the pottery package using pip3 to access Pythonic Redis containers and resilience patterns.

$ pip3 install pottery

Before using Pottery containers, you must set up a standard Redis client (e.g., using the redis-py library).

from redis import Redis
redis = Redis.from_url('redis://localhost:6379/1')

RedisList is a Redis-backed container compatible with Python's list.

Initialization:

• redis: Your Redis client instance.
• key: The Redis key name for the list.

Limitations:

• Elements must be JSON serializable.
• Performance Note: Under the hood, Redis implements lists as doubly linked lists. While inserting at the head or tail is fast (O(1)), accessing elements by index is slow (O(n)). For better performance with index-based access, consider using RedisDeque instead.

from pottery import RedisList
squares = RedisList([1, 4, 9, 16, 25], redis=redis, key='squares')

# Standard list operations
print(squares[0])       # 1
print(squares[-1])      # 25
squares.append(36)

RedisCounter is a Redis-backed container compatible with Python's collections.Counter.

Initialization:

• redis: Your Redis client instance.
• key: The Redis key name for the counter.
• Optional keyword arguments (e.g., a=4, b=2) to initialize counts.

Limitations:

• Keys must be JSON serializable.

from pottery import RedisCounter
from collections import Counter

c = RedisCounter(redis=redis, key='my-counter', a=4, b=2, c=0, d=-2)

# Standard Counter operations
print(c.most_common(3))

# Subtracting another Counter
d = Counter(a=1, b=2, c=3, d=4)
c.subtract(d)
# c is now RedisCounter{'a': 3, 'b': 0, 'c': -3, 'd': -6}

ContextTimer is a utility to measure wall (real-world) time. The .elapsed() method returns the time in milliseconds.

You can use it in two ways:

1. Stand-alone: Manually call .start() and .stop().
2. Context Manager: Use the with statement to automatically manage the timer lifecycle.

import time
from pottery import ContextTimer

# Stand-alone usage
timer = ContextTimer()
timer.start()
time.sleep(0.1)
print(timer.elapsed()) # Returns time in ms
timer.stop()

# Context manager usage
with ContextTimer() as timer:
    time.sleep(0.1)
    print(timer.elapsed())

RedisDeque is a Redis-backed container compatible with Python's collections.deque. It is optimized for fast head/tail operations.

Initialization:

• redis: Your Redis client instance.
• key: The Redis key name for the deque.

Limitations:

• Elements must be JSON serializable.

from pottery import RedisDeque
d = RedisDeque('ghi', redis=redis, key='letters')

# Standard deque operations
d.append('j')
d.appendleft('f')
d.pop()
d.rotate(1)
d.extendleft('abc')

RedisSet is a Redis-backed container compatible with Python's set.

Initialization:

• redis: Your Redis client instance.
• key: The Redis key name for the set.

Limitations:

• Elements must be JSON serializable.

Efficient Membership Testing: You can use .contains_many(*elements) to perform efficient membership testing for multiple elements at once, returning a tuple of booleans.

from pottery import RedisSet
basket = RedisSet({'apple', 'orange', 'pear'}, redis=redis, key='basket')

# Standard set operations
print('orange' in basket)
print(sorted(basket))

# Bulk membership check
nirvana = RedisSet({'kurt', 'krist', 'dave'}, redis=redis, key='nirvana')
print(nirvana.contains_many('kurt', 'krist', 'chat', 'dave'))
# Output: (True, True, False, True)

RedisDict is a Redis-backed container compatible with Python's dict. It allows you to interact with Redis keys as if they were local dictionaries.

Initialization:

• redis: Your Redis client instance.
• key: The Redis key name for the dictionary.

Limitations:

• Keys and values must be JSON serializable.

from pottery import RedisDict
# Initialize with existing data
tel = RedisDict({'jack': 4098, 'sape': 4139}, redis=redis, key='tel')

# Standard dict operations
tel['guido'] = 4127
print(tel['jack'])  # 4098
del tel['sape']
print('guido' in tel)  # True