ait.core.db module¶

AIT Database

The ait.db module provides a general database storage layer for commands and telemetry with several backends.

class ait.core.db.AITDBResult(query=None, results=None, packets=None, errors=None)¶

Bases: object

AIT Database result wrapper.

AITDBResult is a minimal wrapper around database query results / errors. All AIT database APIs that execute a query will return their results wrapped in an AITDBResult object.

AITDbResult tracks four main attributes. Generally, an unused attribute will be None.

query: The query string(s) execute by the backend. This will be returned as a String. Backends are free to format this as appropriate but, in general, the contents of this will be a viable query that could be executed without modification by the backend whenever possible.
results: The raw results from the backend library query. This field is populated by an API query that doesn’t further process results (e.g., into ait.core.tlm.Packet). Users will need to consult the appropriate backend driver documentation for details on the format returned.
packets: A generator that returns ait.core.tlm.Packet objects parsed from the executed query. Interfacing with queried data as ait.core.tlm.Packet objects is the most use case for AIT’s database APIs. All “high level” API functions return their data as Packet objects. In general, a result object will either have data accessible through packets or results, but not both.
errors: An iterator of errors encountered during query execution. Depending on the specific backend implementation, errors and query results (either in results or packets) may or may not be mutually exclusive. Specific API endpoints will document this.

Example uses:

# Query SQLite for all available packets and iterate over the results, # printing them to stdout. be = db.SQLiteBackend() be.connect() res = be.query_packets() for packet in res.get_packets():

print(packet)

__init__(query=None, results=None, packets=None, errors=None)¶: Initialize self. See help(type(self)) for accurate signature.

get_packets()¶

errors¶

has_packets¶

query¶

results¶

class ait.core.db.GenericBackend¶

Bases: object

Generic database backend abstraction

GenericBackend attempts to adequately abstract database operations into a small set of common methods. Not all methods will be useful for every database type and additional methods may need to be added for future database support.

Generally, the expected method functionality should be

connect

Connect to instance of the database via the backend driver. Five configuration options are respected by convention in AIT built-in backend implementations if they’re applicable to the given backend

database.host

The host to connect to. Defaults to localhost

database.port

The port to connect to. Defaults to technology specific value.

database.un

The username to use when connecting to the database. Defaults to a technology specific value.

database.pw

The password to use when connecting to the database. Defaults to a technology specific value.

database.dbname

The name of the database to create/use. Defaults to ait.

create

Create a database in the database instance

insert

Insert a packet into the database

query

Take a string defining a database query and return the results. The format of the results is backend specific.

query_packets

Query for packet types with optional filters.

close

Close the connection to the database instance and handle any cleanup

__init__()¶: Initialize self. See help(type(self)) for accurate signature.

close(**kwargs)¶: Close connection to the database instance.

connect(**kwargs)¶: Connect to a backend’s database instance.

create(**kwargs)¶: Create a database in the instance.

classmethod create_packet_from_result(packet_name, result)¶

Return an AIT Packet from a given database query result item

Creates and returns an AIT Packet denoted by packet_name with field values set given the contents of result. Values that are missing in the result will be defaulted in the returned Packet. Specific implementations will have caveats related to their backend and the limitations of the API.

insert(packet, time=None, **kwargs)¶: Insert a record into the database.

query(query, **kwargs)¶: Query the database instance and return results.

query_packets(packets=None, start_time=None, end_time=None, **kwargs)¶

Query the database instance for packet objects

Return all packets of the defined type from the data store, filtering over an optional time range. If no parameters are specified, this will return all data for all packet types as Packet objects.

class ait.core.db.InfluxDBBackend¶

Bases: ait.core.db.GenericBackend

InfluxDB Backend Abstraction

This requires the InfluxDB Python library to be installed and InfluxDB to be installed. Note, the InfluxDB Python library is only supports up to version 1.2.4. As such, this is only tested against 1.2.4. Newer versions may work but are not officially supported by AIT.

https://github.com/influxdata/influxdb-python https://docs.influxdata.com/influxdb

__init__()¶

close(**kwargs)¶: Close the database connection

connect(**kwargs)¶

Connect to an InfluxDB instance

Connects to an InfluxDB instance and switches to a given database. If the database doesn’t exist it is created first via create().

Configuration Parameters

host: The host for the connection. Passed as either the config key database.host or the kwargs argument host. Defaults to localhost.
port: The port for the connection. Passed as either the config key database.port or the kwargs argument port. Defaults to 8086.
un: The un for the connection. Passed as either the config key database.un or the kwargs argument un. Defaults to root.
pw: The pw for the connection. Passed as either the config key database.pw or the kwargs argument pw. Defaults to pw.
database name: The database name for the connection. Passed as either the config key database.dbname or the kwargs argument database. Defaults to ait.

create(**kwargs)¶

Create a database in a connected InfluxDB instance

Configuration Parameters

database name

The database name to create. Passed as either the config key database.dbname or the kwargs argument database. Defaults to ait.

Raises:

AttributeError:: If a connection to the database doesn’t exist

classmethod create_packet_from_result(packet_id, result)¶

Create an AIT Packet from an InfluxDB query ResultSet item

