shellbot.stores.base module

class shellbot.stores.base.Store(context=None, **kwargs)

Bases: object

Stores data for one space

This is a key-value store, that supports concurrency across multiple processes.

Configuration of the storage engine is coming from settings of the overall bot.

Example:

store = Store(context=my_context)

Normally a store is related to one single space. For this, you can use the function bond() to set the space unique id.

Example:

store.bond(id=space.id)

Once this is done, the store can be used to remember and to recall values.

Example:

store.remember('gauge', gauge)
...
gauge = store.recall('gauge')

append(key, item)

Appends an item to a list

Parameters:

• key (str) – name of the list
• item (any serializable type is accepted) – a new item to append

Example:

>>>store.append('names', 'Alice')
>>>store.append('names', 'Bob')
>>>store.recall('names')
['Alice', 'Bob']

bond(id=None)

Creates or uses resource required for the permanent back-end

Parameters:id (str) – the unique identifier of the related space

This function should be expanded in sub-class, where necessary.

This function is the right place to create files, databases, and index that can be necessary for a store back-end.

Example:

def bond(self, id=None):
    db.execute("CREATE TABLE ...

check()

Checks configuration

This function should be expanded in sub-class, where necessary.

This function is the right place to check parameters that can be used by this instance.

Example:

def check(self):
    self.context.check(self.prefix+'.db', 'store.db')

decrement(key, delta=1)

Decrements a value

Parameters:

• key (str) – name of the value
• delta (int) – decrement to apply

Returns:

the new value

Example:

value = store.decrement('gauge')

forget(key=None)

Forgets a value or all values

Parameters:key (str) – name of the value to forget, or None

To clear only one value, provides the name of it. For example:

store.forget('parameter_123')

To clear all values in the store, just call the function without a value. For example:

store.forget()

This function is safe on multiprocessing and multithreading.

from_text(textual)

Retrieves a value from a textual representation

Parameters:textual (str) – a textual representation that can be saved in store Returns:a python object Return type:object or None

Here we use json.loads() to do the job. You can override this function in your subclass if needed.

increment(key, delta=1)

Increments a value

Parameters:

• key (str) – name of the value
• delta (int) – increment to apply

Returns:

the new value

Example:

value = store.increment('gauge')

on_init(**kwargs)

Adds processing to initialization

This function should be expanded in sub-class, where necessary.

This function is the right place to capture additional parameters provided on instance initialisation.

Example:

def on_init(self, prefix='sqlite', **kwargs):
    ...

recall(key, default=None)

Recalls a value

Parameters:

• key (str) – name of the value
• default (any serializable type is accepted) – default value

Returns:

the actual value, or the default value, or None

Example:

value = store.recall('parameter_123')

This function is safe on multiprocessing and multithreading.

remember(key, value)

Remembers a value

Parameters:

• key (str) – name of the value
• value (any serializable type is accepted) – actual value

This functions stores or updates a value in the back-end storage system.

Example:

store.remember('parameter_123', 'George')

This function is safe on multiprocessing and multithreading.

to_text(value)

Turns a value to a textual representation

Parameters:value (object) – a python object that can be serialized Returns:a textual representation that can be saved in store Return type:str

Here we use json.dumps() to do the job. You can override this function in your subclass if needed.

update(key, label, item)

Updates a dict

Parameters:

• key (str) – name of the dict
• label (str) – named entry in the dict
• item (any serializable type is accepted) – new value of this entry

Example:

>>>store.update('input', 'PO Number', '1234A')
>>>store.recall('input')
{'PO Number': '1234A'}