multilevel_py package

Submodules

multilevel_py.clabject_prop module

class multilevel_py.clabject_prop.AssociationProp(prop_name: str, steps_to_instantiation: int, steps_from_instantiation: Union[int, float], constraints: List[multilevel_py.constraints.PropValueConstraint] = [], is_final: bool = False, prop_value: Optional[Any] = None, default_value: Optional[Any] = None)

Bases: multilevel_py.clabject_prop.BaseClabjectProp

A Property of a clabjec that is meant to hold an associated clabject

get_viz_value_str()

Returns: a concrete syntax friendly string for the given prop value

type_specific_constraints()

Declare type specific constraints that will be appended to self.constraints

class multilevel_py.clabject_prop.BaseClabjectProp(prop_name: str, steps_to_instantiation: int, steps_from_instantiation: Union[int, float], constraints: List[multilevel_py.constraints.PropValueConstraint] = [], is_final: bool = False, prop_value: Optional[Any] = None, default_value: Optional[Any] = None)

Bases: object

Base class of a ClabjectProp, i.e. an enhanced attribute that is capable of “deferred instantiation”

__init__(prop_name: str, steps_to_instantiation: int, steps_from_instantiation: Union[int, float], constraints: List[multilevel_py.constraints.PropValueConstraint] = [], is_final: bool = False, prop_value: Optional[Any] = None, default_value: Optional[Any] = None)

Parameters

• prop_name – The name of the property, which must be unique for the given clabject

• steps_to_instantiation – The number of steps until the property is instantiated, i.e. assigned with a value. A value of 1 means that the property has to be instantiated in the next instantiation step.

• steps_from_instantiation – The number of steps the property continues to exist down the intantiation chain after being instantiated. If set to 0 the property appears only at the clabject it was instantiated on. If set to math.inf it is visible for all direct and indirect instances down the instantiation hierarchy.

• constraints – A List of PropValueConstraints that restrict the space of acceptable property values. A value is only set or updated if it passes through all constraints, otherwise a exceptions.ConstraintViolationException is thrown

• is_final – Indicating whether the property can be changed after its first instantiation.

• prop_value – The value that is assigned to the property during an instantiation step. Can be any python object including functions.

• default_value – optional default_value of the property, used at instantiation if no prop_value is provided

abstract get_viz_value_str() → str

Returns

a concrete syntax friendly string for the given prop value

abstract type_specific_constraints() → List[multilevel_py.constraints.PropValueConstraint]

Declare type specific constraints that will be appended to self.constraints

class multilevel_py.clabject_prop.CollectionDescription(min_max: Tuple[int, int] = (), member_value_constr=None)

Bases: object

Defines a collection property in terms of multiplicity and collection member constraints

__init__(min_max: Tuple[int, int] = (), member_value_constr=None)

Parameters

• min_max – A tuple with defining the min and max number of collection members (inclusive logic)

• member_value_constr – A PropValueConstraint that is applied on all collection members

class multilevel_py.clabject_prop.CollectionProp(prop_name: str, steps_to_instantiation: int, steps_from_instantiation: Union[int, float], constraints: List[multilevel_py.constraints.PropValueConstraint] = [], is_final: bool = False, prop_value: Optional[Any] = None, default_value: Optional[Any] = None, collection_desc: Optional[multilevel_py.clabject_prop.CollectionDescription] = None)

Bases: multilevel_py.clabject_prop.BaseClabjectProp

A property of a clabject that is meant to hold a collection, i.e. a multi-value property of a Clabject

get_viz_value_str()

Returns: a concrete syntax friendly string for the given prop value

type_specific_constraints()

Declare type specific constraints that will be appended to self.constraints

class multilevel_py.clabject_prop.MethodProp(prop_name: str, steps_to_instantiation: int, steps_from_instantiation: Union[int, float], constraints: List[multilevel_py.constraints.PropValueConstraint] = [], is_final: bool = False, prop_value: Optional[Any] = None, default_value: Optional[Any] = None)

Bases: multilevel_py.clabject_prop.BaseClabjectProp

A property of a clabject that is meant to hold a method object

get_viz_value_str()

Returns: a concrete syntax friendly string for the given prop value

