mafw.processor.parameters

Parameter descriptors for the Processor framework.

This module defines the parameter descriptor system that underpins all Processor subclass configuration. It provides:

PassiveParameter — the private storage backing each parameter.
ActiveParameter — the public descriptor interface for declaring processor parameters in a class body.
ensure_parameter_registration() — a decorator guaranteeing parameters are registered before access.
ParameterType — a generic type variable binding the parameter value.
_ParameterRegistry — the ordered mapping of parameter names to their descriptors.

The helper functions _copy_parent_parameter_definitions(), _ensure_parameter_definitions(), and _validate_filter_schema() are used by the metaclass to finalise parameter bookkeeping at class-creation time.

Added in version 2.3: Extracted from the monolithic processor.py module for improved maintainability and focused testing.

Module Attributes

ParameterType

Generic variable type for the ActiveParameter and PassiveParameter.

Functions

ensure_parameter_registration(func)

Decorator to ensure that processor parameters are registered before func executes.

Classes

`ActiveParameter`(name[, value, default, help_doc])	The public interface to the processor parameter.
`PassiveParameter`(name[, value, default, ...])	An helper class to store processor parameter value and metadata.

class mafw.processor.parameters.ActiveParameter(name: str, value: ParameterType | None = None, default: ParameterType | None = None, help_doc: str = '')[source]

Bases: Generic[ParameterType]

The public interface to the processor parameter.

The behaviour of a processor.Processor can be customised by using processor parameters. The value of these parameters can be either set via a configuration file or directly when creating the class.

If the user wants to benefit from this facility, they have to add in the instance of the Processor subclass an ActiveParameter instance in this way:

class MyProcessor(Processor):

    # this is the input folder
    input_folder = ActiveParameter('input_folder', Path(r'C:\'), help_doc='This is where to look for input files')

    def __init__(self, *args, **kwargs):
        super().__init(*args, **kwargs)

        # change the input folder to something else
        self.input_folder = Path(r'D:\data')

        # get the value of the parameter
        print(self.input_folder)

The ActiveParameter is a descriptor, it means that when you create one of them, a lot of work is done behind the scene.

In simple words, a processor parameter is made by two objects: a public interface where the user can easily access the value of the parameter and a private interface where all other information (default, documentation…) is also stored.

The user does not have to take care of all of this. When a new ActiveParameter instance is added to the class as in the code snippet above, the private interface is automatically created and will stay in the class instance until the end of the class lifetime.

To access the private interface, the user can use the processor.Processor.get_parameter() method using the parameter name as a key.

The user can assign to an ActiveParameter almost any name. There are just a few invalid parameter names that are used for other purposes. The list of reserved names is available here. Should the user inadvertently use a reserved named, a ProcessorParameterError is raised.