Table Of Contents
Storage¶
New in version 1.7.0.
Warning
This module is still experimental, and the API is subject to change in a future version.
Usage¶
The idea behind the Storage module is to be able to load/store keys-value pairs. The default model is abstract so you cannot use it directly. We provide some implementations such as:
- kivy.storage.dictstore.DictStore: use a python dict as a store
- kivy.storage.jsonstore.JsonStore: use a JSON file as a store
- kivy.storage.redistore.RedisStore: use a Redis database with redis-py
Examples¶
For example, let’s use a JsonStore:
from kivy.storage.jsonstore import JsonStore
store = JsonStore('hello.json')
# put some values
store.put('tito', name='Mathieu', age=30)
store.put('tshirtman', name='Gabriel', age=27)
# get from a key
print('tito is', store.get('tito'))
# or guess the key/entry for a part of the key
key, tshirtman = store.find(name='Gabriel')
print('tshirtman is', tshirtman)
Because the data is persistant, you can check later to see if the key exists:
from kivy.storage.jsonstore import JsonStore
store = JsonStore('hello.json')
if store.exists('tite'):
print('tite exists:', store.get('tito'))
store.delete('tito')
Synchronous / Asynchronous API¶
All the standard methods (get(), put() , exists(), delete(), find()) have an asynchronous version.
For example, the get method has a callback parameter. If set, the callback will be used to return the result to the user when available: the request will be asynchronous. If the callback is None, then the request will be synchronous and the result will be returned directly.
Without callback (Synchronous API):
entry = mystore.get('tito')
print('tito =', entry)
With callback (Asynchronous API):
def my_callback(store, key, entry):
print('the key', key, 'have', entry)
mystore.get('plop', callback=my_callback)
The callback signature is (for almost all methods) callback(store, key, result):
#. `store` is the `Store` instance currently used.
#. `key` is the key to search for.
#. `entry` is the result of the lookup for the `key`.
Synchronous container type¶
The storage API emulates the container type for the synchronous API:
store = JsonStore('hello.json')
# original: store.get('tito')
store['tito']
# original: store.put('tito', name='Mathieu')
store['tito'] = {'name': 'Mathieu'}
# original: store.delete('tito')
del store['tito']
# original: store.count()
len(store)
# original: store.exists('tito')
'tito' in store
# original: for key in store.keys()
for key in store:
pass
- class kivy.storage.AbstractStore(**kwargs)[source]¶
Bases: kivy.event.EventDispatcher
Abstract class used to implement a Store
- async_delete(callback, key)[source]¶
Asynchronous version of delete().
Callback arguments: - store: AbstractStore instance
Store instance
- key: string
Name of the key to search for
- result: bool
Indicate True if the storage has been updated, or False if nothing has been done (no changes). None if any error.
- async_exists(callback, key)[source]¶
Asynchronous version of exists().
Callback arguments: - store: AbstractStore instance
Store instance
- key: string
Name of the key to search for
- result: boo
Result of the query, None if any error
- async_find(callback, **filters)[source]¶
Asynchronous version of find().
The callback will be called for each entry in the result.
Callback arguments: - store: AbstractStore instance
Store instance
- key: string
Name of the key to search for, or None if we reach the end of the results
- result: bool
Indicate True if the storage has been updated, or False if nothing has been done (no changes). None if any error.
- async_get(callback, key)[source]¶
Asynchronous version of get().
Callback arguments: - store: AbstractStore instance
Store instance
- key: string
Name of the key to search for
- result: dict
Result of the query, None if any error
- async_put(callback, key, **values)[source]¶
Asynchronous version of put().
Callback arguments: - store: AbstractStore instance
Store instance
- key: string
Name of the key to search for
- result: bool
Indicate True if the storage has been updated, or False if nothing has been done (no changes). None if any error.
- delete(key)[source]¶
Delete a key from the storage. If the key is not found, a KeyError exception will be thrown.
- find(**filters)[source]¶
Return all the entries matching the filters. The entries are given through a generator as a list of (key, entry) pairs:
for key, entry in store.find(name='Mathieu'): print('entry:', key, '->', value)
Because it’s a generator, you cannot directly use it as a list. You can do:
# get all the (key, entry) availables entries = list(store.find(name='Mathieu')) # get only the entry from (key, entry) entries = list((x[1] for x in store.find(name='Mathieu')))