type_specific_constraints()

Declare type specific constraints that will be appended to self.constraints

class multilevel_py.clabject_prop.SimpleProp(prop_name: str, steps_to_instantiation: int, steps_from_instantiation: Union[int, float], constraints: List[multilevel_py.constraints.PropValueConstraint] = [], is_final: bool = False, prop_value: Optional[Any] = None, default_value: Optional[Any] = None)

Bases: multilevel_py.clabject_prop.BaseClabjectProp

A property of a Clabject, that is meant to hold a simple (single primitive) value

get_viz_value_str()

Returns: a concrete syntax friendly string for the given prop value

type_specific_constraints()

Declare type specific constraints that will be appended to self.constraints

class multilevel_py.clabject_prop.StateConstraintProp(prop_name: str, steps_to_instantiation: int, steps_from_instantiation: Union[int, float], constraints: List[multilevel_py.constraints.PropValueConstraint] = [], is_final: bool = False, prop_value: Optional[Any] = None, default_value: Optional[Any] = None)

Bases: multilevel_py.clabject_prop.BaseClabjectProp

A property of a Clabject, that is meant to hold a StateConstraint

get_viz_value_str()

Returns: a concrete syntax friendly string for the given prop value

type_specific_constraints()

Declare type specific constraints that will be appended to self.constraints

multilevel_py.constraints module

class multilevel_py.constraints.BaseConstraint(name: str, violation_reason='')

Bases: object

Abstract Base of all kind of clabject constraints

class multilevel_py.constraints.ClabjectStateConstraint(name: str, eval_clabject_func: Callable[[Any], str])

Bases: multilevel_py.constraints.BaseConstraint

A callable constraint that is evaluated on the current clabject state

__init__(name: str, eval_clabject_func: Callable[[Any], str])

Parameters

• name – The name of the constraint

• eval_clabject_func – an evaluation func with of the following structure: Callable(current_clabject) -> str

class multilevel_py.constraints.ConstrViolationDictFactory

Bases: collections.defaultdict

call ConstrViolationsFactory(list) to create dict like objects

add_violations(violations: dict) → None

Parameters

violations – a dict with structure <prop_name: str> => <violation_reason: str>

Returns

Nothing, updates the violationDict object

class multilevel_py.constraints.PropValueConstraint(name: str, eval_value_func: Callable[[Any], str], eval_on_init: bool)

Bases: multilevel_py.constraints.BaseConstraint

A callable constraint imposed on the values of clabject props

__init__(name: str, eval_value_func: Callable[[Any], str], eval_on_init: bool)

Parameters

• name – the name of the constraint

• eval_value_func – an evaluation function, that returns an empty string for valid prop values and a non empty string for prop values that violate the constraint

• eval_on_init – a value indicating whether the constr should be evaluated on (re) init

class multilevel_py.constraints.ReInitPropConstr(del_constr: List[multilevel_py.constraints.PropValueConstraint] = [], add_constr: List[multilevel_py.constraints.PropValueConstraint] = [])

Bases: object

__init__(del_constr: List[multilevel_py.constraints.PropValueConstraint] = [], add_constr: List[multilevel_py.constraints.PropValueConstraint] = [])

Forces the reinitialisation of a property value under updated constraints, if set on a clabject via multilevel_py.core.MetaClabject.require_re_init_on_next_step()

Parameters

• del_constr – list of constraints to remove for the next re instantiation of the prop

• add_constr – list of constraints to validate for the next instantiation step

multilevel_py.constraints.create_violated_constraint_dict()

Returns

an empty constraint_violation dict

multilevel_py.constraints.eval_negative_value_func(value) → str

multilevel_py.constraints.prop_constraint_and_functional(constraint_a: multilevel_py.constraints.PropValueConstraint, constraint_b: multilevel_py.constraints.PropValueConstraint, eval_on_init=False)

Parameters

• constraint_a – the fst constraint

• constraint_b – the snd constraint

• eval_on_init – (bool) value indicating whether the constr should be evaluated on (re) init

Returns

a combined PropValue Constraint, in which both constraint_a, constraint_b must be fulfilled

