PySECONDO - Python DB-API 2.0 interface for `SECONDO`¶

`SECONDO`-API Main Module¶

The module Secondo API implements the Application Programming Interface for Python for the interaction with a SECONDO server. The API implements the Python Database API 2.0 Specification (PEP 249).

connect(host, port, username='username', passwd='passwd', database='')[source]¶

Constructor for creating a connection to the SECONDO server. If further data is provided (database and login data), a connection to an existing database (if available on the server) will be established.

Returns a Connection Object.

Parameters

host – The host of the SECONDO server as IP-address or as qualified name (localhost).
port – The port of the SECONDO server.
username – The username for the connection (optional).
passwd – The password for the connection (optional).
database – The name of the database (optional).

Returns

A Connection Object.

Connection Class¶

The Connection Class provides methods to handle the connection to a SECONDO server and a stored database. The connection can be established in two levels:

Server-only mode

A TCP connection will be established with the SECONDO server. At this point no connection will be established with a specific stored database on the server. This mode is useful for administration tasks on the SECONDO server, like creating, deleting and restoring databases. These methods can as well be called in the Direct DB connection mode, but the current connection with the last opened database will be closed.
Direct DB connection mode

Both a connection with the SECONDO server and to a specific stored database will be established. The requisite for this type of connection is the availability of the database and its specific login parameters (i.e. name of the database, user name and password). A database may or not have login parameters (i.e. user name and password). Therefore, they are optional parameters of the constructor method.

Example for establishing a connection to the Secondo server providing a host and a port:

import secondodb.api as secondo

HOST = '127.0.0.1'   # The server's hostname or IP address
PORT = '1234'        # The port used by the server

connection = secondo.connect(HOST, PORT)

Example for establishing a connection to the Secondo server and to a specific stored database (BERLINTEST):

import secondodb.api as secondo

HOST = '127.0.0.1'   # The server's hostname or IP address
PORT = '1234'        # The port used by the server

connection = secondo.connect(HOST, PORT, database='BERLINTEST')

Basic Methods¶

class Connection(host, port, username, passwd, database)[source]¶

This class implements the connection object of the SECONDO API. The connection object manages all operations at server level and provides access to the current connection instance with the server. The connection object provides the cursor() method to create a cursor for the execution of operations at the database level.

close()[source]¶

Close the connection now.

The connection will be unusable from this point forward; an InternalError exception will be raised if any operation is attempted with the connection. The same applies to all cursor objects trying to use the connection. Note that closing a connection without committing the changes first will cause an implicit rollback to be performed.

Returns: True, if the connection was closed successfully.

close_database()[source]¶

Closes the currently opened database on the SECONDO server. The connection object returns to the server-only mode.

Returns: True, if the database was closed successfully.

create_database(database_name)[source]¶

Creates a database on the SECONDO server. The database remains open after creation.

Parameters: database_name – The name of the new database.
Returns: True, if the database was created successfully.

cursor()[source]¶

Return a new Cursor Object using the connection.

If the database does not provide a direct cursor concept, the module will have to emulate cursors using other means to the extent needed by this specification.

Returns: A Cursor object.

delete_database(database_name)[source]¶

Deletes a database on the SECONDO server. Before deletion, all opened databases on the Secondo server will be closed. The connection object will be set to server-only mode.

Parameters: database_name – The name of the database.
Returns: True, if the database was deleted successfully.

open_database(database_name)[source]¶

Opens a database on the SECONDO server. The server-only mode will be set to False.

Parameters: database_name – The name of the database.
Returns: True, if the database was opened successfully.

restore_database(database_name, database_location)[source]¶

Restores a database from a specific location into the SECONDO server. After restoring the database will be available for establish a connection.

Parameters

database_name – The name of the database.
database_location – The location of the database.

Returns

True, if the database was successfully restored.

Transaction Methods¶

class Connection(host, port, username, passwd, database)[source]¶

This class implements the connection object of the SECONDO API. The connection object manages all operations at server level and provides access to the current connection instance with the server. The connection object provides the cursor() method to create a cursor for the execution of operations at the database level.

commit()[source]¶

Commit any pending transaction to the database.

Returns: True, if the current transaction was commit successfully.

rollback()[source]¶

In case a database does provide transactions this method causes the database to roll back to the start of any pending transaction. Closing a connection without committing the changes first will cause an implicit rollback to be performed.

Returns: True, if the current transaction was rolled back successfully.

Get-Methods¶

Get-Methods can be used to retrieve different types of objects or information from a SECONDO database.

class Connection(host, port, username, passwd, database)[source]¶

This class implements the connection object of the SECONDO API. The connection object manages all operations at server level and provides access to the current connection instance with the server. The connection object provides the cursor() method to create a cursor for the execution of operations at the database level.

get_algebra(algebra_name)[source]¶

Returns the details for an algebra from the SECONDO server.

