mafw.processor.path_types

Path-typing helpers for processor parameters.

Author:

Bulgheroni Antonio (antonio.bulgheroni@ec.europa.eu)

Description:

Classify Path processor parameters so the steering GUI can offer the right browse dialog (folder, existing file, or new file). The module defines the public PathRole enum and three ergonomic aliases — DirectoryPath, InputFilePath, and OutputFilePath — that expand to Annotated[Path, ...] while keeping the runtime type a plain Path.

The module imports only pathlib, enum, and typing; it must stay importable in a headless, PySide6-free environment so that processors can annotate parameters without any GUI dependency.

Added in version 2.4.

Module Attributes

DirectoryPath	Ergonomic alias for a directory path parameter.
InputFilePath	Ergonomic alias for an input (existing) file path parameter.
OutputFilePath	Ergonomic alias for an output (not-yet-existing) file path parameter.

Functions

is_path_type(annotation)	Return whether the annotation denotes Path or a subclass.
path_role_of(annotation)	Return the PathRole marker on a path annotation, or INPUT_FILE.

Classes

PathRole(*values)

Classify how a Path parameter should be browsed in the steering GUI.

class mafw.processor.path_types.PathRole(*values)

Bases: Enum

Classify how a Path parameter should be browsed in the steering GUI.

The role selects the file dialog used by the inline path editor: a directory chooser, an existing-file chooser, or a save (new-file) chooser. It does not affect the runtime type of the parameter, which stays Path.

Added in version 2.4.

DIRECTORY = 1

An existing directory target.

INPUT_FILE = 2

A file that must already exist (the default role).

OUTPUT_FILE = 3

A file path that need not yet exist.

mafw.processor.path_types._list_element_type(annotation: Any) → Any

Return the element type T of a list[T] annotation, or None.

Any Annotated wrapper is stripped first, then typing.get_args yields the single type argument. A bare list (no parameter) resolves to None.

Parameters:

annotation – The annotation to inspect.

Returns:

The element type when known, otherwise None.

mafw.processor.path_types._unwrap_annotated(annotation: Any) → tuple[Any, tuple[Any, ...]]

Split an Annotated wrapper into its underlying type and metadata.

Detection relies on the __metadata__ attribute, which is the robust public marker of an Annotated form; the three aliases above expand to exactly such forms, so they are unwrapped identically to a hand-written Annotated.

Parameters:

annotation – Any annotation object, possibly an Annotated[...] form.

Returns:

A tuple (underlying, metadata); metadata is empty when the annotation is not an Annotated form.

mafw.processor.path_types.is_path_type(annotation: Any) → bool

Return whether the annotation denotes Path or a subclass.

Handles plain Path, concrete subclasses (PosixPath / WindowsPath), and Annotated[Path-like, ...] wrappers, including the DirectoryPath / InputFilePath / OutputFilePath aliases.

Parameters:

annotation – The annotation to inspect.

Returns:

True when the (unwrapped) annotation is a Path type or subclass.

mafw.processor.path_types.path_role_of(annotation: Any) → PathRole

Return the PathRole marker on a path annotation, or INPUT_FILE.

Unmarked Path / Path subclass parameters default to PathRole.INPUT_FILE (the pre-fix browse behaviour). The alias forms carry their marker in the Annotated metadata and are resolved here unchanged.

Parameters:

annotation – The annotation to inspect.

Returns:

The embedded PathRole, or PathRole.INPUT_FILE when none.

mafw.processor.path_types.DirectoryPath

Ergonomic alias for a directory path parameter.

Equivalent to Annotated[Path, PathRole.DIRECTORY]; the runtime type remains Path.

Added in version 2.4.

alias of Annotated[Path, <PathRole.DIRECTORY: 1>]

mafw.processor.path_types.InputFilePath

Ergonomic alias for an input (existing) file path parameter.

Equivalent to Annotated[Path, PathRole.INPUT_FILE]; the runtime type remains Path.

Added in version 2.4.

alias of Annotated[Path, <PathRole.INPUT_FILE: 2>]

mafw.processor.path_types.OutputFilePath

Ergonomic alias for an output (not-yet-existing) file path parameter.

Equivalent to Annotated[Path, PathRole.OUTPUT_FILE]; the runtime type remains Path.

Added in version 2.4.

alias of Annotated[Path, <PathRole.OUTPUT_FILE: 3>]