Extract Influx DB query results entry into an AIT packet. This assumes that telemetry data was inserted in the format generated by InfluxDBBackend.insert(). Complex types such as CMD16 and EVR16 are evaluated if they can be properly encoded from the raw value in the query result. If there is no opcode / EVR-code for a particular raw value the value is skipped (and thus defaulted to 0).

TODO: Reevaluate this assumption that missing opcodes / EVR-codes should be left as 0 if a match isn’t found in the dictionary.

Arguments

packet_id (string or PacketDefinition): The “id” for the packet to create. If packet_id is a string it must name a valid PacketDefintion in the telemetry dictionary. Otherwise, it must be a PacketDefinition.
result (dict): The influxdb.resultset.ResultSet entry from which values should be extracted to form the AIT packet

Returns

A ait.core.tlm.Packet with values initialized from the values in the ResultSet entry. If a field cannot be located in the result entry it will left as the default value in the Packet or set to None if it’s a CMD / EVR type.

create_packets_from_results(**kwargs)¶

insert(packet, time=None, **kwargs)¶

Insert a packet into the database

Arguments

packet: The ait.core.tlm.Packet instance to insert into the database
time: Optional parameter specifying the time value to use when inserting the record into the database. Default case does not provide a time value so Influx defaults to the current time when inserting the record.
tags: Optional kwargs argument for specifying a dictionary of tags to include when adding the values. Defaults to nothing.

query(query, **kwargs)¶

Query the database and return results

Queries the Influx instance and returns a ResultSet of values. For API documentation for InfluxDB-Python check out the project documentation. https://github.com/influxdata/influxdb-python

Arguments:

query:: The query string to send to the database

Returns:

An AITDBResult with the database query results set in results or errors recorded in errors.

query_packets(packets=None, start_time=None, end_time=None, **kwargs)¶

Query the database for packet types over a time range.

Query the database for packet types over a time range. By default, all packet types will be queried from the start of the GPS time epoch to current time. In other words, you will (probably) receive everything in the database. Be careful!

Arguments:

packets: An iterator containing the packet names over which to query. (: default: All packet types defined in the telemetry dictionary)
start_time: A datetime.datetime object defining the query time: range start inclusively. (default: The start of the GPS time Epoch)
end_time: A datetime.datetime object defining the query time: range end inclusively. (default: The current UTC Zulu time).

Additional Keyword Arguments:

yield_packet_time: If True, the packet generator will yield results: in the form (packet time as datetime object, Packet object). This provides access to the time field associated with the packet in the database.
kwargs: Additional kwargs are passed to the backend query without: modification.

Returns:

An AITDBResult with packets set to a generator of all: packet objects returned by the query in time-sorted order. Otherwise, errors will contain any encountered errors.

Raises:

ValueError: If a provided packet type name cannot be located in the: telemetry dictionary.

class ait.core.db.SQLiteBackend¶

Bases: ait.core.db.GenericBackend

__init__()¶

close(**kwargs)¶: Close the database connection.

connect(**kwargs)¶

Connect to a SQLite instance If the database doesn’t exist it is created first via create().

Configuration Parameters

database name: The database name of file to “connect” to. Passed as either the config key database.dbname or the kwargs argument database. Defaults to ait.db.

create(**kwargs)¶

Create packet tables in the connected database

Configuration Parameters

tlmdict: The ait.core.tlm.TlmDict instance to use. Defaults to the currently configured telemetry dictionary.

classmethod create_packet_from_result(packet_name, data)¶

Return an AIT Packet from a given database query result item

Creates and returns an AIT Packet denoted by packet_name with field values set given the contents of result. Values that are missing in the result will be defaulted in the returned Packet. Specific implementations will have caveats related to their backend and the limitations of the API.

insert(packet, time=None, **kwargs)¶

Insert a packet into the database

Arguments

packet: The ait.core.tlm.Packet instance to insert into the database

query(query, **kwargs)¶

Query the database and return results

Queries the SQLite instance and returns the raw results object. API documentation for Python’s SQLite3 interface provides format details. https://docs.python.org/3.7/library/sqlite3.html

Arguments:

query:: The query string to send to the database

Returns:

An AITDBResult with the database query results set in results or errors recorded in errors.

query_packets(packets=None, start_time=None, end_time=None, **kwargs)¶

Query the database for packet types over a time range.

Query the database for packet types over a time range. By default, all packet types will be queried from the start of the GPS time epoch to current time. In other words, you will (probably) receive everything in the database. Be careful!

Arguments:

packets: An iterator containing the packet names over which to query. (: default: All packet types defined in the telemetry dictionary)
start_time: A datetime.datetime object defining the query time: range start inclusively. (default: The start of the GPS time Epoch)
end_time: A datetime.datetime object defining the query time: range end inclusively. (default: The current UTC Zulu time).

Additional Keyword Arguments:

yield_packet_time: If True, the packet generator will yield results: in the form (packet time as datetime object, Packet object). This provides access to the time field associated with the packet in the database.
kwargs: Additional kwargs are passed to the backend query without: modification.

Returns:

An AITDBResult with packets set to a generator of all

packet objects returned by the query in time-sorted order. The errors attribute will include any errors encountered.

Note, because queries are broken up by packet type, this could contain both results and errors.

Raises:

ValueError: If a provided packet type name cannot be located in the: telemetry dictionary.