API Reference#

pw_config_loader: None

pw_config_loader.find_config#

Helpers for finding config files.

pw_config_loader.find_config.configs_in_parents(config_file_name: str, path: Path) → Iterator[Path]#

Finds all config files in a file’s parent directories.

Given the following file system:

/ (root)
  home/
    gregory/
      foo.conf
      pigweed/
        foo.conf
        pw_cli/
          baz.txt

Calling this with config_file_name="foo.conf" and path=/home/gregory/pigweed/pw_cli/baz.txt, the following config files will be yielded in order:

/home/gregory/pigweed/foo.conf
/home/gregory/foo.conf

Parameters:

config_file_name – The basename of the config file of interest.
path – The path to search for config files from.

Yields:

The paths to all config files that match the provided config_file_name, ordered from nearest to path to farthest.

pw_config_loader.find_config.paths_by_nearest_config( config_file_name: str, paths: Iterable[Path], ) → Mapping[Path | None, List[Path]]#

Groups a series of paths by their nearest config file.

For each path in paths, a lookup of the nearest matching config file is performed. Each identified config file is inserted as a key to the dictionary, and the value of each entry is a list containing every input file path that will use said config file. This is well suited for batching calls to tools that require a config file as a passed argument.

Example:

paths_by_config = paths_by_nearest_config(
    'settings.ini',
    paths,
)
for conf, grouped_paths:
    subprocess.run(
        (
            'format_files',
            '--config',
            conf,
            *grouped_paths,
        )
    )

Parameters:

config_file_name – The basename of the config file of interest.
paths – The paths that should be mapped to their nearest config.

Returns:

A dictionary mapping the path of a config file to files that will pick up that config as their nearest config file.

pw_config_loader.json_config_loader_mixin#

JSON config file loader mixin.

class pw_config_loader.json_config_loader_mixin.JsonConfigLoaderMixin#

JSON Config file loader mixin.

Use this mixin to load json file settings and save them into self._config. For example:

from pw_cli.json_config_loader_mixin import JsonConfigLoaderMixin

class PwBloatPrefs(JsonConfigLoaderMixin):
    def __init__(self) -> None:
        self.config_init(
            config_section_title='pw_bloat',
            project_file=Path('$PW_PROJECT_ROOT/.pw_bloat.json'),
            project_user_file=Path(
                '$PW_PROJECT_ROOT/.pw_bloat.user.json'),
            user_file=Path('~/.pw_bloat.json'),
            default_config={},
            environment_var='PW_BLOAT_CONFIG_FILE',
        )

pw_config_loader.toml_config_loader_mixin#

Toml config file loader mixin.

class pw_config_loader.toml_config_loader_mixin.TomlConfigLoaderMixin#

TOML Config file loader mixin.

Use this mixin to load toml file settings and save them into self._config. For example:

from pw_cli.toml_config_loader_mixin import TomlConfigLoaderMixin

class PwBloatPrefs(TomlConfigLoaderMixin):
    def __init__(self) -> None:
        self.config_init(
            config_section_title='pw_bloat',
            project_file=Path('$PW_PROJECT_ROOT/.pw_bloat.toml'),
            project_user_file=Path(
                '$PW_PROJECT_ROOT/.pw_bloat.user.toml'),
            user_file=Path('~/.pw_bloat.toml'),
            default_config={},
            environment_var='PW_BLOAT_CONFIG_FILE',
        )

pw_config_loader.yaml_config_loader_mixin#

Yaml config file loader mixin.

exception pw_config_loader.yaml_config_loader_mixin.MissingConfigTitle#: Exception for when an existing YAML file is missing config_title.

class pw_config_loader.yaml_config_loader_mixin.Stage(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

class pw_config_loader.yaml_config_loader_mixin.YamlConfigLoaderMixin#

Yaml Config file loader mixin.

Use this mixin to load yaml file settings and save them into self._config. For example:

class ConsolePrefs(YamlConfigLoaderMixin):
    def __init__(self) -> None:
        self.config_init(
            config_section_title='pw_console',
            project_file=Path('project_file.yaml'),
            project_user_file=Path('project_user_file.yaml'),
            user_file=Path('~/user_file.yaml'),
            default_config={},
            environment_var='PW_CONSOLE_CONFIG_FILE',
        )

Call this to load YAML config files in order of precedence.

The following files are loaded in this order: 1. project_file 2. project_user_file 3. user_file

Lastly, if a valid file path is specified at os.environ[environment_var] then load that file overriding all config options.

Parameters:

config_section_title –
String name of this config section. For example: pw_console or pw_watch. In the YAML file this is represented by a config_title key.
```
---
config_title: pw_console
```
project_file – Project level config file. This is intended to be a file living somewhere under a project folder and is checked into the repo. It serves as a base config all developers can inherit from.
project_user_file – User’s personal config file for a specific project. This can be a file that lives in a project folder that is git-ignored and not checked into the repo.
user_file – A global user based config file. This is typically a file in the users home directory and settings here apply to all projects.
default_config – A Python dict representing the base default config. This dict will be applied as a starting point before loading any yaml files.
environment_var – The name of an environment variable to check for a config file. If a config file exists there it will be loaded on top of the default_config ignoring project and user files.
skip_files_without_sections – Don’t produce an exception if a config file doesn’t include the relevant section. Instead, just move on to the next file.

handle_overloaded_value( key: str, stage: Stage, original_value: Any, overriding_value: Any, ) → Any#: Overload this in subclasses to handle of overloaded values.

load_config_file( file_path: Path, skip_files_without_sections: bool = False, stage: Stage = Stage.OUT_OF_BAND, ) → None#: Load a config file and extract the appropriate section.