multilevel_py.constraints.prop_constraint_collection_member_functional(member_constr_func: multilevel_py.constraints.PropValueConstraint, filter_func: Optional[Callable[[Collection], Collection]] = None, eval_on_init=True)

Generates a PropValueConstraint that is applied on (selected) members of a collection prop value

Parameters

• member_constr_func – A PropValueConstraint that each collection member must satisfy

• filter_func – A filter function that takes the whole collection and returns only the members, the member_constr_func should be checked on

• eval_on_init – value indicating whether the constr should be evaluated on (re) init

Returns

a parameterised, callable PropValueConstraint object

multilevel_py.constraints.prop_constraint_collection_multiplicity_functional(min_member_number: int, max_member_number: int, eval_on_init=False)

multilevel_py.constraints.prop_constraint_is_th_order_instance_of_clabject_set_functional(expected_values: set, order: int = 1, eval_on_init=True)

Generates a PropValueConstraint that checks whether the given value is an (given) order instance of one of the specified clabjects

Parameters

• expected_values – a set of clabjects

• order – an integer, describing how often the instance_of operation should be applied

• eval_on_init – value indicating whether the constr should be evaluated on (re) init

Returns

a parameterised, callable PropValueConstraint object

multilevel_py.constraints.prop_constraint_ml_instance_of_th_order_functional(expected_clabject_type, instantiation_order: Optional[Union[int, Tuple[int, int]]] = None, eval_on_init=True)

Generate prop value constraints using the instance_mechanism provided by the multilevel_py package

Parameters

• expected_clabject_type – the expected_clabject_type values are supposed to be instances of

• instantiation_order – the number of permissible instantiation steps between value and expected_clabject_type, if None instances of any order are allowed, if int only this exact number of instantiation steps is tolerated, if (min, max) tuple the inclusive interval of integers between min and max is tolerated

• eval_on_init – value indicating whether the constr should be evaluated on (re) init

Returns

a parameterised, callable PropValueConstraint object

multilevel_py.constraints.prop_constraint_optional_value_functional(constraint: multilevel_py.constraints.PropValueConstraint)

Parameters

constraint – a PropValueConstraint

Returns

a relaxed constraint of the given PropValueConstraint by tolerating also values of None as valid init value

multilevel_py.constraints.prop_constraint_or_functional(constraint_a: multilevel_py.constraints.PropValueConstraint, constraint_b: multilevel_py.constraints.PropValueConstraint)

Parameters

• constraint_a – the fst constraint

• constraint_b – the snd constraint

Returns

a combined PropValueConstraint, in which at least one of constraint_a and constraint_b must be fulfilled

multilevel_py.constraints.prop_constraint_py_isinstance_functional(expected_type, eval_on_init=True) → multilevel_py.constraints.PropValueConstraint

Generate prop value constraints using Pythons traditional isinstance facility

Parameters

• expected_type – the expected type or class object

• eval_on_init – value indicating whether the constr should be evaluated on (re) init

Returns

a parameterised, callable PropValueConstraint object

multilevel_py.constraints.prop_constraint_value_in_set_functional(expected_set: set, eval_on_init=True)

Generate PropValueConstraint that evaluates whether the given value is in the expected set

Parameters

• expected_set – a set of permitted values

• eval_on_init – (bool) value indicating whether the constr should be evaluated on (re) init

Returns: a callable prop_constr instance

multilevel_py.constraints.prop_constraint_value_is_collection_functional(eval_on_init=True)

Generates a PropValueConstraint that checks whether the property value is a valid collection

Parameters

eval_on_init – value indicating whether the constr should be evaluated on (re) init

multilevel_py.constraints.prop_value_can_be_bound_as_method_functional(eval_on_init=True)

Parameters

eval_on_init – value indicating whether the constr should be evaluated on (re) init

Returns

a PropValueConstraint that determines whether the provided value can serve as method

multilevel_py.core module

class multilevel_py.core.ClabjectPropDict

Bases: Dict[str, multilevel_py.clabject_prop.BaseClabjectProp]

Responsible for updating the clabject props in the __ml_props__ attribute of a clabject

add_prop_constraint(prop_name: str, constraint: multilevel_py.constraints.PropValueConstraint) → None

Add a PropValueConstraint for an existing property

Parameters

