Examples¶

Basic usage¶

All collections can be imported from the top-level redis_collections package. For example, to use a Redis-backed version of Python’s dict, import Dict and use it just like you would its Python counterpart:

>>> from redis_collections import Dict

>>> D = Dict()
>>> D['answer'] = 42  # Store an item on the Redis server
>>> D['answer']  # Retrieve an item from the Redis server
42

To use a dictionary that pushes its least recently used items to Redis, import LRUDict and use it like a normal dict:

>>> from redis_collections import LRUDict

>>> lru_dict = LRUDict(maxsize=2)
>>> lru_dict.update([('a', 1), ('b', 2), ('c', 3), ('d', 4)])
>>> lru_dict['b']  # Most recently used key is now 'b'
1
>>> lru_dict['c'] = -2  # Most recently used key is now 'c'
>>> lru_duct['e'] = 5  # 'e' pushes 'b' to Redis

Standard collections¶

This package provides several collections that emulate built-in Python types and classes from the collections module.

Collection	Python type	Redis type
`Dict`	`dict`	Hash
`List`	`list`	List
`Set`	`set`	Set
`Counter`	`Counter`	Hash
`DefaultDict`	`defaultdict`	Hash
`Deque`	`deque`	List

Use each one as you would the standard version:

>>> from redis_collections import List, Set

>>> L = List(key='test-list')
>>> L.append('one')
>>> L.extend(['two', 'three'])
>>> L[:-1]
['one', 'two']

>>> S = Set(key='test-set')
>>> S.add('a')
>>> S.add('a')
>>> S.add('b')
>>> len(S)
2

Data is stored and retrieved in Redis, so if the Python process with a collection terminates, you can re-load it in another process.

Syncable collections¶

The standard Redis collections write to and read from Redis for all operations. This means that all changes made in a Python process are reflected in Redis, and that a collection made by one Python process can be accessed by another Python process. However, this also means that all read and write operations are fairly slow, since they have to retrieve data from and write data to Redis.

The syncable collections in this package provide types whose contents are kept in memory. When their sync method is called those contents are written to Redis:

>>> from redis_collections import SyncableDict

>>> D = SyncableDict()
>>> D['a'] = 1  # No write to Redis
>>> D['a'] += 1  # No read from or write to Redis
>>> D.sync()  # Contents are written to Redis

These collections can also be used with a with block for automatic synchronization:

>>> with SyncableDict() as D:
...     D['a'] = 1
...     D['a'] += 1
>>> D['a']  # Contents were written to Redis at the end of the with block
2

If the Python process with a collection terminates, un-synchronized data won’t be available in Redis.

Other collections¶

Least recently used dictionary¶

The standard collections do their processing in Redis (at the expense of speed) and the syncable collections do their processing in Python (at the expense of automatic persistence).

The LRUDict collection provides a compromise. Recently used items are stored in memory; older items are pushed to Redis:

>>> from redis_collections import LRUDict

>>> D = LRUDict(maxsize=2)
>>> D['a'] = 1
>>> D['b'] = 2
>>> D['c'] = 2  # 'a' is pushed to Redis and 'c' is stored locally
>>> D['a']  # 'b' is pushed to Redis and 'a' is retrieved for local storage
1
>>> D.sync()  # All items are copied to Redis

See the API Docs for LRUDict for more details.

Sorted Set counter¶

The standard and syncable collections allow for access to Redis data types through corresponding Python data types. However, there are Redis data types that don’t have an analog in Python.

The SortedSetCounter provides access to the Redis Sorted Set type. Its API doesn’t emulate any Python type’s, but should be easy for Python users to understand and use:

>>> from redis_collections import SortedSetCounter

>>> ssc = SortedSetCounter([('earth', 300), ('mercury', 100)])
>>> ssc.set_score('venus', 200)
>>> ssc.get_score('venus')
200.0
>>> ssc.items()
[('mercury', 100.0), ('venus', 200.0), ('earth', 300.0)]

See the API Docs for SortedSetCounter for more details.