Database Integration

The ability to persistenly store codes, decoders and computational results in a database is deeply integrated into the lpdec package. To that end, code and decoder objects implement an interface that allow them to be (de-)serialized using JSON. The base class for that mechanism is contained in the lpdec.persistence module.

Persistent Object Storage

class JSONDecodable

Bases: object

Base class for objects that can be serialized using JSON.

fromJSON(type cls, paramString, classname=None, **kwargs)

Create object of this class or a subclass from the JSON string paramString.

params(self)

Return a JSON encodable dictionary of parameters which, when passed to the constructor, yield the same object.

toJSON(self)

Returns a JSON string representing this object.

class JSONEncoder(skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Bases: json.encoder.JSONEncoder

Custom JSON that encodes subclasses of JSONDecodable by JSONDecodable.params() and the name of the class in the className attribute.

default(self, obj)

classByName(name)

makeObjectHook(**kwargs)

General Database Management

This package manages the database containing code definitions, simulation results, and other.

Before any of the functions are used, the init() method must be called in order to initialize the database connection.

class UTCDateTime(*args, **kwargs)

Bases: sqlalchemy.sql.type_api.TypeDecorator

Subclasses sqla.DateTime in order to add UTC timezone info to all objects.

When used as bind parameter, any supplied datetime object will be converted to UTC (if a timezone exists). Retrieved datetimes will always have the UTC timezone set.

impl

alias of DateTime

exception DatabaseException

Bases: Exception

Exception that indicates a problem in the database connection or state.

knownDatabases()

Return a list of known database connection strings.

The returned list may be modified in order to add/remove database strings. It is automatically stored at program exit.

saveDatabases()

Store the databases list to the config file.

init(database=None, testMode=False)

Initialize the database package and connect to database, which is a connection string.

Examples: - sqlite:///myresults.sqlite - mysql://username:password@localhost/port

If database is None, an interactive console dialogs asks the user to input a string. The database string may as well be a single number; in that case, the connection will be made to the entry with that position in the list of known databases.

teardown()

Deallocate all database resources. This is mainly intended for testing.

checkCode(code, insert=True)

Tests if code is contained in the database. If there is a code with the same name that does not match the given code, a DatabaseException is raised.

The code will be inserted into the database if insert is True and the code not yet contained.

Returns:The code’s primary ID (if it exists or was inserted by this method), otherwise None. Return type:int

checkDecoder(decoder, insert=True)

Tests if decoder is contained in the database. If there is a decoder with the same name that does not match the given code, a DatabaseException is raised.

The decoder will be inserted into the database if insert is True and the decoder not yet contained.

Returns:The decoder’s primary ID (if it exists or was inserted by this method), otherwise None. Return type:int

get(what, identifier, code=None)

Retrieve a code or decoder from the database. what is one of (“code”, “decoder”) and specifies what to retrieve. The identifier can be either the primary key or the name or the instance object of the code or decoder. :returns: The code or decoder object corresponding to the input identifier. :raises: DatabaseException if it was not found.

createCode(name, cls, **kwargs)

Convenience function that returns a code from database, if it exists, and otherwise creates it with the given parameters.

names(what='codes')

Return the names of all codes or decoders, depending on the parameter what which is one of (‘decoders’, ‘codes’).

Storage of Simulation Results

init()

Initialize the simulations database module. This needs to be called before any other function of this module can be used, but after db.init().

existingIdentifiers()

Returns a list of all identifiers for which simulation results exist in the database.

addDataPoint(point)

Add (or update) a data point to the database. :param simulation.DataPoint point: DataPoint instance. .

dataPoint(code, channel, wordSeed, decoder, identifier)

Return a simulation.DataPoint object for the given parameters.

If such one exists in the database, it is initialized with the data (samples, errors etc.) from there. Otherwise an empty point is created.