Returns: A Python list with the available algebras on the SECONDO server.

get_list_algebras()[source]¶

Returns a list of the available algebras in the SECONDO server.

Returns: A Python list with the available algebras_1 on the SECONDO server.

get_list_databases()[source]¶

Returns a list of the databases in the SECONDO server.

Returns: A Python list with the names of the available databases on the SECONDO server.

get_list_objects()[source]¶

Returns a list of the objects in the SECONDO server.

Returns: A Python list with the names available objects of the currently opened database.

get_list_type_constructors()[source]¶

Returns a list of the type constructors available in the SECONDO server.

Returns: A Python list with the constructors of the available types of the currently opened database.

get_list_types()[source]¶

Returns a list of the types available in the current open database.

Returns: A list expression object with the available types of the currently opened database.

Cursor Class¶

class Cursor(connection)[source]¶

close()[source]¶

Close the cursor now (rather than whenever __del__ is called).

The cursor will be unusable from this point forward; an InternalError exception will be raised if any operation is attempted with the cursor.

Returns: True, if the cursor was closed successfully.

execute(operation, parameters=None)[source]¶

Prepare and execute a database operation (query or command).

Parameters may be provided as sequence or mapping and will be bound to variables in the operation. The placeholders in the operation must use the following format: {i}, where i is an integer, which specifies the position of the parameter in the list of parameters.

Example 1: Simple Query

Operation = query {0} Parameter list = [‘mehringdamm’] Formatted operation = query mehringdamm

Example 2: Inserting Single Tuples

Operation = query {0} inserttuple[{1}, {2}] count; Parameter list = [‘myfirstrel’,‘“Anna”’, ‘27’] Formatted operation = query myfirstrel inserttuple[“Anna”, 27] count;

Parameters

operation – A string with a SECONDO command.
parameters – Further parameters for the execution of the command (currently not in use).

Returns

A SECONDO object, a list with SECONDO objects or a SECONDO response.

execute_create(identifier, type_expression)[source]¶

Creates an object of the given type with undefined value.

Parameters

identifier – The identifier of the object to be created.
type_expression – A type expression for the command ‘create <identifier> = <type expression>’

Returns

The string Success, if the object was created successfully.

execute_create_empty_relation(relation_name, list_attributes)[source]¶

Creates an empty relation in the database. The list of the attributes must follow the following format:

list_attributes = [attr]

where

attr = [Name, type]

IMPORTANT: The name of the attributes must begin with an upper case character.

Example:

attr1 = [‘Att1’, ‘string’] attr2 = [‘Att2’, ‘string’]

list_attributes = [attr1, attr2]

Parameters

relation_name (str) – The name of the relation.
list_attributes ([]) – A list with the attributes of the relation (please be aware of the format).

Returns

The string ‘Success’, if the relation was successfully created, otherwise None.

execute_create_type(identifier, type_expression)[source]¶

Creates a named type in the database.

Parameters

identifier – The identifier of the type to be created.
type_expression – A type expression for the command ‘type <identifier> = <type expression>’

Returns

The string Success, if the named type was created successfully.

execute_delete(identifier)[source]¶

Deletes the object with the name <identifier> from the currently opened database.

Parameters: identifier – The identifier of the object.
Returns: The string Success, if the object was deleted successfully.

execute_delete_type(identifier)[source]¶

Deletes a named type from the database.

Parameters: identifier – The identifier of the type to be deleted.
Returns: The string Success, if the named type was deleted successfully.

execute_derive(identifier, value_expression)[source]¶

This works basically in the same way as the let command. The difference is the handling of the created objects during creating and restoring a database dump. The derive command should be used for objects that have no external representation, e.g., indexes.

Parameters

identifier – The identifier of the object.
value_expression – A value expression for the command ‘derive <identifier> = <value expression>’

Returns

None

execute_insert_tuple_into_relation(relation_name, single_tuple)[source]¶

Inserts a list of values into a relation.

Parameters

relation_name (str) – The name of the relation.
single_tuple ([]) – A single tuple of the relation. The single tuple is a list must contain two elements: the first element is a list with the values of the tuple, and the second element is a list with the types of the relation.

Returns

The string ‘Success’, if the tuples were successfully added, otherwise None.

execute_kill(identifier)[source]¶

Removes the object with the name <identifier> from the opened database catalog without removing its data structures. Generally, the delete command should be used to remove database objects. The kill command should only be used if the delete command crashes the database due to corrupted persistent data structures for this object.

Parameters: identifier – The identifier of the object to be “killed”.
Returns: The string Success, if the object was “killed” successfully.

execute_let(identifier, value_expression)[source]¶

This command does almost the same as the query command. In contrast, the result of the <value expression> is not displayed on the screen. Instead, the result is stored in an object with the name <identifier>. The command only runs successfully if the object does not exist yet in the database; otherwise, an error message is displayed.

Parameters

