docbuild.config.load#

Load and process configuration files.

Functions#

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.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 (raw dict)

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.

Note: The returned configuration is the raw loaded dictionary. No placeholder replacement or validation has been performed on it.

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.