Quick search

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:

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_clear(callback)[source]

Asynchronous version of clear().

async_count(callback)[source]

Asynchronously return the number of entries in the storage

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_keys(callback)[source]

Asynchronously return all the keys in the storage

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.

clear()[source]

Wipe the whole storage.

count()[source]

Return the number of entries in the storage

delete(key)[source]

Delete a key from the storage. If the key is not found, a KeyError exception will be thrown.

exists(key)[source]

Check if a key exist in the store.

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')))
get(key)[source]

Get the value stored at key. If the key is not found, a KeyError exception will be thrown.

keys()[source]

Return a list of all the keys in the storage

put(key, **values)[source]

Put a new key/value in the storage