identifier – The identifier of the object.
value_expression – A value expression for the command ‘let <identifier> = <value expression>’

Returns

A list expression object with the response from the SECONDO server.

execute_simple_query(value_expression)[source]¶

Evaluates the given value expression and displays the result object.

Parameters: value_expression – A value expression for the command ‘query <value expression>’
Returns: A list expression object with the response from the SECONDO server.

execute_update(identifier, value_expression)[source]¶

Assigns the result of the value expression to an existing object in the database.

Parameters

identifier – The identifier of the object.
value_expression – A value expression for the command ‘update <identifier> := <value expression>’

Returns

The string Success, if the object was updated successfully.

executemany(operation, seq_of_parameters)[source]¶

Prepare a database operation (query or command) and then execute it against all parameter sequences or mappings found in the sequence seq_of_parameters. Every entry of the list seq_of_parameters must be declared as a list, even when just one parameter is being used.

The placeholders in the operation must use the following format: {i}, where i is an integer number, which specifies the position of the parameter in the list of parameters.

Example 1: Simple Query

Operation = query {0} Parameter list = [‘mehringdamm’] Formatted operation = query mehringdamm

Example 2: Inserting Single Tuples

Operation = query {0} inserttuple[{1}, {2}] count; Parameter list = [‘myfirstrel’,‘“Anna”’, ‘27’] Formatted operation = query myfirstrel inserttuple[“Anna”, 27] count;

Parameters

operation – A SECONDO command with placeholders.
seq_of_parameters – A list with further parameters for the execution of the commands of the list.

Returns

A list with entries. Each entry is a list with an SECONDO object, the type of the response and the list expression as string.

fetchall()[source]¶

Fetch all (remaining) rows of a query result, returning them as a sequence of sequences (e.g. a list of tuples). An empty sequence is returned when no more rows are available.

An InterfaceError exception is raised if the previous call to .execute*() did not produce any result set or no call was issued yet.

Returns: A list with the fetched elements.

fetchmany(size=1)[source]¶

Fetch the next set of rows of a query result, returning a sequence of sequences (e.g. a list of tuples). An empty sequence is returned when no more rows are available. If there are not enough rows to fulfil the size parameter, only the available rows will be returned.

Parameters: size – The number of the rows to be returned from the cursor.
Returns: A list with the fetched elements.

fetchone()[source]¶

Fetch the next row of a query result set, returning a single sequence, or None when no more data is available.

An InterfaceError exception is raised if the previous call to .execute*() did not produce any result set or no call was issued yet.

Returns: A single row of a query result set.

Exceptions¶

The module Secondo API implements the Application Programming Interface for Python for the interaction with a SECONDO server. The API implements the Python Database API 2.0 Specification (PEP 249).

exception DataError(message, *args)[source]: Exception raised for errors that are due to problems with the processed data like division by zero, numeric value out of range, etc.

exception DatabaseError(message, *args)[source]: Exception raised for errors that are related to the database.

exception Error(message, *args)[source]: Exception that is the base class of all other error exceptions. You can use this to catch all errors with one single except statement. Warnings are not considered errors and thus should not use this class as base.

exception IntegrityError(message, *args)[source]: Exception raised when the relational integrity of the database is affected, e.g. a foreign key check fails.

exception InterfaceError(message, *args)[source]: Exception raised for errors that are related to the database interface rather than the database itself.

exception InternalError(message, *args)[source]: Exception raised when the database encounters an internal error, e.g. the cursor is not valid anymore, the transaction is out of sync, etc.

exception NotSupportedError(message, *args)[source]: Exception raised in case a method or database API was used which is not supported by the database, e.g. requesting a .rollback() on a connection that does not support transaction or has transactions turned off.

exception OperationalError(message, *args)[source]: Exception raised for errors that are related to the database’s operation and not necessarily under the control of the programmer, e.g. an unexpected disconnect occurs, the data source name is not found, a transaction could not be processed, a memory allocation error occurred during processing, etc.

exception ProgrammingError(message, *args)[source]: Exception raised for programming errors, e.g. table not found or already exists, syntax error in the SQL statement, wrong number of parameters specified, etc.

exception Warning(message, *args)[source]: Exception raised for important warnings like data truncations while inserting, etc.

Support Modules¶

`SECONDO` Commands¶

The module Secondo Commands contains the strings of the commands to interact with the SECONDO server and its objects. The strings can be formatted using the Python method format() to replace the placeholders (i.e. {0} or {1}).

apply_parameters_to_operation(operation, parameter_list)[source]¶

Replaces the placeholders of the operation with the parameters of the list.

Parameters

operation – A string with an operation, which includes placeholders for the parameters.
parameter_list – A list of parameters.

Returns

The formatted operation.

Available Secondo Commands:

# ---- Basic commands ---- #

