The Plugin System
Note
The plugin system has drastically changed in Version 2.0. For the old version see here.
Plugin packages are mainly meant to provided model logic to PyRolL, which does only ship with most basic relations at its core. Simulating rolling processes is only possible by using plugin packages, without, PyRolL runs, of course, but the results are extremely rough estimations. Plugins for PyRolL work through hooks.
A hook is a attribute of a class resp. an object, whose value can be explicitly set or computed from a set of functions. A plugin can supply functions to hooks to represent a physical model approach. The user, however, can always override the function logic by defining a value on the object itself by classic attribute syntax.
Let’s give an example for clarification.
The Profile
class defines the hook Profile.flow_stress
, which represents the flow stress of the profile’s material.
class Profile(HookHost):
...
flow_stress = Hook[float]()
...
Classes using hooks have to be derived from HookHost
.
The Hook
instance is a descriptor providing logic and storage for a hooks value and functions.
It can be used as decorator for defining a function.
@Profile.flow_stress
def flow_stress1(self: Profile):
return 2 * self.strain
This function is now registered for calculating flow stresses of all profiles, if no explicit value is set.
The functions must have classic method signature, so the self
argument always refers to the actual object instance.
The functions registered are evaluated in reverse order of their registration, so the last registered is the first executed.
The first result other than None
is taken as the hook’s actual value.
The value is cached until the cache is cleared using the HookHost.clear_hook_cache()
method.
The user may override hook function evaluation totally by setting an explicit value at object creation…
profile = Profile.round(
...,
flow_stress=100e6,
...,
)
…or later using attribute syntax.
profile.flow_stress = 100e6
- class Hook(name=None, owner=None)
Descriptor yielding the value of a hook attribute if called on instance, or itself if called on class.
- __call__(func=None, tryfirst=False, trylast=False, wrapper=False)
Call self as a function.
- __delete__(instance: object) None
Deletes the value from the
__dict__
of the instance. Does not raise, if the value is not in the__dict__
.
- __get__(instance: None, owner: type) Hook[T]
- __get__(instance: HookHost, owner: type) T
Get the value of the hook if called on instance or the descriptor itself if called on class.
Hook value resolution is done in the following order: 1. explicit values (in
__dict__
) 2. cached values (in__cache__
) 3. from hook functions.Saves the value in
__cache__
if the value was determined from functions.- Raises:
AttributeError – if no value could be provided or if a RecursionError occurred during hook function calling
ValueError – if the resulting value was infinite (only for numeric values)
- __set__(instance: object, value: T) None
Saves a value to the
__dict__
of the instance.
- add_function(func, tryfirst=False, trylast=False, wrapper=False)
Add the given function to the internal function store.
- Returns:
the created HookFunction object
- get_result(instance) T | None
Get the first not
None
result of the functions inself.functions
or the cached value.
- remove_function(func: HookFunction)
Remove a function from the internal function store.
- Returns:
the underlying function object
- property functions: List[HookFunction]
List of functions stored in this instance and equally named instances in superclasses of its owner.
- property functions_gen: Generator[HookFunction, None, None]
Generator listing functions stored in this instance and equally named instances in superclasses of its owner.
- name
The name of the hook.
- owner
The owner class of the hook instance.
- property type
Returns the given generic attribute (the data type of the hook). :raises TypeError: if the instance was not created using a generic parameter (so
__orig_class__
was not set)
- class HookFunction(func, hook, tryfirst=False, trylast=False, wrapper=False)
Class wrapping a function used to yield the value of hooks. Instantiated commonly by use of a Hook instance as decorator on a function. You should not instantiate it yourself.
- Parameters:
func – the function
hook – the associated hook
tryfirst – whether to use this function with the highest priority
trylast – whether to use this function with the lowest priority
- __call__(instance)
Call the function as it were a method the provided instance.
- cycle
Cycle detection.
- function
The underlying function.
- hook
The hook the function is defined for.
- module
The module the function originates from.
- name
The name of the function.
- qualname
The qualified name of the function.
- property tryfirst
Whether to use this function with the highest priority.
- property trylast
Whether to use this function with the lowest priority.
- wrapper
Whether the hook function is a wrapper.
- class HookHost
A base class providing plugin functionality and some related convenience methods to a derived class.
- evaluate_and_set_hooks()
Evaluate functions of root hooks and set the results explicitly as attributes.
- classmethod extension_class(source: type)
Class decorator for adding new hook definitions to an existing HookHost.
- Returns:
the extended class (the reference to the source class is discarded)
- Raises:
TypeError – if the source class is itself derived from HookHost (error-prone)
- has_cached(name: str)
Checks whether a value is cached for the hook name.
- has_set(name: str)
Checks whether a value is explicitly set for the hook name.
- has_set_or_cached(name: str)
Checks whether a value is explicitly set or cached for the hook name.
- has_value(name: str)
Checks whether a value is available for the hook name.
- reevaluate_cache()
Clears the cache of hook function results.