pyaml.configuration.fileloader#

Load PyAML configuration files and expand nested references.

The loader supports YAML and JSON files, environment and path resolvers, recursive file includes, and optional source-location metadata for diagnostics.

Functions

load(filename[, include_locations])

Load a configuration file.

resolve_env(value[, _context])

Resolve an environment variable by name.

resolve_file(value[, context])

Load and return the contents of a configuration file.

resolve_path(value[, _context])

Resolve a configuration path without loading the file.

resolver(name)

Register a function as a configuration value resolver.

Classes

ConfigLoader(path, context)

Base class for parsers that expand nested configuration references.

JSONLoader(path, context)

Load and expand JSON configuration files.

LoadContext([include_locations, include_stack])

Track include state during one recursive loading session.

RootFolder([path])

Manage the base directory for relative configuration paths.

SafeLineLoader(stream)

YAML loader that preserves line and column information for mappings.

YAMLLoader(path, context)

Load and expand YAML configuration files.

Exceptions

PyAMLConfigCyclingException(error_filename, ...)

Raised when a configuration file includes itself through a cycle.
exception pyaml.configuration.fileloader.PyAMLConfigCyclingException(error_filename, path_stack)#

Bases: PyAMLException

Raised when a configuration file includes itself through a cycle.

Parameters:

  • error_filename (str) – File that triggered the cycle.

  • path_stack (list[pathlib.Path]) – Include chain leading to the cycle.

class pyaml.configuration.fileloader.ConfigLoader(path, context)#

Bases: ABC

Base class for parsers that expand nested configuration references.

Parameters:

  • path (pathlib.Path) – Configuration file being loaded.

  • context (LoadContext) – Shared state for recursive includes and cycle detection.

Methods

expand()

Recursively expand configuration values.

load()

Load and parse the current configuration file.
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 pyaml.configuration.fileloader.JSONLoader(path, context)#

Bases: ConfigLoader

Load and expand JSON configuration files.

Parameters:

  • path (pathlib.Path) – Configuration file being loaded.

  • context (LoadContext) – Shared state for recursive includes and cycle detection.

Methods

load()

Parse the JSON file and expand nested configuration references.
load()#

Parse the JSON file and expand nested configuration references.

class pyaml.configuration.fileloader.LoadContext(include_locations=False, include_stack=<factory>)#

Bases: object

Track include state during one recursive loading session.

Parameters:

  • include_locations (bool, optional) – Preserve source locations in loaded mappings.

  • include_stack (list[pathlib.Path], optional) – Active include chain. Usually left empty for a new session.

Methods

loading()

Temporarily add a file to the active include chain.
loading(path)#

Temporarily add a file to the active include chain.

Parameters:

path (pathlib.Path) – File that is about to be loaded.

Raises:

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

class pyaml.configuration.fileloader.RootFolder(path=None)#

Bases: object

Manage the base directory for relative configuration paths.

Parameters:

path (str or pathlib.Path or None, optional) – Directory used to resolve relative paths.

Methods

set()

Set the directory used to resolve relative configuration files.

get()

Return the resolved configuration root directory.

expand_path()

Resolve a configuration path against the root directory.
expand_path(path)#

Resolve a configuration path against the root directory.

Relative paths are interpreted relative to the configured root folder.

Parameters:

path (str or pathlib.Path) – Path to resolve.

Returns:

pathlib.Path – Absolute, normalized path.

Return type:

Path

get()#

Return the resolved configuration root directory.

set(path)#

Set the directory used to resolve relative configuration files.

Parameters:

path (str or pathlib.Path) – New configuration root directory.

class pyaml.configuration.fileloader.SafeLineLoader(stream)#

Bases: SafeLoader

YAML loader that preserves line and column information for mappings.

Parameters:

stream (io.TextIOBase) – Stream to parse. Its name is recorded so errors can cite the source file.

Methods

construct_mapping()

Build a mapping and attach location metadata to it.
construct_mapping(node, deep=False)#

Build a mapping and attach location metadata to it.

class pyaml.configuration.fileloader.YAMLLoader(path, context)#

Bases: ConfigLoader

Load and expand YAML configuration files.

Parameters:

  • path (pathlib.Path) – Configuration file being loaded.

  • context (LoadContext) – Shared state for recursive includes and cycle detection.

Methods

load()

Parse the YAML file and expand nested configuration references.
load()#

Parse the YAML file and expand nested configuration references.

pyaml.configuration.fileloader.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.

pyaml.configuration.fileloader.resolve_env(value, _context=None)#

Resolve an environment variable by name.

Parameters:

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

  • _context (LoadContext or None, optional) – Unused loading context retained for resolver compatibility.

Returns:

str – Environment variable value.

Raises:

PyAMLException – If the environment variable is not set.

Return type:

str

pyaml.configuration.fileloader.resolve_file(value, context=None)#

Load and return the contents of a configuration file.

Parameters:

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

  • context (LoadContext, optional) – Shared loading context used to detect inclusion cycles.

Returns:

object – Parsed and expanded configuration data.

Raises:

RuntimeError – If no loading context is provided.

Return type:

Any

pyaml.configuration.fileloader.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 (LoadContext or None, optional) – Unused loading context retained for resolver compatibility.

Returns:

str – Absolute, normalized path.

Return type:

str

pyaml.configuration.fileloader.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.