ae.sys_core

dynamic system configuration, initialization and connection

this module allows the dynamic (data-driven) configuration and connection of your application to all their needed external systems (like servers, databases, cloud stores, …).

system classes

the SystemBase class represents a single system. the creation of instances of this class is automatically done dynamically by the (mostly unique) instance of the class UsedSystems.

each instance of SystemBase is using a system-specific connector class to establish an internal connection to the represented system. for the implementation of a connector class, simply inherit from the abstract base class SystemConnectionBase - also provided by this module.

by creating an instance of the class UsedSystems you get a dictionary-like object with all the properties for each configured system. the items of this dict are instances of the class SystemBase.

dynamic system properties

the properties of your systems are specified within config files as variables.

the only mandatory config variable is a dict with the name availableSystems, with the system-ids as dict keys. the items of this dict are also dicts with string keys and called system configs. only the key name is mandatory in these system configs. the following system config dict keys are supported:

name : system name (long name of system-id, only used for repr() and debugging).
credential_keys : List[str] of credential keys needed to connect to this system.
feature_keys : List[str] of feature keys supported by this system.
available_rec_types : Dict[str, str] of supported rec type ids and names.
connector_module : name of the connector package.module (def=ae.sys_data_<system-id-in-lower-case>).
connector_class : name of the connector class (def=<system-id>SysConnector),

the value of each credential and feature key gets automatically dynamically read from a config option or variable. the name of these config options/variables consists of the key string, prefixed with the system id in lower case. so if e.g. the value of a credential key ‘User’ for the system id ‘Abc’ will be loaded from a config variable with the name abcUser. all the credential and feature config variables can be either stored in the main or the systems section of the config files - see also config_value().

an example of a system configuration you find in the config file test.cfg, situated in the tests folder of this package.

multiple system configurations

to provide multiple system configurations for the same application (suite) you can use individual config files for each application instance with a separate config file (see .sys_env<SYS_ENV_ID>.cfg here).

Module Attributes

SYS_SECTION_NAME

section name for system config variables

Functions

config_value(var_name, console_app)

determine system configuration setting value from application config options/variables.

Classes

`SystemBase`(sys_id, console_app, credentials)	instance represents an external system, including their system properties and a connection object.
`SystemConnectorBase`(system)	abstract system connector base class - sub-class establishes the connection to an external system.
`UsedSystems`(console_app, *selected_systems, ...)	an instance of this class is keeping a dictionary of all the found and used systems of this application.

SYS_SECTION_NAME = 'aeSystems': section name for system config variables

config_value(var_name, console_app)[source]

determine system configuration setting value from application config options/variables.

Parameters:

var_name¶ (str) – config variable name. variable value gets searched in the application instance environment, first in the application config options, then in the application config variables (first within the section MAIN_SECTION_NAME/aeOptions and then within SYS_SECTION_NAME/aeSystems.
console_app¶ (ConsoleApp) – ConsoleApp instance of the application providing these config options/variables.

Return type:

Any

Returns:

config variable value if found else None.

class SystemBase(sys_id, console_app, credentials, features=(), rec_types=None)[source]

Bases: object

instance represents an external system, including their system properties and a connection object.

instances: int = 0

__init__(sys_id, console_app, credentials, features=(), rec_types=None)[source]

create new SystemBase instance.

Parameters:

sys_id¶ (str) – unique str to identify a system (also used as prefix/suffix).
console_app¶ (ConsoleApp) – ConsoleApp instance of the application using these systems.
credentials¶ (Dict[str, str]) – dict to access system, containing e.g. user name, password, token, dsn…
features¶ (Sequence[str]) – optional list with special features for this system (see SDF_* constants).
rec_types¶ (Optional[Dict[str, str]]) – optional dict of available record types for this system.

sys_id: system id

console_app: application instance and config environment

credentials: credentials to connect to this system

features: system specific features and configs

available_rec_types: Dict[str, str]: record types available in this system

connection: Any: object with opt. connect() and disconnect()/close() methods

conn_error: str: error message of last system access or dis-/connect

__repr__()[source]

representation string of this SystemBase instance.

Return type:: str
Returns:: representation string of this instance.

connect(sys_config, force_reconnect=False)[source]

connect this instance to his system using a system connector class.

Parameters:

sys_config¶ (Dict[str, str]) – dict with the dynamic config properties of this system.
force_reconnect¶ (bool) – optional; pass True to force re-connection (even if self.connection is already initialized).

Return type:

str

Returns:

error message or empty string in case of no errors while re-connecting.

disconnect()[source]

disconnect this external system.

Return type:: str
Returns:: error message string or empty string if no errors occurred on disconnection.

class SystemConnectorBase(system)[source]

Bases: ABC

abstract system connector base class - sub-class establishes the connection to an external system.

instances: int = 0

__init__(system)[source]

create new SystemBase instance.

Parameters:: system¶ (SystemBase) – instance of SystemBase class that is representing the system using this connection.

system: SystemBase instance

console_app: application instance and config environment

last_err_msg: str: last system connection error message(s)

__repr__()[source]

representation string of this SystemBase instance.

Return type:: str
Returns:: representation string of this instance.

abstract connect()[source]

abstract method - raising NotImplementedError, so has to be implemented by the sub-class.

Return type:: str

class UsedSystems(console_app, *selected_systems, **entered_credentials)[source]

Bases: OrderedDict

an instance of this class is keeping a dictionary of all the found and used systems of this application.

the keys of this dictionary-like class are the system ids of your application. the items are instances of the SystemBase class.

each instance is providing additionally the following instance attributes:

console_app - instance of the ConsoleApp class that is using these systems.
available_systems - system properties loaded from config files.

all the system-specific properties are stored within the SystemBase instances.

__init__(console_app, *selected_systems, **entered_credentials)[source]

create new instance of UsedSystems.

Parameters:

console_app¶ (ConsoleApp) – ConsoleApp instance of the application using these systems.
selected_systems¶ (str) – optional iterable of system id strings of the available systems that have to be initialized for the app specified by the console_app argument. if no system id get passed then all available systems will be initialized from the config variable availableSystems.
entered_credentials¶ (str) – optional dict of credentials entered by a user at run-time (overwriting the values set in the related config variable availableSystems). the keys of this dictionary starting with the system id in lower case, followed by one of the key strings specified in the credential_keys config list (see dynamic system properties).

_load_merge_cred_feat(entered_credentials)[source]

load and initialize all used system configs and merge entered credentials into it.

Parameters:: entered_credentials¶ (Dict[str, str]) – passed over unchanged from UsedSystems - see entered_credentials.

_add_system(sys_id, credentials, features=())[source]

add new SystemBase instance to this UsedSystems instance.

Parameters:

sys_id¶ (str) – system id.
credentials¶ (Dict[str, str]) – credentials of the new system to add.
features¶ (Sequence[str]) – optional list with special features for this system (see SDF_* constants).

connect(force_reconnect=False)[source]

connect all the selected systems of this instance.

Parameters:: force_reconnect¶ (bool) – optional; pass True to force re-connection (even if self.connection is initialized).
Return type:: str
Returns:: error message or empty string in case of no errors while re-connecting.

disconnect()[source]

disconnect all available and already connected systems.

Return type:: str
Returns:: error message string or empty string if no errors occurred on disconnection.