SECONDO_COM_QUERY = 'query {0}'
SECONDO_COM_LET = 'let {0} = {1}'
SECONDO_COM_DERIVE = 'derive {0} = {1}'
SECONDO_COM_UPDATE = 'update {0} := {1}'
SECONDO_COM_DELETE = 'delete {0}'
SECONDO_COM_TYPE = 'type {0} = {1}'
SECONDO_COM_DELETE_TYPE = 'delete type {0}'
SECONDO_COM_CREATE = 'create {0} : {1}'
SECONDO_COM_KILL = 'kill {0}'

# ---- Databases ----- #

SECONDO_COM_CREATE_DB = 'create database {0}'
SECONDO_COM_OPEN_DB = 'open database {0}'
SECONDO_COM_CLOSE_DB = 'close database'
SECONDO_COM_DELETE_DB = 'delete database {0}'
SECONDO_COM_RESTORE_DB = 'restore database {0}'

# ---- Transactions ----- #

SECONDO_COM_BEGIN_TR = 'begin transaction'
SECONDO_COM_COMMIT_TR = 'commit transaction'
SECONDO_COM_ABORT_TR = 'abort transaction'

# ---- Inquiries ----- #

SECONDO_COM_LIST_DB = 'list databases'
SECONDO_COM_LIST_TYPE_CONS = 'list type constructors'
SECONDO_COM_LIST_OPERATORS = 'list operators'
SECONDO_COM_LIST_ALGEBRAS = 'list algebras'
SECONDO_COM_LIST_ALGEBRA = 'list algebra {0}'
SECONDO_COM_LIST_TYPES = 'list types'
SECONDO_COM_LIST_OBJECTS = 'list objects'

# ---- Import and Export ----- #

SECONDO_COM_SAVE_DB = 'save database to {0}'
SECONDO_COM_RESTORE_DB_FROM = 'restore database {0} from {1}'
SECONDO_COM_SAVE_OBJECT = 'save {0} to {1}'
SECONDO_COM_RESTORE_OBJECT = 'restore {0} from {1}'

`SECONDO` Messages¶

The module Secondo Messages contains the start and end strings of the responses to an inquiry or a command from the SECONDO server.

Available Secondo Messages:

SECONDO_OK = '<SecondoOk/>'

SECONDO_INTRO_START = '<SecondoIntro>'
SECONDO_INTRO_END = '</SecondoIntro>'

SECONDO_ERROR_START = '<SecondoError>'
SECONDO_ERROR_END = '</SecondoError>'

SECONDO_CONNECT_START = '<Connect>'
SECONDO_CONNECT_END = '</Connect>'
SECONDO_DISCONNECT_END = '<Disconnect/>'

SECONDO_COMMAND_START = '<Secondo>'
SECONDO_COMMAND_END = '</Secondo>'

SECONDO_MESSAGE_START = '<Message>'
SECONDO_MESSAGE_END = '</Message>'

SECONDO_RESPONSE_START = '<SecondoResponse>'
SECONDO_RESPONSE_END = '</SecondoResponse>'

SECONDO_PROGRESS = 'progress'

`SECONDO` Parser¶

The module Secondo Parser implements functions for parsing a response to an inquiry or a command from the SECONDO server. A list expression object can be constructed through the function receive_response. A list expression object for a specific inquiry can be then converted to a Python structure (dictionary or list), which can be used to print or display the results in an ad-hoc format.

check_identifier(identifier)[source]¶

Checks the validity of a given value expression.

Parameters: identifier (str) –
Return type: bool
Returns: True, if the value expression is valid.

check_port(port)[source]¶

Checks the validity of a given port value.

Parameters: port (str) – The number of the port as string.
Return type: bool
Returns: True, if the port value is valid.

check_validity_string(validity_string)[source]¶

Checks the validity string of a SECONDO response.

Parameters: validity_string (str) – The string with the value ‘bnl’.
Return type: bool
Returns: True, if the string has the bnl-value. Otherwise a DataError will be raised.

parse_inquiry_algebra(list_expr)[source]¶

Returns a list with the objects of a database.

Parameters: list_expr (ListExp) – A response list.
Return type: Algebra
Returns: An Algebra object.

parse_inquiry_algebras(list_expr)[source]¶

Returns a list with the algebras of the server.

Parameters: list_expr (ListExp) – A list expression object.
Return type: []
Returns: The list of the algebras.

parse_inquiry_databases(list_expr)[source]¶

Returns a list with the database names of a database inquiry.

Parameters: list_expr (ListExp) – A List Expression object with a database inquiry.
Return type: []
Returns: A list with the database names.

parse_inquiry_objects(list_expr)[source]¶

Parses an objects inquiry from a SECONDO server response.

Parameters: list_expr (ListExp) – A list expression object with the types of the response.
Return type: []
Returns: A list with objects of the class Object containing the types.

parse_inquiry_type_constructors(list_expr)[source]¶

Parses a types inquiry from a SECONDO server response.

