docbuild.config.load#

Load and process configuration files.

Functions#

process_envconfig(→ tuple[pathlib.Path, dict[str, Any]])

Process the env config.

load_single_config(→ dict[str, Any])

Load a single TOML config file and return its content.

load_and_merge_configs(...)

Load config files and merge all content regardless of the nesting level.

handle_config(→ tuple[tuple[pathlib.Path, ...)

Return (config_files, config, from_defaults) for config file handling.

Module Contents#

docbuild.config.load.process_envconfig(envconfigfile: str | pathlib.Path | None) → tuple[pathlib.Path, dict[str, Any]]#

Process the env config.

Parameters:

envconfigfile – Path to the env TOML config file.

Returns:

Tuple of the env config file path and the config object.

Raises:

ValueError – If neither envconfigfile nor role is provided.

docbuild.config.load.load_single_config(configfile: str | pathlib.Path) → dict[str, Any]#

Load a single TOML config file and return its content.

Parameters:

configfile – Path to the config file.

Returns:

The loaded config as a dictionary.

Raises:
docbuild.config.load.load_and_merge_configs(defaults: collections.abc.Sequence[str | pathlib.Path], *paths: str | pathlib.Path) → tuple[tuple[str | pathlib.Path, Ellipsis], dict[str, Any]]#

Load config files and merge all content regardless of the nesting level.

The order of defaults and paths is important. The paths are in the order of system path, user path, and current working directory. The defaults are in the order of common config file names followed by more specific ones. The later ones will override data from the earlier ones.

Parameters:

  • defaults – a sequence of base filenames (without path!) to look for in the paths

  • paths – the paths to look for config files (without the filename!)

Returns:

the found config files and the merged dictionary

docbuild.config.load.handle_config(user_path: pathlib.Path | str | None, search_dirs: collections.abc.Iterable[str | pathlib.Path], basenames: collections.abc.Iterable[str] | None, default_filename: str | None = None, default_config: object | None = None) → tuple[tuple[pathlib.Path, Ellipsis] | None, object | dict, bool]#

Return (config_files, config, from_defaults) for config file handling.

Parameters:

  • user_path – Path to the user-defined config file, if any.

  • search_dirs – Iterable of directories to search for config files.

  • basenames – Iterable of base filenames to search for.

  • default_filename – Default filename to use if no config file is found.

  • default_config – Default configuration to return if no config file is found.

Returns:

A tuple containing:

  • A tuple of found config file paths or None if no config file is found.

  • The loaded configuration as a dictionary or the default configuration.

  • A boolean indicating if the default configuration was used.

Raises:

ValueError – If no config file is found and no default configuration is provided.