• prop_name – the name of the prop the constraint is imposed on

• constraint – a PropValueConstraint Object

Returns: Nothing, updates the state of ClabjectPropDict

adjust_instantiation_speed(speed_adjustments: Dict[str, int])

Adjust the number of instantiation steps for a property to become instantiated from the perspective of the current clabject

Parameters

speed_adjustments – dict with structure <prop_name:str> => <speed_adj: int>: if integer < 0 acceleration of prop instantiation, if the acceleration leads to number_to_instantiation_steps < 1, the effect is that the prop has to be instantiated with the next instantiation step, if integer > 0 the instantiation of property deferred by this number of steps

Returns

Updates the State of the ClabjectPropDict

apply_instantiation_step(init_props: dict, speed_adjustments: dict)

Implements deep instantiation mechanism

Parameters

• init_props – the props to be instantiated at this instantiation - step given as prop: value pairs inside a dictionary

• speed_adjustments – prop_name : integer, see adjust_instantiation_speed()

Returns

A ClabjectPropDict object with initialised props and decremented instantiation counters if no Exception is raised

check_prop_in_keys(prop_name: str) → None

check_violated_prop_constraints(prop_name: Optional[str] = None, potential_value=None, init_only=True)

Check the constraints for a specific prop or for all props if no prop_name is provided

Parameters

• prop_name – The property to check

• potential_value – the provided value due to be instantiated, if not provided the current prop_value is checked

• init_only – Evaluate only the constraints that have eval_on_init flag set

Returns

ConstrViolationDict

define_props(new_props: List[multilevel_py.clabject_prop.BaseClabjectProp]) → None

Define props on the current clabject

Parameters

new_props – a list of new properties

Returns

Nothing, manipulates the objects state, i.e. the current __ml_props__

next_prop_dict()

Create a deep copy of the ClabjectPropDict of the current clabject. Chosen on copy rather than reference semantic to enable independent state evolution

Returns

a fresh ClabjectPropDict copy

class multilevel_py.core.MetaClabject(name, bases, attr_dict)

Bases: type

The python metaclass that defines the behaviour of clabjects

add_prop_constraint(constraint, prop_name: Optional[str] = None) → None

Delegates to ClabjectPropDict.add_prop_constraint()

adjust_instantiation_speed(speed_adjustments: Dict[str, int])

Delegates to ClabjectPropDict.adjust_instantiation_speed()

check_prop_constraints(prop_name: Optional[str] = None, potential_value=None, init_only=False)

Delegates to ClabjectPropDict.check_violated_prop_constraints()

check_state_constraints() → dict

Checks all ‘active’, i.e. instantiated ClabjectStateProps on the current clabject

Returns

a dictionary with the structure <prop_name> => <violation_reason>

define_props(new_props=typing.List[multilevel_py.clabject_prop.BaseClabjectProp])

Delegates to ClabjectPropDict.define_props()

get_framework_attrs()

Returns

all framework attributes of clabjects, that are not as domain related ClabjectProps managed by the internal ClabjectDict

instance_of()

Returns

The ‘ontological’ meta clabject of the current clabject. The term ontological should indicate that this relation is related to the respective target domain abstraction.

require_re_init_on_next_step(prop_name: Optional[str] = None, re_init_prop_constr: Optional[multilevel_py.constraints.ReInitPropConstr] = None) → None

Require that a given property gets re-reinitialised on the next instantiation step

Parameters

• prop_name – the prop name

• re_init_prop_constr – an instance of ReInitPropConstr

Returns

Nothing, updates the state of the internal __ml_props__ and thus changes the semantics of the next instantiation

viz_name_str()

multilevel_py.core.bind(instance, func, as_name=None)

Bind a function to an object, i.e. make it a method of the object

Parameters

• instance – The object to which the function should be bound

• func – The function to be bound, should accept the instance as first argument, i.e. “self

• as_name – An optional new alias for the function

Returns

the bound method object

multilevel_py.core.create_clabject_prop(n: str, t: int, f, c: List[Callable[[Any], bool]] = [], i_f: bool = True, i_m: bool = False, i_sc: bool = False, i_assoc: bool = False, coll_desc: Optional[tuple] = None, v=None, d=None)