Parameters: list_expr (ListExp) – A list expression object with the types of the response.
Return type: []
Returns: A list containing the type constructors.

parse_inquiry_types(list_expr)[source]¶

Parses a types inquiry from a SECONDO server response.

Parameters: list_expr (ListExp) – A list expression object with the types of the response.
Return type: []
Returns: A list with objects of the class Type containing the types.

parse_query(list_expr)[source]¶

Converts the result of a query in list expression format into Python objects.

Parameters: list_expr (ListExp) – A list expression object.
Returns: A Python object.

parse_type_definition(list_expr)[source]¶

Parses a type definition element from a SECONDO server response.

Parameters: list_expr (ListExp) – A list expression object with the type definition of the response.
Returns: A string value with the type and a list with the attributes, if the type corresponds to a relation. Otherwise the list parameter will be set to None. Every single attribute is an object of the class Attribute.

receive_response(socket_object)[source]¶

This method handles the SECONDO response from the server. After processing two parameters will be returned: The first parameter contains the opening string of the response (for example <SecondoIntro>). The second parameter depends on this string, as it can be a simple string with a message or a List Expression object with the result of an inquiry.

In case of an error, a dictionary structure with the details (error code, position and message) will be returned. In any case, the returned result list corresponds to the fourth element of the obtained list expression object from the server response.

Parameters: socket_object (socket) – A socket object with the response from the server.
Returns: The opening string of the response and a list or a message.

`SECONDO` Algebras¶

Data types for the Secondo Standard Algebra

The module Secondo Standard Algebra implements the data types for the conversion of list expression objects with values of the types contained in the StandardAlgebra of the SECONDO system. The data types are implemented in Python using Data Classes. Data Classes are implemented in the API like normal classes without behaviour. Like regular classes their attributes can be called through the given names.

parse_bool(list_expr)[source]¶

Parses a list expression for a boolean object.

Parameters: list_expr (ListExp) – A list expression object containing a boolean.
Return type: bool
Returns: A boolean.

parse_int(list_expr)[source]¶

Parses a list expression for an integer object.

Parameters: list_expr (ListExp) – A list expression object containing an integer.
Return type: int
Returns: An integer.

parse_longint(list_expr)[source]¶

Parses a list expression for a long integer object.

Parameters: list_expr (ListExp) – A list expression object containing a long integer.
Return type: int
Returns: An integer.

parse_rational(list_expr)[source]¶

Parses a list expression for a rational object.

Parameters: list_expr (ListExp) – A list expression object containing a rational.
Return type: float
Returns: A float.

parse_real(list_expr)[source]¶

Parses a list expression for a real object.

Parameters: list_expr (ListExp) – A list expression object containing a real.
Return type: float
Returns: A float.

parse_string(list_expr)[source]¶

Parses a list expression for a string object.

Parameters: list_expr (ListExp) – A list expression object containing a string.
Return type: str
Returns: A string.

Data types for the Secondo Spatial Algebra

The module Secondo Spatial Algebra implements the data types for the conversion of list expression objects with values of the types contained in the SpatialAlgebra of the SECONDO system. The data types are implemented in Python using Data Classes. Data Classes are implemented in the API like normal classes without behaviour. Like regular classes their attributes can be called through the given names.

class Face(outercycle, holecycles)[source]¶: Implements a single face of a region, containing an outercycle (list of single points) and holecycles (a list of cycles, where each cycle is a list of points).

class Line(segments)[source]¶: Implements a line as a list of single segments of the class Segment.

class Point(x, y)[source]¶: Implements a single point expressing two coordinates X and Y.

class Region(faces)[source]¶: Implements a region as a list of faces of the class Face.

class Segment(x1, y1, x2, y2)[source]¶: Implements a single segment of a line.

convert_line_to_list_exp_str(line)[source]¶

Converts a line object to a nested list in string format.

Parameters: line (Line) – A line object.
Return type: str
Returns: The nested list as string.

convert_point_to_list_exp_str(point)[source]¶

Converts a point object to a nested list in string format.

Parameters: point (Point) – A point object.
Return type: str
Returns: The nested list as string.

convert_points_to_list_exp_str(points)[source]¶

Converts a points object to a nested list in string format.

Parameters: points ([]) – A points object.
Return type: str
Returns: The nested list as string.

convert_region_to_list_exp_str(region)[source]¶

Converts a region object to a nested list in string format.

Parameters: region (Region) – A region object.
Return type: str
Returns: The nested list as string.

parse_line(list_expr)[source]¶

Transforms a list expression object containing a line (line) to a named tuple.

Parameters: list_expr (ListExp) – A list expression object containing a line (line).
Return type: Line
Returns: A named tuple with the line.

parse_point(list_expr)[source]¶

Transforms a list expression object containing a point (point) to a named tuple.

Parameters: list_expr (ListExp) – A list expression object containing a point (point).
Return type: Point
Returns: A named tuple with the point.

