invoke.config.Config

Creates a new config object. :param dict defaults: A dict containing default (lowest level) config data. Default: `global_defaults`. :param dict overrides: A dict containing override-level config data. Default: ``{}``. :param str system_prefix: Base path for the global config file location; combined with the prefix and file suffixes to arrive at final file path candidates. Default: ``/etc/`` (thus e.g. ``/etc/invoke.yaml`` or ``/etc/invoke.json``). :param str user_prefix: Like ``system_prefix`` but for the per-user config file. These variables are joined as strings, not via path-style joins, so they may contain partial file paths; for the per-user config file this often means a leading dot, to make the final result a hidden file on most systems. Default: ``~/.`` (e.g. ``~/.invoke.yaml``). :param str project_location: Optional directory path of the currently loaded `.Collection` (as loaded by `.Loader`). When non-empty, will trigger seeking of per-project config files in this directory. :param str runtime_path: Optional file path to a runtime configuration file. Used to fill the penultimate slot in the config hierarchy. Should be a full file path to an existing file, not a directory path or a prefix. :param bool lazy: Whether to automatically load some of the lower config levels. By default (``lazy=False``), ``__init__`` automatically calls `load_system` and `load_user` to load system and user config files, respectively. For more control over what is loaded when, you can say ``lazy=True``, and no automatic loading is done. .. note:: If you give ``defaults`` and/or ``overrides`` as ``__init__`` kwargs instead of waiting to use `load_defaults` or `load_overrides` afterwards, those *will* still end up 'loaded' immediately.

Return a copy of this configuration object. The new object will be identical in terms of configured sources and any loaded (or user-manipulated) data, but will be a distinct object with as little shared mutable state as possible. Specifically, all `dict` values within the config are recursively recreated, with non-dict leaf values subjected to `copy.copy` (note: *not* `copy.deepcopy`, as this can cause issues with various objects such as compiled regexen or threading locks, often found buried deep within rich aggregates like API or DB clients). The only remaining config values that may end up shared between a config and its clone are thus those 'rich' objects that do not `copy.copy` cleanly, or compound non-dict objects (such as lists or tuples). :param into: A `.Config` subclass that the new clone should be "upgraded" to. Used by client libraries which have their own `.Config` subclasses that e.g. define additional defaults; cloning "into" one of these subclasses ensures that any new keys/subtrees are added gracefully, without overwriting anything that may have been pre-defined. Default: ``None`` (just clone into another regular `.Config`). :returns: A `.Config`, or an instance of the class given to ``into``. :raises: ``TypeError``, if ``into`` is given a value and that value is not a `.Config` subclass. .. versionadded:: 1.0

Undocumented

Update collection-driven config data. `.load_collection` is intended for use by the core task execution machinery, which is responsible for obtaining collection-driven data. See :ref:`collection-configuration` for details. .. versionadded:: 1.0

Set or replace the 'defaults' configuration level, from ``data``. :param dict data: The config data to load as the defaults level. :param bool merge: Whether to merge the loaded data into the central config. Default: ``True``. :returns: ``None``. .. versionadded:: 1.0

Set or replace the 'overrides' configuration level, from ``data``. :param dict data: The config data to load as the overrides level. :param bool merge: Whether to merge the loaded data into the central config. Default: ``True``. :returns: ``None``. .. versionadded:: 1.0

Load a project-level config file, if possible. Checks the configured ``_project_prefix`` value derived from the path given to `set_project_location`, which is typically set to the directory containing the loaded task collection. Thus, if one were to run the CLI tool against a tasks collection ``/home/myuser/code/tasks.py``, `load_project` would seek out files like ``/home/myuser/code/invoke.yml``. :param bool merge: Whether to merge the loaded data into the central config. Default: ``True``. :returns: ``None``. .. versionadded:: 1.0

Load a runtime-level config file, if one was specified. When the CLI framework creates a `Config`, it sets ``_runtime_path``, which is a full path to the requested config file. This method attempts to load that file. :param bool merge: Whether to merge the loaded data into the central config. Default: ``True``. :returns: ``None``. .. versionadded:: 1.0

Load values from the shell environment. `.load_shell_env` is intended for execution late in a `.Config` object's lifecycle, once all other sources (such as a runtime config file or per-collection configurations) have been loaded. Loading from the shell is not terrifically expensive, but must be done at a specific point in time to ensure the "only known config keys are loaded from the env" behavior works correctly. See :ref:`env-vars` for details on this design decision and other info re: how environment variables are scanned and loaded. .. versionadded:: 1.0

Load a system-level config file, if possible. Checks the configured ``_system_prefix`` path, which defaults to ``/etc``, and will thus load files like ``/etc/invoke.yml``. :param bool merge: Whether to merge the loaded data into the central config. Default: ``True``. :returns: ``None``. .. versionadded:: 1.0

Load a user-level config file, if possible. Checks the configured ``_user_prefix`` path, which defaults to ``~/.``, and will thus load files like ``~/.invoke.yml``. :param bool merge: Whether to merge the loaded data into the central config. Default: ``True``. :returns: ``None``. .. versionadded:: 1.0

Merge all config sources, in order. .. versionadded:: 1.0

Set the directory path where a project-level config file may be found. Does not do any file loading on its own; for that, see `load_project`. .. versionadded:: 1.0

Set the runtime config file path. .. versionadded:: 1.0