vinegar.utils.sqlite_store

Data store used by the sqlite data source.

This data store uses the sqlite3 package for accessing a database file that stores information associated with systems.

The data store provided by this module is primarily intended to serve as the backend of the sqlite data source. This means that the storage structure used by this data store has been designed with that use in mind and is probably not very useful for other applications.

However, it is still provided by a separate package because other modules might find it useful to be able to access and modify the database used by a data source.

The data store is implemented in a way, so that it is safe to access the same database concurrently from multiple threads or even processes. This means that many DataStore instances may be created for the same database file and that a single DataStore instance may be shared by different threads.

A DataStore instance is created by calling open_data_store.

class vinegar.utils.sqlite_store.DataStore(db_file: str, strict_value_checking=True)

Data store that is backed by an SQLite database.

When a program is done with using an instance of this class, it should call its close method. Alternatively, an instance of this class can be used as a context manager like in the following example:

with open_data_store(db_file) as data_store:
    data_store.set_value('system_id', 'key', 'value')
    print(data_store.get_data('system_id'))

Instances of this class are safe for use by multiple threads.

close() → None

Close this data store. This closes the underlying database connection.

A data store should be closed when it is not going to be used any longer.

Using the data store after closing it will result in an exception being raised.

delete_data(system_id: str) → None

Delete all data associated with a system ID.

Parameters:

system_id – system_id for which all data (all keys) shall be deleted.

delete_value(system_id: str, key: str) → None

Delete data associated with a system ID and a specific key.

Parameters:

  • system_id – system_id for which the piece of data identified by key shall be deleted.

  • key – key which shall be deleted. Data stored under different keys is not affected by this operation.

find_systems(key: str, value: Any) → Sequence

Find system IDs associated with a certain key value pair.

This returns those system IDs for which the specified key has the specified value.

Parameters:

  • key – key that shall be tested.

  • value – data that is expected for the specified key. A system is only included in the returned list if the data stored for it under the specified key matches this value.

Returns:

list of system IDs that match the predicate.

get_data(system_id: str) → Mapping[str, Any]

Return all data associated with a specific system ID.

The data is returned as a dict where each key is one of the keys that has been stored for the system and each value is the value stored for that key.

If there is no data for the specified system ID, an empty dict is returned.

Parameters:

system_id – system ID of the system for which the data shall be retrieved.

Returns:

dictionary containing all data for the specified system ID.

get_value(system_id: str, key: str) → Any

Return the value associated with a specific system ID and key.

If the specified key does not exist for the specified system ID, a KeyError is raised.

Parameters:

  • system_id – system_id for which the piece of data identified by key shall be retrieved.

  • key – key for which the value shall be retrieved.

Returns:

value associated with the specified system ID and key.

list_systems() → Sequence[str]

Return a list of all system IDs.

The returned list contains every system ID for which at least one piece of data is stored.

Returns:

list of system IDs that are known by this data store.

set_value(system_id: str, key: str, value: Any) → None

Store a value for the specified system ID and key.

The data store internally uses JSON to serialize the value, so there are some restrictions on which kind of values are supported.

In general, only objects that can be serialized by json.dumps are supported. In particular, passing an object that has a circular reference (e.g. a dict that refers back to itself through one of its values) results in a ValueError being raised. Passing another kind of object that cannot be serialized by json.dumps results in a TypeError being raised.

If the strict_value_checking option is enabled for this data store (see open_data_store) some additional checks apply. JSON natively only supports the elementary data types bool, float, int and str as well as list and dict instances using these types. The values stored in a list or a dict must also be of one of these types. The keys of a dict are further constrained: They must be instances of str. In additon to the aforementioned types, the special value None is also supported (but not as a dict key).

Enforcing these limitations has the advantage that values will be deserialized to their original representations. For example, json.dumps supports serializing a dict that has int keys, but those keys will be instances of str when deserializing the dict again. Similar considerations apply to instances of tuple and set: json.dumps could serialize those, but they would be implicitly converted to instances of list.

For those reasons, keeping strict_value_checking set to True is recommended. There is a small but mostly insignificant performance benefit in disabling strict_value_checking. Therefore, code that knows that it only passes conforming values might want to choose to disable the check.

Parameters:

  • system_id – system_id for which the value shall be stored.

  • key – key for which the value shall be stored.

  • value – value that shall be stored.

vinegar.utils.sqlite_store.open_data_store(db_file: str, strict_value_checking=True) → DataStore

Open a data store that is backed by the specified database file. If the database file does not exist yet, create it.

The strict_value_checking option controls the behavior of the set_value method. If the option is set to True (the default), set_value raises an exception if the specified value cannot be safely serialized as JSON (see that method for details about which types can be serialized safely).

A data store that has been created should be closed when it is not needed any longer by calling its close method. This ensures that resources associated with the database connection are released immediately instead of when the data store object is eventually garbage collected.

The object returned by this function can be used as a context manager to simplify resource management. Please refer to the class documentation of DataStore for an example.

Parameters:

  • db_file – path to the database file that stores the catual data.

  • strict_value_checking – True if inserted values shall be checked strictly, False if the checks shall be more relaxed. See set_value for details.

Returns:

data store backed by db_file.