parse_points(list_expr)[source]¶

Transforms a list expression object containing points (points) to a named tuple.

Parameters: list_expr (ListExp) – A list expression object containing points (points).
Return type: []
Returns: A named tuple with the points.

parse_region(list_expr)[source]¶

Transforms a list expression object containing a region (region) to a named tuple.

Parameters: list_expr (ListExp) – A list expression object containing a region (region).
Return type: Region
Returns: A named tuple with the region.

parse_segment(list_expr)[source]¶

Transforms a list expression object containing a segment (segment) to a named tuple.

Parameters: list_expr (ListExp) – A list expression object containing a segment (segment).
Return type: Segment
Returns: A named tuple with the segment.

Data types for the Secondo Spatio Temporal Algebra

The module Secondo Spatio-Temporal Algebra implements the data types for the conversion of list expression objects with values of the types contained in the TemporalAlgebra of the SECONDO system. The data types are implemented in Python using Data Classes. Data Classes are implemented in the API like normal classes without behaviour. Like regular classes their attributes can be called through the given names.

class BoolInInterval(interval, value_vector)[source]¶: Implements a structure to store the time interval and the value vector of a moving boolean.

class IPoint(instant, point)[source]¶: Implements an instant point as a point for a specific instant.

class IRegion(instant, region)[source]¶: Implements an instant region as a region for a specific instant.

class IntInInterval(interval, value_vector)[source]¶: Implements a structure to store the time interval and the value vector of a moving integer.

class Interval(start_time, end_time, close_left, close_right)[source]¶: Implements a time interval.

class MBool(intervals)[source]¶: Implements a moving boolean as a series of booleans in intervals.

class MInt(intervals)[source]¶: Implements a moving integer as a series of integer values in intervals.

class MPoint(intervals)[source]¶: Implements a moving point as a series of points in intervals.

class MReal(intervals)[source]¶: Implements a moving real as a series of real values in intervals.

class MRegion(intervals)[source]¶: Implements a moving region as a series of regions in intervals.

class MString(intervals)[source]¶: Implements a moving string as a series of string values in intervals.

class MapPoint(x1, y1, x2, y2)[source]¶: Implements a map point, i.e. a motion vector for a point of a moving region.

class MotionVector(x1, y1, x2, y2)[source]¶: Implements a motion vector of a moving point.

class PointInInterval(interval, motion_vector)[source]¶: Implements a structure to store the time interval and the motion vector of a moving point.

class RealInInterval(interval, value_vector)[source]¶: Implements a structure to store the time interval and the value vector of a moving real.

class RegionInInterval(interval, map_faces)[source]¶: Implements a structure to store the time interval and the motion vector of a moving region.

class StringInInterval(interval, value_vector)[source]¶: Implements a structure to store the time interval and the value vector of a moving string.

class ValueVectorBool(value)[source]¶: Implements the value vector for a moving boolean.

class ValueVectorInt(value)[source]¶: Implements the value vector for a moving integer.

class ValueVectorReal(start_value, end_value, boolean)[source]¶: Implements the value vector for a moving real.

class ValueVectorString(value)[source]¶: Implements the value vector for a moving string.

parse_ipoint(list_expr)[source]¶

Transforms a list expression object containing an instant point (ipoint) to a named tuple.

Parameters: list_expr (ListExp) – A list expression object containing an instant region (ipoint).
Return type: IPoint
Returns: An object of the data class IPoint with the instant point.

parse_iregion(list_expr)[source]¶

Transforms a list expression object containing an instant region (iregion) to a named tuple.

Parameters: list_expr (ListExp) – A list expression object containing an instant region (iregion).
Return type: IRegion
Returns: An object of the data class IRegion with the instant region.

parse_mbool(list_expr)[source]¶

Transforms a list expression object containing a moving boolean (mbool) to a named tuple.

Parameters: list_expr (ListExp) – A list expression object containing a moving boolean (mbool).
Return type: MBool
Returns: An object of the data class MBool with the moving boolean.

parse_mint(list_expr)[source]¶

Transforms a list expression object containing a moving integer (mint) to a named tuple.

Parameters: list_expr (ListExp) – A list expression object containing a moving integer (mint).
Return type: MInt
Returns: An object of the data class MInt with the moving integer.

parse_mpoint(list_expr)[source]¶

Transforms a list expression object containing a moving point (mpoint) to a named tuple.

Parameters: list_expr (ListExp) – A list expression object containing a moving point (mpoint).
Return type: MPoint
Returns: An object of the data class MPoint with the moving point.

parse_mreal(list_expr)[source]¶

Transforms a list expression object containing a moving real (mreal) to a named tuple.

Parameters: list_expr – A list expression object containing a moving real (mreal).
Return type: MReal
Returns: An object of the data class MReal with the moving real.

parse_mregion(list_expr)[source]¶

