config
¶
-
class
invoke.config.
Config
(defaults=None, overrides=None, system_prefix=None, user_prefix=None, project_home=None, env_prefix=None, runtime_path=None)¶ Invoke’s primary configuration handling class.
See Configuration for details on the configuration system this class implements, including the configuration hierarchy. The rest of this class’ documentation assumes familiarity with that document.
Access
Configuration values may be accessed using dict syntax:
config['foo']
or attribute syntax:
config.foo
Nesting works the same way - dict config values are turned into objects which honor both the dictionary protocol and the attribute-access method:
config['foo']['bar'] config.foo.bar
A note about attribute access and methods
This class implements the entire dictionary protocol: methods such as
keys
,values
,items
,pop
and so forth should all function as they do on regular dicts. It also implements its own methods such asload_collection
andclone
.Warning
Accordingly, this means that if you have configuration options sharing names with these methods, you must use dictionary syntax (e.g.
myconfig['keys']
) to access them.Individual configuration ‘levels’ and their source locations are stored as ‘private’ attributes (e.g.
_defaults
,_system_prefix
) so fewer names are “taken” from the perspective of attribute access to user config values.Lifecycle
On initialization,
Config
will seek out and load various configuration files from disk, thenmerge
the results with other in-memory sources such as defaults and CLI overrides.Typically, the
load_collection
andload_shell_env
methods are called after initialization -load_collection
prior to each task invocation (because collection-level config data may change depending on the task) andload_shell_env
as the final step (as it needs the rest of the config to know which env vars are valid to load).Once users are given a copy of the configuration (usually via their task’s
Context
argument) all the above loading (& a finalmerge
) has been performed and they are free to modify it as they would any other regular dictionary.Warning
Calling
merge
after manually modifyingConfig
objects may overwrite those manual changes, since it overwrites the core config dict with data from per-source attributes like._defaults
or_.user
.-
__init__
(defaults=None, overrides=None, system_prefix=None, user_prefix=None, project_home=None, env_prefix=None, runtime_path=None)¶ Creates a new config object.
Parameters: - defaults (dict) – A dict containing default (lowest level) config data. Default:
global_defaults
. - overrides (dict) – A dict containing override-level config data. Default:
{}
. - system_prefix (str) –
Path & partial filename for the global config file location. Should include everything but the dot & file extension.
Default:
/etc/invoke
(e.g./etc/invoke.yaml
or/etc/invoke.json
). - user_prefix (str) –
Like
system_prefix
but for the per-user config file.Default:
~/.invoke
(e.g.~/.invoke.yaml
). - project_home (str) – Optional directory path location of the currently loaded
Collection
(as loaded byLoader
). When non-empty, will trigger seeking of per-project config files in this location +invoke.(yaml|json|py)
. - env_prefix (str) –
Environment variable seek prefix; optional, defaults to
None
.When not
None
, only environment variables beginning with this value will be loaded. If it is set, the keys will have the prefix stripped out before processing, so e.g.env_prefix='INVOKE_'
means users must setINVOKE_MYSETTING
in the shell to affect the"mysetting"
setting. - runtime_path (str) –
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.
- defaults (dict) – A dict containing default (lowest level) config data. Default:
-
clone
()¶ Return a copy of this configuration object.
The new object will be identical in terms of configured sources and any loaded/merged data, but will be a distinct object with no shared mutable state.
-
static
global_defaults
()¶ Return the core default settings for Invoke.
Generally only for use by
Config
internals. For descriptions of these values, see Default configuration values.Subclasses may choose to override this method, calling
Config.global_defaults
and applyingmerge_dicts
to the result, to add to or modify these values.
-
load_collection
(data)¶ Update collection-driven config data.
load_collection
is intended for use by the core task execution machinery, which is responsible for obtaining per-task collection-driven data. See Collection-based configuration for details.Note
This method triggers
merge
after it runs.
-
load_files
()¶ Load any unloaded/un-searched-for config file sources.
Specifically, any file sources whose
_found
values areNone
will be sought and loaded if found; if their_found
value is nonNone
(e.g.True
orFalse
) they will be skipped. Typically this means this method is idempotent and becomes a no-op after the first run.Execution of this method does not imply merging; use
merge
for that.
-
load_shell_env
()¶ Load values from the shell environment.
load_shell_env
is intended for execution late in aConfig
object’s lifecycle, once all other sources have been merged. 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 Environment variables for details on this design decision and other info re: how environment variables are scanned and loaded.
-
merge
()¶ Merge all config sources, in order.
Does not imply loading of config files or environment variables; use
load_files
and/orload_shell_env
beforehand instead.
-
paths
¶ An iterable of all successfully loaded config file paths.
No specific order.
-
-
class
invoke.config.
DataProxy
¶ Helper class implementing nested dict+attr access for
Config
.-
__weakref__
¶ list of weak references to the object (if defined)
-
-
invoke.config.
merge_dicts
(base, updates)¶ Recursively merge dict
updates
into dictbase
(mutatingbase
.)- Values which are themselves dicts will be recursed into.
- Values which are a dict in one input and not a dict in the other input
(e.g. if our inputs were
{'foo': 5}
and{'foo': {'bar': 5}}
) are irreconciliable and will generate an exception.