fileloader

PyAML configuration file loader.

class ConfigLoader(path, context)

Bases: ABC

Base class for loaders that expand nested configuration references.

Store the file path and shared loading context.

expand(obj)

Recursively expand configuration values.

Dictionaries and lists are traversed recursively, while string values are resolved using the registered resolvers. All other values are returned unchanged.

abstractmethod load()

Load and parse the current configuration file.

class JSONLoader(path, context)

Bases: ConfigLoader

Load and expand JSON configuration files.

Create a JSON loader for the given file.

load()

Parse the JSON file and expand nested configuration references.

class LoadContext(include_locations=False, include_stack=<factory>)

Bases: object

Track state for one recursive configuration-loading session.

loading(path)

Register a file as currently being loaded and remove it afterward.

Raises:

PyAMLConfigCyclingException – If the file is already on the active include stack.

include_locations: bool = False

include_stack: list[Path]

class PyAMLConfigCyclingException(error_filename, path_stack)

Bases: PyAMLException

Raised when a configuration file includes itself through a cycle.

Create a circular-include error.

Parameters:

• error_filename (str) – The file that triggered the cycle.

• path_stack (list[Path]) – The include chain leading to the cycle.

class RootFolder(path=None)

Bases: object

Manage the root directory used to resolve configuration paths.

Create a root folder.

If no path is provided, the current working directory is used.

expand_path(path)

Return an absolute, normalized configuration path.

Relative paths are interpreted relative to the configured root folder.

get()

Return the current root path.

set(path)

Set the root path used for resolving relative configuration files.

class SafeLineLoader(stream)

Bases: SafeLoader

YAML loader that preserves line and column information for mappings.

Create the YAML loader and record the source filename.

construct_mapping(node, deep=False)

Build a mapping and attach location metadata to it.

class YAMLLoader(path, context)

Bases: ConfigLoader

Load and expand YAML configuration files.

Create a YAML loader for the given file.

load()

Parse the YAML file and expand nested configuration references.

load(filename, include_locations=False)

Load a configuration file.

When include_locations is False, uses the faster C-based YAML loader and skips including source location metadata.

resolve_env(value, _context=None)

Resolve an environment variable.

Parameters:

• value (str) – Name of the environment variable.

• context – Unused loading context. Present to match the resolver interface.

Raises:

PyAMLException – If the environment variable is not set.

resolve_file(value, context)

Load and return the contents of a configuration file.

Parameters:

• value (str) – Path to the configuration file.

• context (LoadContext) – Shared loading context used to track recursive includes and detect inclusion cycles.

Raises:

RuntimeError – If no loading context is provided.

resolve_path(value, _context=None)

Resolve a configuration path without loading the file.

Relative paths are expanded using the configured root folder.

Parameters:

• value (str) – Path to resolve.

• context – Unused loading context. Present to match the resolver interface.

Returns:

The absolute, normalized path as a string.

resolver(name)

Register a function as a configuration value resolver.

Parameters:

name (str) – Prefix used to invoke the resolver (for example "env" or "file").

Returns:

• A decorator that registers the decorated function in the global

• resolver registry.