Transforms a list expression object containing a moving region (mregion) to a named tuple.

Parameters: list_expr (ListExp) – A list expression object containing a moving region (mregion).
Return type: MRegion
Returns: An object of the data class MRegion with the moving region.

parse_mstring(list_expr)[source]¶

Transforms a list expression object containing a moving string (mstring) to a named tuple.

Parameters: list_expr (ListExp) – A list expression object containing a moving string (mstring).
Return type: MString
Returns: An object of the data class MString with the moving string.

parse_timestamp(timestamp)[source]¶

Parses a timestamp string using the Python module datetime.

Formats supported:

‘%Y-%m-%d-%H:%M’ ‘%Y-%m-%d-%H:%M:%S’ ‘%Y-%m-%d-%H:%M:%S.%f’

Parameters: timestamp (str) – A string with a timestamp.
Return type: datetime
Returns: A datetime object.

Data types for the Secondo Relational Algebra

The module Secondo Relational Algebra implements the data types for the conversion of list expression objects with values of the types contained in the RelationalAlgebra of the SECONDO system. The data types are implemented in Python using Data Classes. Data Classes are implemented in the API like normal classes without behaviour. Like regular classes their attributes can be called through the given names.

class Relation(attributes, data)[source]¶: Implements the type relation (rel) of the relational algebra of SECONDO.

parse_relation(list_expr, attr_list)[source]¶

Parses a relation (rel) object. A relation named tuple with two attributes (attributes and data) will be returned. The attribute “attributes” contains the fields and types of the relation. The attribute “data” contains the entries.

Parameters

list_expr (ListExp) – A list expression object with a relation.
attr_list ([]) – The list of the attributes. Every attribute is an object of the class Attribute.

Return type

Relation

Returns

An object of the class Relation with the data. Every entry of the relation data is a Python dictionary, which allows to call the single fields of the tuple using the corresponding attribute name. The retrieval of the value using an index (like in lists) is allowed as well.

`SECONDO` Input Handler¶

The module Secondo Input Handler handles the conversion of different values from a socket stream in form of binary values. The implementation is based on the Java-Class MyInputStreamReader of the Secondo JavaGUI and supports the reception and construction of a list expression object originated through the response to an inquiry (or command) from the SECONDO server.

build_list_expr_from_binary(socket_object)[source]¶

This method builds a list expression object from a binary response from the SECONDO server. In javagui: readBinaryFrom()

Parameters: socket_object (socket) –
Return type: ListExp
Returns: A list expression object with the contents of the nested list.

read_binary_record(socket_object)[source]¶

Reads on each iteration a single buffered vector of bytes and translates it to the specified type. Some types requiere the specification of the length for the buffer. The length is normally expressed as the first binary value after the specification of the type integer.

Parameters: socket_object (socket) – A socket object with the response from the SECONDO server.
Return type: ListExp
Returns: None

read_bool(socket_object)[source]¶

Reads a boolean value from the socket response.

Parameters: socket_object (socket) – A socket object with the response from the SECONDO server.
Return type: bool
Returns: A boolean value.

read_byte(socket_object)[source]¶

Reads a single byte from the socket response.

Parameters: socket_object (socket) – A socket object with the response from the SECONDO server.
Return type: bytes
Returns: A byte value.

read_double(socket_object)[source]¶

Reads a double value from the socket response.

Parameters: socket_object (socket) – A socket object with the response from the SECONDO server.
Return type: float
Returns: A float representing the double value.

read_int(socket_object)[source]¶

Reads an integer value from the socket response. An integer value takes 4 bytes to be built.

Parameters: socket_object (socket) – A socket object with the response from the SECONDO server.
Return type: int
Returns: An integer value.

read_line_of_text(socket_object)[source]¶

Returns a single text line from a response. The input stream will be read until the occurrence of a new line.

Parameters: socket_object (socket) – A socket object.
Return type: str
Returns: A string with a single text line.

read_long(socket_object)[source]¶

Reads a long value from the socket response.

Parameters: socket_object (socket) – A socket object with the response from the SECONDO server.
Return type: int
Returns: A long (int) value.

read_real(socket_object)[source]¶

Reads a real value from the socket response.

Parameters: socket_object (socket) – A socket object with the response from the SECONDO server.
Return type: float
Returns: A float representing the real value.

read_short(socket_object)[source]¶

Reads a short value from the socket response. A short value takes 2 bytes to be built.

Parameters: socket_object (socket) – A socket object with the response from the SECONDO server.
Return type: int
Returns: A short value.

read_string(socket_object, size)[source]¶

Reads a string of a specified size from a socket object.

Parameters

socket_object (socket) – A socket object with the response from the SECONDO server.
size (int) – The size of the string.

Return type

str

Returns

A string value.

`SECONDO` List Expression¶

