mafw.tools.path_resolution

Resolve configuration-declared filesystem paths against their owning file.

The resolver keeps path expansion separate from configuration storage and filesystem validation. Callers must opt into this API only for values known to represent filesystem paths.

Added in version 2.4.

author:

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

Functions

resolve_path(value, context, *[, ...])

Interpolate and resolve a known filesystem path value.

Classes

PathResolutionContext(base_directory[, ...])	Immutable base context for a configuration-declared path.
PathValidationPolicy(*values)	Select an optional existence and type check for a resolved path.

Exceptions

PathResolutionError(original_value, context, ...)

Report an invalid filesystem path value with its owning context.

exception mafw.tools.path_resolution.PathResolutionError(original_value: str | Path, context: PathResolutionContext, detail: str)

Bases: ValueError

Report an invalid filesystem path value with its owning context.

Added in version 2.4.

Create an error that retains the configured value and context.

class mafw.tools.path_resolution.PathResolutionContext(base_directory: Path, declaring_file: Path | None = None)

Bases: object

Immutable base context for a configuration-declared path.

Use from_file() for a path declared in a configuration file. Each nested configuration file should get a new context of its own. The from_directory() constructor supports existing APIs that already receive an explicit base directory.

Relative context inputs are anchored to the current directory once, when the context is created. Path values resolved later do not depend on it.

Added in version 2.4.

classmethod from_directory(directory: Path | str) → Self

Create a context from an explicit base directory.

Parameters:

directory – Base directory for relative values.

Returns:

An immutable context with an absolute base directory.

classmethod from_file(declaring_file: Path | str) → Self

Create a context whose base is the directory containing a file.

Parameters:

declaring_file – Configuration file that owns the path value.

Returns:

An immutable context with an absolute file and base directory.

property description: str

Return a human-readable description for diagnostics.

class mafw.tools.path_resolution.PathValidationPolicy(*values)

Bases: Enum

Select an optional existence and type check for a resolved path.

NONE is appropriate for output destinations, which need not exist yet.

Added in version 2.4.

mafw.tools.path_resolution._looks_like_uri(value: str) → bool

Recognize URI schemes without mistaking Windows drive paths for URIs.

mafw.tools.path_resolution._resolve_interpolated_path(value: str | Path, context: PathResolutionContext, *, validation: PathValidationPolicy = PathValidationPolicy.NONE, original_value: str | Path | None = None) → Path

Resolve an already interpolated path for the public API and migrations.

mafw.tools.path_resolution.resolve_path(value: str | Path, context: PathResolutionContext, *, validation: PathValidationPolicy = PathValidationPolicy.NONE, env: Mapping[str, str] | None = None) → Path

Interpolate and resolve a known filesystem path value.

Environment-variable interpolation uses the same syntax and errors as mafw.tools.toml_tools.resolve_string() and occurs before home expansion and path normalization. URI schemes and glob patterns are rejected because this function handles filesystem paths only.

Normalization produces an absolute path without requiring it to exist. validation may additionally require an existing file or directory. Use PathValidationPolicy.NONE for output destinations; this function never creates files or directories.

Parameters:

• value – Configured path value, retained unchanged by the caller.

• context – Owning configuration-file or explicit base-directory context.

• validation – Optional existence and type policy.

• env – Environment mapping for interpolation; defaults to os.environ.

Returns:

The effective absolute path.

Raises:

PathResolutionError – If interpolation, classification, normalization, or requested validation fails.