Module

module

Base class for defining flepimop2 modules.

ModuleABC

Bases: ABC

Abstract base class for flepimop2 modules.

Attributes:

Name	Type	Description
module	str	The fully-qualified module name. Concrete subclasses may define this explicitly or provide a namespaced class keyword argument such as module="csv".
module_namespace	str | None	The flepimop2 namespace used to resolve short module names such as "csv" into fully-qualified paths.
options	dict[str, Any] | None	Optional dictionary of additional options the module exposes for flepimop2 to take advantage of.

__init_subclass__(**kwargs)

Ensure concrete subclasses define a valid module name.

This validation works for both plain Python and Pydantic-based subclasses. If module_namespace="..." or module="..." are supplied in the class definition, they are normalized before validation.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Additional keyword arguments passed to parent classes.	{}

Source code in src/flepimop2/module.py

def __init_subclass__(cls, **kwargs: Any) -> None:
    """
    Ensure concrete subclasses define a valid module name.

    This validation works for both plain Python and Pydantic-based subclasses.
    If `module_namespace="..."` or `module="..."` are supplied in the class
    definition, they are normalized before validation.

    Args:
        **kwargs: Additional keyword arguments passed to parent classes.

    """
    module_namespace = kwargs.pop("module_namespace", None)
    module = kwargs.pop("module", None)
    super().__init_subclass__(**kwargs)
    if module_namespace is not None:
        cls._apply_module_namespace(module_namespace)
    if module is not None:
        cls._apply_module_shortcut(module)
    if inspect.isabstract(cls) or cls.__name__.endswith("ABC"):
        return
    cls._validate_module_definition()

option(name, default=RaiseOnMissing)

Retrieve an option value by name, with an optional default.

Parameters:

Name	Type	Description	Default
name	str	The name of the option to retrieve.	required
default	Any	The default value to return if the option is not found. If not provided, defaults to RaiseOnMissing, which will cause a KeyError to be raised if the option is missing.	RaiseOnMissing

Returns:

Type	Description
Any	The value of the option if found, otherwise the default value.

Raises:

Type	Description
KeyError	If the option is missing and default is not provided.

Examples:

>>> from flepimop2.module import ModuleABC
>>> class MyModule(ModuleABC):
...     module = "my_module"
...     options = {"option1": 42}
>>> mod = MyModule()
>>> mod.option("option1")
42
>>> mod.option("option2", default="default_value")
'default_value'
>>> mod.option("option2")
Traceback (most recent call last):
    ...
KeyError: "Option 'option2' not found in module 'my_module'."
>>> class MyModuleWithMissingOption(ModuleABC):
...     module = "missing_opts"
>>> mod = MyModuleWithMissingOption()
>>> mod.option("option1", default="default_value")
'default_value'
>>> mod.option("option1")
Traceback (most recent call last):
    ...
KeyError: "Option 'option1' not found in module 'missing_opts'."

Source code in src/flepimop2/module.py

def option(self, name: str, default: Any = RaiseOnMissing) -> Any:  # noqa: ANN401
    """
    Retrieve an option value by name, with an optional default.

    Args:
        name: The name of the option to retrieve.
        default: The default value to return if the option is not found. If
            not provided, defaults to `RaiseOnMissing`, which will cause a
            `KeyError` to be raised if the option is missing.

    Returns:
        The value of the option if found, otherwise the default value.

    Raises:
        KeyError: If the option is missing and `default` is not provided.

    Examples:
        >>> from flepimop2.module import ModuleABC
        >>> class MyModule(ModuleABC):
        ...     module = "my_module"
        ...     options = {"option1": 42}
        >>> mod = MyModule()
        >>> mod.option("option1")
        42
        >>> mod.option("option2", default="default_value")
        'default_value'
        >>> mod.option("option2")
        Traceback (most recent call last):
            ...
        KeyError: "Option 'option2' not found in module 'my_module'."
        >>> class MyModuleWithMissingOption(ModuleABC):
        ...     module = "missing_opts"
        >>> mod = MyModuleWithMissingOption()
        >>> mod.option("option1", default="default_value")
        'default_value'
        >>> mod.option("option1")
        Traceback (most recent call last):
            ...
        KeyError: "Option 'option1' not found in module 'missing_opts'."

    """
    opts = self.options or {}
    if name not in opts and isinstance(default, RaiseOnMissingType):
        msg = f"Option '{name}' not found in module '{self.module}'."
        raise KeyError(msg)
    return opts.get(name, default)