The module Secondo List Expression implements methods for the reception and construction of a list expression object originated through the response of the SECONDO server to an inquiry or a command. The implementation is based on the Java class ListExpr of the Secondo JavaGUI.

append_to_last_element(last_element, new_node)[source]¶

Appends a new element to a list expression object. The new element will be stored in the “value” variable of the last element passed and stores an empty list in his “next” variable.

Parameters

last_element – The list expression object to be extended.
new_node – The list expression object to be appended.

Returns

The new list expression object with the new appended element.

build_new_list_node(left_list, right_list)[source]¶

Builds a new node for a list expression. A node is formed by a left and a right list. The right list, which will be appended in the “next”-parameter, must not be an atom.

Parameters

left_list – The left list expression object for the parameter “value”.
right_list – The right list expression object for the parameter “next”.

Returns

A list expression object.

check_if_atom(in_list)[source]¶

Verifies if the ListExpr object is an atom. The method verifies the type of the list object.

Parameters: in_list – A ListExpr Object.
Returns: True, if the list element is not an atom, otherwise false.

create_bool_atom(value)[source]¶

Creates a new boolean atom using a boolean as value.

Parameters: value – A boolean.
Returns: A ListExp object with the newly created boolean atom.

create_integer_atom(value)[source]¶

Creates a new integer atom using an integer as value.

Parameters: value – An integer.
Returns: A ListExp object with the newly created integer atom.

create_real_atom(value)[source]¶

Creates a new real atom using an real as value.

Parameters: value – A real value.
Returns: A ListExp object with the newly created real atom.

create_string_atom(value)[source]¶

Creates a new string atom using a string as value.

Parameters: value – A string.
Returns: A ListExp object with the newly created string atom.

create_symbol_atom(value)[source]¶

Creates a new symbol atom using its identifier as value.

Parameters: value – The identifier of the symbol (like DATABASE).
Returns: A ListExp object with the newly created symbol atom.

create_text_atom(value)[source]¶

Creates a new text atom using a passed text as value.

Parameters: value – A text.
Returns: A ListExp object with the newly created text atom.

five_element_list(element_1, element_2, element_3, element_4, element_5)[source]¶

Creates a five element list expression.

Parameters

element_1 – A list expression object.
element_2 – A list expression object.
element_3 – A list expression object.
element_4 – A list expression object.
element_5 – A list expression object.

Returns

A list expression object with five elements.

four_element_list(element_1, element_2, element_3, element_4)[source]¶

Creates a four element list expression.

Parameters

element_1 – A list expression object.
element_2 – A list expression object.
element_3 – A list expression object.
element_4 – A list expression object.

Returns

A list expression object with four elements.

one_element_list(element_1)[source]¶

Creates a one element list expression. The left node contains the element value, and the right node an empty list.

Parameters: element_1 – A list expression object.
Returns: A list expression object with one element.

six_element_list(element_1, element_2, element_3, element_4, element_5, element_6)[source]¶

Creates a six element list expression.

Parameters

element_1 – A list expression object.
element_2 – A list expression object.
element_3 – A list expression object.
element_4 – A list expression object.
element_5 – A list expression object.
element_6 – A list expression object.

Returns

A list expression object with six elements.

three_element_list(element_1, element_2, element_3)[source]¶

Creates a three element list expression.

Parameters

element_1 – A list expression object.
element_2 – A list expression object.
element_3 – A list expression object.

Returns

A list expression object with three elements.

two_element_list(element_1, element_2)[source]¶

Creates a two element list expression.

Parameters

element_1 – A list expression object.
element_2 – A list expression object.

Returns

A list expression object with two elements.

PySECONDO - Python DB-API 2.0 interface for `SECONDO`¶

`SECONDO`-API Main Module¶

Connection Class¶

Basic Methods¶

Transaction Methods¶

Get-Methods¶

Cursor Class¶

Exceptions¶

Support Modules¶

`SECONDO` Commands¶

`SECONDO` Messages¶

`SECONDO` Parser¶

`SECONDO` Algebras¶

`SECONDO` Input Handler¶

`SECONDO` List Expression¶

Indices and tables¶

Table of Contents

This Page

PySECONDO - Python DB-API 2.0 interface for SECONDO¶

SECONDO-API Main Module¶

Connection Class¶

Basic Methods¶

Transaction Methods¶

Get-Methods¶

Cursor Class¶

Exceptions¶

Support Modules¶

SECONDO Commands¶

SECONDO Messages¶

SECONDO Parser¶

SECONDO Algebras¶

SECONDO Input Handler¶

SECONDO List Expression¶

Indices and tables¶

PySECONDO - Python DB-API 2.0 interface for `SECONDO`¶

`SECONDO`-API Main Module¶

`SECONDO` Commands¶

`SECONDO` Messages¶

`SECONDO` Parser¶

`SECONDO` Algebras¶

`SECONDO` Input Handler¶

`SECONDO` List Expression¶