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 any number of key-value pairs via an indexed key. 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.redisstore.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', org='kivy')
store.put('tshirtman', name='Gabriel', age=27)

# using the same index key erases all previously added key-value pairs
store.put('tito', name='Mathieu', age=30)

# get a value using a index key and key
print('tito is', store.get('tito')['age'])

# or guess the key/entry for a part of the key
for item in store.find(name='Gabriel'):
    print('tshirtmans index key is', item[0])
    print('his key value pairs are', str(item[1]))

Because the data is persistent, you can check later to see if the key exists:

from kivy.storage.jsonstore import JsonStore

store = JsonStore('hello.json')
if store.exists('tito'):
    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, result):
    print('the key', key, 'has a value of', result)
mystore.get('plop', callback=my_callback)

The callback signature (for almost all methods) is:

def callback(store, key, result):
    """
    store: the `Store` instance currently used.
    key: the key sought for.
    result: 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)¶

Bases: kivy.event.EventDispatcher

Abstract class used to implement a Store

async_clear(callback)¶: Asynchronous version of clear().

async_count(callback)¶: Asynchronously return the number of entries in the storage.

async_delete(callback, key)¶

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)¶

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)¶

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)¶

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_keys(callback)¶: Asynchronously return all the keys in the storage.

async_put(callback, key, **values)¶

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.

clear()¶: Wipe the whole storage.

count()¶: Return the number of entries in the storage.

delete(key)¶: Delete a key from the storage. If the key is not found, a KeyError exception will be thrown.

exists(key)¶: Check if a key exists in the store.

find(**filters)¶

Return all the entries matching the filters. The entries are returned through a generator as a list of (key, entry) pairs where entry is a dict of key-value pairs

for key, entry in store.find(name='Mathieu'):
    print('key:', key, ', entry:', entry)

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')))

get(key)¶: Get the key-value pairs stored at key. If the key is not found, a KeyError exception will be thrown.

keys()¶: Return a list of all the keys in the storage.

put(key, **values)¶: Put new key-value pairs (given in values) into the storage. Any existing key-value pairs will be removed.

« UrlRequest

Dictionary store »

Version

Quick search

Table Of Contents

Storage¶

Usage¶

Examples¶

Synchronous / Asynchronous API¶

Synchronous container type¶