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 in self.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.

root_hook_fallback(hook: Hook) Any | None

May return a fallback value for getting of root hooks. The default implementation returns None, may be overridden in subclasses.