Key/Value Store

The playhouse.kv module contains the implementation of a persistentdictionary.

• class KeyValue([key_field=None[, value_field=None[, ordered=False[, database=None[, table_name='keyvalue']]]]])

Parameters:

• key_field (Field) – field to use for key. Defaults toCharField. Must have primary_key=True.
• value_field (Field) – field to use for value. Defaults toPickleField.
• ordered (bool) – data should be returned in key-sorted order.
• database (Database) – database where key/value data is stored. If notspecified, an in-memory SQLite database will be used.
• table_name (str) – table name for data storage.

Dictionary-like API for storing key/value data. Like dictionaries, supportsthe expected APIs, but also has the added capability of acceptingexpressions for getting, setting and deleting items.

Table is created automatically (if it doesn’t exist) when the KeyValueis instantiated.

Uses efficient upsert implementation for setting and updating/overwritingkey/value pairs.

Basic examples:

# Create a key/value store, which uses an in-memory SQLite database
# for data storage.
KV = KeyValue()
 
# Set (or overwrite) the value for "k1".
KV['k1'] = 'v1'
 
# Set (or update) multiple keys at once (uses an efficient upsert).
KV.update(k2='v2', k3='v3')
 
# Getting values works as you'd expect.
assert KV['k2'] == 'v2'
 
# We can also do this:
for value in KV[KV.key > 'k1']:
    print(value)
 
# 'v2'
# 'v3'
 
# Update multiple values at once using expression:
KV[KV.key > 'k1'] = 'vx'
 
# What's stored in the KV?
print(dict(KV))
 
# {'k1': 'v1', 'k2': 'vx', 'k3': 'vx'}
 
# Delete a single item.
del KV['k2']
 
# How many items are stored in the KV?
print(len(KV))
# 2
 
# Delete items that match the given condition.
del KV[KV.key > 'k1']

• contains(expr)

Parameters:expr – a single key or an expressionReturns:Boolean whether key/expression exists.

Example:

>>> kv = KeyValue()
>>> kv.update(k1='v1', k2='v2')
 
>>> 'k1' in kv
True
>>> 'kx' in kv
False
 
>>> (KV.key < 'k2') in KV
True
>>> (KV.key > 'k2') in KV
False

• len()

Returns:Count of items stored.

• getitem(expr)

Parameters:expr – a single key or an expression.Returns:value(s) corresponding to key/expression.Raises:KeyError if single key given and not found.

Examples:

>>> KV = KeyValue()
>>> KV.update(k1='v1', k2='v2', k3='v3')
 
>>> KV['k1']
'v1'
>>> KV['kx']
KeyError: "kx" not found
 
>>> KV[KV.key > 'k1']
['v2', 'v3']
>>> KV[KV.key < 'k1']
[]

• setitem(expr, value)

Parameters:

- **expr** – a single key or an expression.
- **value** – value to set for key(s)

Set value for the given key. If expr is an expression, then anykeys matching the expression will have their value updated.

Example:

>>> KV = KeyValue()
>>> KV.update(k1='v1', k2='v2', k3='v3')
 
>>> KV['k1'] = 'v1-x'
>>> print(KV['k1'])
'v1-x'
 
>>> KV[KV.key >= 'k2'] = 'v99'
>>> dict(KV)
{'k1': 'v1-x', 'k2': 'v99', 'k3': 'v99'}

• delitem(expr)

Parameters:expr – a single key or an expression.

Delete the given key. If an expression is given, delete all keys thatmatch the expression.

Example:

>>> KV = KeyValue()
>>> KV.update(k1=1, k2=2, k3=3)
 
>>> del KV['k1']  # Deletes "k1".
>>> del KV['k1']
KeyError: "k1" does not exist
 
>>> del KV[KV.key > 'k2']  # Deletes "k3".
>>> del KV[KV.key > 'k99']  # Nothing deleted, no keys match.

• keys()

Returns:an iterable of all keys in the table.

• values()

Returns:an iterable of all values in the table.

• items()

Returns:an iterable of all key/value pairs in the table.

• update([__data=None[, **mapping]])
• Efficiently bulk-insert or replace the given key/value pairs.

Example:

>>> KV = KeyValue()
>>> KV.update(k1=1, k2=2)  # Sets 'k1'=1, 'k2'=2.
 
>>> dict(KV)
{'k1': 1, 'k2': 2}
 
>>> KV.update(k2=22, k3=3)  # Updates 'k2'->22, sets 'k3'=3.
 
>>> dict(KV)
{'k1': 1, 'k2': 22, 'k3': 3}
 
>>> KV.update({'k2': -2, 'k4': 4})  # Also can pass a dictionary.
 
>>> dict(KV)
{'k1': 1, 'k2': -2, 'k3': 3, 'k4': 4}

• get(expr[, default=None])

Parameters:

- **expr** – a single key or an expression.
- **default** – default value if key not found.Returns:

value of given key/expr or default if single key not found.

Get the value at the given key. If the key does not exist, the defaultvalue is returned, unless the key is an expression in which case anempty list will be returned.

• pop(expr[, default=Sentinel])

Parameters:

- **expr** – a single key or an expression.
- **default** – default value if key does not exist.Returns:

value of given key/expr or default if single key not found.

Get value and delete the given key. If the key does not exist, thedefault value is returned, unless the key is an expression in whichcase an empty list is returned.

• clear()
• Remove all items from the key-value table.