taucmdr.cf.storage.sqlite3_file module

Local file backend for SQLite databases.

A persistent, transactional record storage system using sqlite3 for both the database and the key/value store.

class taucmdr.cf.storage.sqlite3_file.SQLiteDatabase(dbfile, storage=None, readonly=False)[source]

Bases: object

Represents a connection to the database.

dbfile

Path to database file

Type:

str

class _LoggingCursor(dbfile, cursor)[source]

Bases: object

close()[source]
execute(sql, parameters=(), log=True)[source]
fetchall()[source]
fetchone()[source]
property lastrowid
check_writable()[source]

Raise StorageError if the database is read-only.

close()[source]

Close the database connection

commit_transaction()[source]

Commit a transaction previously started with SQLiteDatabase.start_transaction

cursor()[source]

Returns a cursor which can be used to query the SQLite database

open()[source]

Open the database connection specified in this object’s dbfile attribute

purge()[source]

Delete every record in every table in the database. :raises SQLiteStorageError: Attempt to perform and operation on a database which is not open

revert_transaction()[source]

Revert a transaction previously started with SQLiteDatabase.start_transaction

start_transaction()[source]

Begin a transaction, which can be reverted with SQLiteDatabase.revert_transaction or committed with SQLiteDatabase.commit_transaction.

table(table_name)[source]

Get a table object for a table in this database. :param table_name: The name of the table requested :type table_name: str

Returns:

A table object for the table table_name

Raises:

SQLiteStorageError – Attempt to perform and operation on a database which is not open

tables()[source]

Get a list of all the tables in the database :returns: A list of the target names for the tables in the database.

Raises:

SQLiteStorageError – Attempt to perform and operation on a database which is not open

class taucmdr.cf.storage.sqlite3_file.SQLiteLocalFileStorage(name, prefix, create_prefix=True)[source]

Bases: LocalFileStorage

A persistent, transactional record storage system.

Uses sqlite3 for both the database and the key/value store.

Record

alias of _SQLiteJsonRecord

__enter__()[source]

Initiates the database transaction.

__exit__(ex_type, value, traceback)[source]

Finalizes the database transaction.

__str__()[source]

Human-readable identifier for this database.

_abc_impl = <_abc._abc_data object>
_database_writable()[source]
connect_database(*args, **kwargs)[source]

Open the database for reading and writing, or only for reading if it can’t be written.

contains(keys, table_name=None, match_any=False)[source]

Check if the specified table contains at least one matching record.

The behavior depends on the type of keys:

  • self.Record.eid_type: check for the record with that element identifier.

  • dict: check for the record with attributes matching keys.

  • list or tuple: return the equivalent of map(contains, keys).

  • None: return False.

Parameters:

  • keys – Fields or element identifiers to match.

  • table_name (str) – Name of the table to operate on. See AbstractStorage.table.

  • match_any (bool) – Only applies if keys is a dictionary. If True then any key in keys may match or if False then all keys in keys must match.

Returns:

True if the table contains at least one matching record, False otherwise.

Return type:

bool

Raises:

ValueError – Invalid value for keys.

count(table_name=None)[source]

Count the records in the database.

Parameters:

table_name (str) – Name of the table to operate on. See AbstractStorage.table.

Returns:

Number of records in the table.

Return type:

int

database_exists()[source]

Determine if the database file backing this Storage object exists.

Returns:

True if database exists; false otherwise.

Return type:

bool

property dbfile

Absolute path to the database file.

Type:

str

disconnect_database(*args, **kwargs)[source]

Close the database for reading and writing.

get(keys, table_name=None, match_any=False)[source]

Find a single record.

The behavior depends on the type of keys:

  • self.Record.eid_type: return the record with that element identifier.

  • dict: return the record with attributes matching keys.

  • list or tuple: return a list of records matching the elements of keys

  • None: return None.

Parameters:

  • keys – Fields or element identifiers to match.

  • table_name (str) – Name of the table to operate on. See AbstractStorage.table.

  • match_any (bool) – Only applies if keys is a dictionary. If True then any key in keys may match or if False then all keys in keys must match.

Returns:

The matching data record if keys was a self.Record.eid_type or dict. list: All matching data records if keys was a list or tuple. None: No record found or bool(keys) == False.

Return type:

Record

Raises:

ValueError – Invalid value for keys.

insert(data, table_name=None)[source]

Create a new record.

If the table doesn’t exist it will be created.

Parameters:
Returns:

The new record.

Return type:

Record

match(field, table_name=None, regex=None, test=None)[source]

Find records where field matches regex or test.

Either regex or test may be specified, not both. If regex is given, then all records with field matching the regular expression are returned. If test is given then all records with field set to a value that causes test to return True are returned. If neither is given, return all records where field is set to any value.

Parameters:

  • table_name (str) – Name of the table to operate on. See AbstractStorage.table.

  • field (string) – Name of the data field to match.

  • regex (string) – Regular expression string.

  • test – Callable returning a boolean value.

