pypz.core.specs.instance module

class pypz.core.specs.instance.Instance(name: str = None, *args, **kwargs)

Bases: Generic[NestedInstanceType], RegisteredInterface, ABC

This class represents the instance specs that serves as base for all the other models. It abstracts all common features and functionalities that is required to maintain the actual instances like parameters or even multi level nested instances.

Parameters:

name – name of the instance, if not provided, it will be attempted to deduce from the variable’s name
nested_instance_type – type of the expected nested instances

__context: Instance: Reference to the context aka parent object. Derived automatically in the override implementation of __setattr__.

__depends_on: set: Set of other instances that is this instance depending on. Note however that the type of the dependencies are checked dynamically in runtime, since dependencies can only be defined on the same type of instance.

__expected_parameters: dict[str, ExpectedParameter]: Map of expected parameters defined as descriptor of the class. Key is the name of the parameter, value is the parameter descriptor. Used to check, if an expected (described) parameter value shall be set upon instance parameter setting.

__full_name: str: Full name of the instance which uniquely identifies it up to its topmost context. For example, if an instance A has a parent context B, which has a parent context C, then the full name of A is ‘C.B.A’. This value is calculated and the result is stored after the first calculation to avoid recalculation every time.

__nested_instance_type: Type[NestedInstanceType] | None: Stores the specified type of the nested instances. This is required to be able to discover those instances

__nested_instances: dict[str, NestedInstanceType]: This dictionary holds all the instances that are nested in the context of this instance object

__parameters: InstanceParameters: The interpreted instance parameters i.e., cascading and templates are interpreted

__reference: Reference to the reference instance. If specified, then some instance internal configuration related attributes will refer to the attributes of the reference instance.

__simple_name: str: Name of the instance, which is represented by the object created from the implementation class. If not provided and there is a parent context, then the parent context will use the name of the variable.

__spec_classes: set: Set of specs classes that are in the class hierarchy i.e., which specs classes are contributing to the implementation of this class

__spec_name: str: The name of the spec constructed of module and qualified class name. Notice that we separate the module name and the class name so that we can identify them at loading by name.

_abc_impl = <_abc._abc_data object>

abstract _on_error(source: Any, exception: Exception) → None: This method can be implemented to react to error events during execution. The error itself may come from arbitrary sources.

abstract _on_interrupt(system_signal: int = None) → None

This method can be implemented to react to interrupt signals like SIGINT, SIGTERM etc. The specs implementation can then execute interrupt logic e.g., early termination of loops.

Parameters:: system_signal – id of the system signal that causes interrupt

static create_from_dto(instance_dto: InstanceDTO, *args, **kwargs) → Instance

Creates an instance object from the DTO representation. It is capable to retrieve and load specified classes and to update created instances according to the DTO.

Parameters:: instance_dto – instance DTO
Returns:: instance object specified by the DTO

static create_from_string(source, *args, **kwargs) → Instance

Helper method to provide the functionality to create an instance from a json model specified either as string or as dict.

Parameters:: source – model as string
Returns:: instance object specified by the DTO

depends_on(instance: Instance) → None

Specify dependency instances of the actual instance. The following prerequisites shall be considered: - dependency must be the same specs type - dependency can be defined only in the same parent context The same parent context means that if there is an operatorA with plugin1 and plugin2 and an operatorB with plugin3, then only plugin1 and plugin2 can express dependencies to each other, since plugin3 is in another operator.

Parameters:: instance – dependency instance

get_context()

get_dto() → InstanceDTO

Converts the instance information into the corresponding Data Transfer Object (DTO)

Returns:: DTO from instance

get_expected_parameters() → dict | str

Returns all the expected parameters as dictionary. Each parameter has the following types:

result = {
    'name': {
        'type': 'str | int | float | set | list | dict | type(None)',
        'required': 'True | False',
        'description': 'str',
        'currentValue': 'str | int | float | set | list | dict | None'
    }
}

get_full_name() → str

get_missing_required_parameters() → dict[str, set[str]]

This method returns the missing required parameters recursively for all nested instances, hence all parameters will be collected in the current scope.

Returns:: dict, where key is the instance’s full name and value is a list of the names of the missing required parameters. If no missing required parameters, then an empty dict will be returned

get_parameter(name: str)

get_simple_name() → str

has_parameter(name: str) → bool

set_parameter(name: str, value: Any) → None

Parameter setter method, which interprets the templates and handles cascading parameters. One can ignore setting values for existing parameters via the provided flag.

Parameters:

name – parameter name
value – parameter value

set_parameters(parameters: dict) → None

Convenience parameter setter method for dicts, where all key value pair will be set separately

Parameters:: parameters – parameter dict

update(source: InstanceDTO | dict | str) → None

This method allows to update certain attributes of the instance based on the provided DTO. All attributes can be updated here as well, for which a setter exists, in addition one can inject additional nested instances or update existing.

Parameters:: source – json string, dict or DTO

class pypz.core.specs.instance.InstanceGroup

Bases: ABC

This class provides methods to access instance group related information. It can be implemented on different instance level, since a group might have different meaning on top level and on nested level.

_abc_impl = <_abc._abc_data object>

abstract get_group_index() → int

abstract get_group_name() → str | None

abstract get_group_principal() → Instance | None

abstract get_group_size() → int

abstract is_principal() → bool

class pypz.core.specs.instance.InstanceInitInterceptor(name, bases, namespace, /, **kwargs)

Bases: ABCMeta

This metaclass has the responsibility to intercept the instance initialization and so ensure that instance name and context objects are resolved automatically, before executing the __init__ of the instance. For more information refer to InterceptedInstance.

class pypz.core.specs.instance.InterceptedInstance(instance_name: str, context_class: Type[Instance], *args, **kwargs)

Bases: object

This class represents an intercepted instance at init. Part of the feature set is that if you don’t provide a name to an instance in its parent context, then its variable name is used as name. However, since there is no convenient way to provide the name of the variable holding the reference to the object into the object’s __init__, we need to work around this. The concept is that we intercept the instance creation, if no name has been provided through a metaclass. This metaclass creates an InterceptedInstance object instead of the real object. As next step, the Instance’s __setattr__ is modified (since that is the only place, where the variable name is given) so that, if it sees that an InterceptedInstance is to be assigned, it instead creates the original object, but this time with the name and the context object already provided. Hence, all the (nested) instances’ __init__ will be performed with already available name and context.

class pypz.core.specs.instance.InterceptedInstanceType

This type definition is necessary to allow proper typehints of the objects created by the Instance class with the custom metaclass. Without this type definition no hints will be given.

alias of TypeVar(‘InterceptedInstanceType’)

class pypz.core.specs.instance.RegisteredInterface

Bases: object

This is a marker interface with the sole purpose to identify the native specs interfaces. It is necessary to separate the implemented and multiple inherited classes from the actual plugin interfaces.