Stable Interface for the creation of clabject properties, the suitable ClabjectProp class is chosen in dependence of the given attributes, see clabject_prop.BaseClabjectProp.__init__()

Parameters

• n – shorthand for prop_name

• t – shorthand for steps_to_instantiation

• f – shorthand for steps_from_instantiation, integer or * (str) for remaining infinite may steps

• c – shorthand for constraints

• i_f – shorthand for is_final

• i_m – shorthand for is_method

• i_assoc – shorthand for is_association

• i_sc – shorthand for is_stateConstraint

• coll_desc – (min, max, member_constr) tuple that is translated to a CollectionDescription object

• v – shorthand for prop_value

• d – shorthand for default_value

Returns

An obj which is an instance of a class that inherits from BaseClabjectProp

multilevel_py.core.is_clabject(obj: Any) → bool

Determine whether a given object is a clabject

Parameters

obj – the object to check

Returns

a boolean value that indicates whether the predicate is fulfilled for the given obj

multilevel_py.exceptions module

exception multilevel_py.exceptions.ChangeFinalPropException(prop_name: str)

Bases: Exception

exception multilevel_py.exceptions.ClabjectDeclaredAsInstanceException(obj)

Bases: Exception

exception multilevel_py.exceptions.ConstraintViolationException(violated_constraints: dict)

Bases: Exception

__init__(violated_constraints: dict)

Parameters

violated_constraints – a nested dict of the following structure <constr_holder_name:str> => <violated_constraints: dict>

exception multilevel_py.exceptions.InconsistentCreateClabjectPropArgsException(ex_msg)

Bases: Exception

exception multilevel_py.exceptions.InvalidInstantiationOrderException(provided_instantiation_order)

Bases: Exception

exception multilevel_py.exceptions.InvalidMultiplicityTupleException(provided_tuple)

Bases: Exception

exception multilevel_py.exceptions.InvalidPropValueConstraintException(constr)

Bases: Exception

exception multilevel_py.exceptions.NotAClabjectException(obj)

Bases: Exception

exception multilevel_py.exceptions.PropsAlreadyDefinedException(already_defined_props: Set[str])

Bases: Exception

exception multilevel_py.exceptions.ReInitFinalPropException(prop_name: str)

Bases: Exception

exception multilevel_py.exceptions.ReInitVanishingPropException(prop_name: str)

Bases: Exception

exception multilevel_py.exceptions.TypeSpecificConstraintRemovalException(constr)

Bases: Exception

exception multilevel_py.exceptions.UndefinedPropsException(undefined_props: Set[str])

Bases: Exception

exception multilevel_py.exceptions.UnduePropInstantiationException(prop_name: str, later_steps_number: int)

Bases: Exception

exception multilevel_py.exceptions.UninitialisedPropException(prop_name: str)

Bases: Exception

multilevel_py.viz module

multilevel_py.viz.determine_level_recursive(clabject) → int

Parameters

clabject – a clabject obj., i.e. a class of the core.MetaClabject python metaclass

Returns

The level of the clabject, i.e. the maximum number of instantiation steps of al instantiation chains that originate from the given clabject

multilevel_py.viz.viz_classification_hierarchy(start_clabject, output_dir: Optional[pathlib.Path] = None, output_name: Optional[str] = None, render=True, by_level=False, hidden_root=False, show_hierarchy_name=False, format='png', font='arial', fontsize='12')

Parameters

• start_clabject – a clabject obj., i.e. a class of the core.MetaClabject python metaclass

• output_dir – a Path obj. that represents the desired output viz directory

• output_name – the name of the generated plot

• render – boolean value indicating whether the final dot object should be rendered into output dir

• by_level – use an breadth-first recursion, i.e. level by level through the given classification hierarchy

• hidden_root – boolean value indicating whether the start_clabject should be rendered

• show_hierarchy_name – boolean value indicating whether the plot should include the hierarchy name (name of start_clabject)

• format – a str specifying the given desired output format (“pdf”, “png”, “svg”, “jpg”)

• font – a str specifying the desired font-family

• fontsize – a str specifying the desired font-size (as integer value)

Returns

a dot object constructed by traversing the classification hierarchy

Module contents