Returns:

Matching data records.

Return type:

list

Raises:

ValueError – Invalid value for keys.

purge(table_name=None)[source]

Delete all records.

Parameters:

table_name (str) – Name of the table to operate on. See AbstractStorage.table.

remove(keys, table_name=None, match_any=False)[source]

Delete records.

The behavior depends on the type of keys:

  • self.Record.eid_type: delete the record with that element identifier.

  • dict: delete all records with attributes matching keys.

  • list or tuple: delete all records matching the elements of keys.

Parameters:

  • keys – Fields or element identifiers to match.

  • table_name (str) – Name of the table to operate on. See AbstractStorage.table.

  • match_any (bool) – Only applies if keys is a dictionary. If True then any key in keys may match or if False then all keys in keys must match.

Raises:

ValueError – bool(keys) == False or invalid value for keys.

search(keys=None, table_name=None, match_any=False)[source]

Find multiple records.

The behavior depends on the type of keys:

  • self.Record.eid_type: return the record with that element identifier.

  • dict: return all records with attributes matching keys.

  • list or tuple: return a list of records matching the elements of keys

  • None: return all records.

Parameters:

  • keys – Fields or element identifiers to match.

  • table_name (str) – Name of the table to operate on. See AbstractStorage.table.

  • match_any (bool) – Only applies if keys is a dictionary. If True then any key in keys may match or if False then all keys in keys must match.

Returns:

Matching data records.

Return type:

list

Raises:

ValueError – Invalid value for keys.

table(table_name)[source]

Return a handle to a table.

Return a handle to the named table or, if table_name is None, return the default table.

Parameters:

table_name (str) – Name of the table or None.

Returns:

A database table object.

Return type:

object

unset(fields, keys, table_name=None, match_any=False)[source]

Update records by unsetting fields.

Update only allows you to update a record by adding new fields or overwriting existing fields. Use this method to remove a field from the record.

The behavior depends on the type of keys:

  • self.Record.eid_type: update the record with that element identifier.

  • dict: update all records with attributes matching keys.

  • list or tuple: apply update to all records matching the elements of keys.

Parameters:

  • fields (list) – Names of fields to remove from matching records.

  • keys – Fields or element identifiers to match.

  • table_name (str) – Name of the table to operate on. See AbstractStorage.table.

  • match_any (bool) – Only applies if keys is a dictionary. If True then any key in keys may match or if False then all keys in keys must match.

Raises:

ValueError – bool(keys) == False or invalid value for keys.

update(fields, keys, table_name=None, match_any=False)[source]

Update records.

The behavior depends on the type of keys:

  • self.Record.eid_type: update the record with that element identifier.

  • dict: update all records with attributes matching keys.

  • list or tuple: apply update to all records matching the elements of keys.

Parameters:

  • fields (dict) – Data to record.

  • keys – Fields or element identifiers to match.

  • table_name (str) – Name of the table to operate on. See AbstractStorage.table.

  • match_any (bool) – Only applies if keys is a dictionary. If True then any key in keys may match or if False then all keys in keys must match.

Raises:

ValueError – bool(keys) == False or invalid value for keys.

exception taucmdr.cf.storage.sqlite3_file.SQLiteStorageError(table_name=None)[source]

Bases: StorageError

Indicates that the database connection has not been initialized.

message_fmt = '%(value)s\n\n%(hints)s\nPlease contact %(contact)s for assistance.'

Format string for the error message.

class taucmdr.cf.storage.sqlite3_file._SQLiteJsonRecord(database, element, eid=None)[source]

Bases: StorageRecord

eid_type

alias of int

class taucmdr.cf.storage.sqlite3_file._SQLiteJsonTable(database, name)[source]

Bases: object

Represents a JSON Table within the SQLite database. Operations on the table are made through this class.

Attributes:

Record

alias of _SQLiteJsonRecord

_ensure_exists()[source]
_get(keys=None, eid=None, match_any=False, remove=False)[source]
static _json_query(keys=None, match_any=False)[source]
count(cond, match_any=False)[source]
exists(field)[source]
get(keys=None, eid=None, match_any=False)[source]
insert(element)[source]
property name
purge()[source]
remove(keys=None, eid=None, match_any=False)[source]
search(cond, match_any=False)[source]

Return all records in this table matching the given conditions.

Parameters:

  • cond (dict) – Field-value pairs to match against stored JSON records.

  • match_any (bool) – If True, match records satisfying any condition (OR); otherwise all conditions must match (AND).

update(fields, keys=None, eids=None, match_any=False, unset=False)[source]

Update or remove fields in records matching the given keys or element IDs.

Parameters:

  • fields – Field-value dict to set, or a list/tuple of field names to remove if unset.

  • keys (dict) – Field-value pairs identifying records to update.

  • eids – Element ID or list of element IDs identifying records to update.

  • match_any (bool) – If True, match records satisfying any key (OR); otherwise AND.

  • unset (bool) – If True, remove the named fields instead of setting them.