config

exception invoke.config.AmbiguousMergeError

__weakref__

对象的弱引用列表

class invoke.config.Config(overrides: Dict[str, Any] | None = None, defaults: Dict[str, Any] | None = None, system_prefix: str | None = None, user_prefix: str | None = None, project_location: PathLike | None = None, runtime_path: PathLike | None = None, lazy: bool = False)

Invoke的主要配置处理类。

看见 配置 有关此类实现的配置系统的详细信息，包括 configuration hierarchy 。本课程文档的其余部分假定您熟悉该文档。

Access

可以使用DICT语法访问和/或更新配置值：：

config['foo']

或属性语法：：

config.foo

嵌套的工作方式相同-DICT配置值被转换为同时支持字典协议和属性访问方法的对象：：

config['foo']['bar']
config.foo.bar

A note about attribute access and methods

此类实现了整个字典协议：方法，如 keys ， values ， items ， pop 以此类推，都应该像在常规词典上一样发挥作用。它还实现了新的特定于配置的方法，例如 load_system ， load_collection ， merge ， clone 等

警告

因此，这意味着如果您具有与这些方法共享名称的配置选项，则 must 使用词典语法(例如 myconfig['keys'] )以访问配置数据。

Lifecycle

在初始化时， Config ：

• 创建每个级别的数据结构；

• 存储提供给的任何级别 __init__ ，例如默认或覆盖，以及各种配置文件路径/文件名模式；

• 并加载配置文件(如果找到的话)(尽管这通常只意味着系统和用户级别的文件，因为项目和运行时文件在找到和加载之前需要更多信息。)

  • 可以通过指定以下命令跳过此步骤 lazy=True 。

在这点上， Config 完全可用-因为它会先发制人地加载一些配置文件，这些配置文件可能会影响之后的任何事情，如CLI解析或加载任务集合。

在CLI用例中，在实例化之后使用 load_* 方法，如 load_overrides ， load_project ，等等：

• 参数/选项分析的结果被应用于覆盖级别；

• 加载项目级配置文件，因为它依赖于加载的任务集合；

• 如果提供了运行时配置文件的标志，则加载该文件；

• 然后，对于正在执行的每个任务：

  • 加载每个集合的数据(只有在我们有收集和任务在手时才有可能)；

  • 加载Shell环境数据(必须在进程结束时完成，因为使用配置的其余部分作为解释env var名称的指南。)

此时，配置对象被传递给正在执行的任务，作为其执行的一部分 Context 。

直接对 Config 在这一点之后，它本身最终存储在它们自己的(最顶层)配置级别中，从而更容易调试最终值。

最后，任何 deletions 致送至 Config (例如，DICT风格的变异子的应用，如 pop ， clear 等)也在它们自己的结构中被跟踪，从而允许配置对象在不改变底层源数据的情况下执行这样的方法调用。

Special class attributes

以下类级属性用于配置系统本身的低级配置，例如要加载哪些文件路径。它们主要用于按子类重写。

• prefix ：提供以下项的默认值 file_prefix (直接)和 env_prefix (大写)。有关详细信息，请参阅它们的说明。其缺省值为 "invoke" 。

• file_prefix ：配置文件‘basename’的默认名称(尽管它不是文字基本名称；如果需要，它可以包含路径部分)，该配置文件附加到的配置值 system_prefix ， user_prefix 等，以到达最终(扩展前)文件路径。

  因此，默认情况下，系统级配置文件路径将 system_prefix 的 /etc/ 与 file_prefix 的 invoke 到达像这样的路径 /etc/invoke.json 。

  默认为 None ，意思是使用 prefix 。

• env_prefix ：用于确定加载哪些环境变量作为env var配置级别的前缀(与连接下划线一起使用)。因为它的缺省值是 prefix 大写，这意味着env变量如下 INVOKE_RUN_ECHO 是默认情况下寻找的。

  默认为 None ，意思是使用 prefix 。

在 1.0 版本加入.

__init__(overrides: Dict[str, Any] | None = None, defaults: Dict[str, Any] | None = None, system_prefix: str | None = None, user_prefix: str | None = None, project_location: PathLike | None = None, runtime_path: PathLike | None = None, lazy: bool = False)

创建新的配置对象。

参数:

• defaults (dict) -- 包含默认(最低级别)配置数据的字典。默认： global_defaults 。

• overrides (dict) -- 包含覆盖级别配置数据的字典。默认： {} 。

• system_prefix (str) -- 全局配置文件位置的基本路径；与前缀和文件后缀组合以得到最终的文件路径候选。默认： /etc/ (例如 /etc/invoke.yaml 或 /etc/invoke.json )。

• user_prefix (str) -- 喜欢 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: ~/. (例如： ~/.invoke.yaml )。

• project_location (str) -- 当前加载的可选目录路径 Collection (由加载 Loader )。非空时，将触发在此目录中查找每个项目的配置文件。

• runtime_path (str) -- 运行时配置文件的可选文件路径。用于填充配置层次结构中的倒数第二个位置。应为现有文件的完整文件路径，而不是目录路径或前缀。

• lazy (bool) -- 是否自动加载一些较低的配置级别。默认情况下 (lazy=False ), __init__ 自动呼叫 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__`而不是等待使用 load_defaults 或 load_overrides 之后，那些 will 但最终还是会立刻“满载而归”。

clone(into: Type[Config] | None = None) → Config

返回此配置对象的副本。

新对象在配置的源和任何加载的(或用户操作的)数据方面将是相同的，但将是一个不同的对象，具有尽可能少的共享可变状态。

具体来说，所有 dict 配置中的值以递归方式重新创建，其中非字典叶的值受 copy.copy (注： not copy.deepcopy ，因为这可能会导致各种对象的问题，如编译的正则表达式或线程锁，通常隐藏在API或DB客户端等富聚合的深处)。

因此，可能最终在配置及其克隆之间共享的唯一剩余配置值是那些不 copy.copy 干净的或复合的非DICT对象(如列表或元组)。

参数:

into -- A Config 新克隆应该“升级”到的子类。由拥有自己的客户端库的客户端库使用 Config 子类，例如定义额外的缺省值；克隆到这些子类中的一个确保任何新的键/子树被优雅地添加，而不会覆盖任何可能已经被预定义的东西。默认： None (只需克隆成另一个常规 Config )。

返回:

A Config ，或指定给的类的实例 into 。

在 1.0 版本加入.

static global_defaults() → Dict[str, Any]

返回Invoke的核心默认设置。

通常仅供以下人员使用 Config 内饰。有关这些值的说明，请参见 默认配置值 。

子类可以选择重写此方法，调用 Config.global_defaults 和应用程序 merge_dicts 添加或修改这些值。

在 1.0 版本加入.

load_collection(data: Dict[str, Any], merge: bool = True) → None

更新集合驱动的配置数据。

load_collection 供负责获取收集驱动的数据的核心任务执行机制使用。看见 Collection -基于配置 了解更多细节。

在 1.0 版本加入.

load_defaults(data: Dict[str, Any], merge: bool = True) → None

设置或替换“DEFAULTS”配置级别 data 。

参数:

• data (dict) -- 要加载为默认级别的配置数据。

• merge (bool) -- 是否将加载的数据合并到中央配置中。默认： True 。

返回:

None 。

在 1.0 版本加入.

load_overrides(data: Dict[str, Any], merge: bool = True) → None

设置或替换“Overrides”配置级别 data 。

参数:

• data (dict) -- 要作为覆盖级别加载的配置数据。

• merge (bool) -- 是否将加载的数据合并到中央配置中。默认： True 。

返回:

None 。

在 1.0 版本加入.

load_project(merge: bool = True) → None

如果可能，加载项目级配置文件。

检查已配置的 _project_prefix 从给出的路径派生的值 set_project_location ，它通常设置为包含加载的任务集合的目录。

因此，如果要对任务集合运行CLI工具 /home/myuser/code/tasks.py ， load_project 会找出像这样的文件 /home/myuser/code/invoke.yml 。

参数:

merge (bool) -- 是否将加载的数据合并到中央配置中。默认： True 。

返回:

None 。

在 1.0 版本加入.

load_runtime(merge: bool = True) → None

加载运行时级别的配置文件(如果已指定)。

当CLI框架创建 Config, it sets _ 运行时路径，是所请求的配置文件的完整路径。此方法尝试加载该文件。

参数:

merge (bool) -- 是否将加载的数据合并到中央配置中。默认： True 。

返回:

None 。

在 1.0 版本加入.

load_shell_env() → None

从Shell环境加载值。

load_shell_env 被设计为在 Config 对象的生命周期，一旦加载了所有其他源(如运行时配置文件或每个集合的配置)。从Shell加载并不是非常昂贵，但必须在特定的时间点完成，以确保“仅从环境加载已知的配置密钥”行为正常工作。

看见 环境变量 有关此设计决策和其他信息的详细信息，请参阅：如何扫描和加载环境变量。

在 1.0 版本加入.

load_system(merge: bool = True) → None

如果可能，加载系统级配置文件。

检查已配置的 _system_prefix 路径，默认为 /etc ，因此将加载如下文件 /etc/invoke.yml 。

参数:

merge (bool) -- 是否将加载的数据合并到中央配置中。默认： True 。

返回:

None 。

在 1.0 版本加入.

load_user(merge: bool = True) → None

如果可能，加载用户级别的配置文件。

检查已配置的 _user_prefix 路径，默认为 ~/. ，因此将加载如下文件 ~/.invoke.yml 。

参数:

merge (bool) -- 是否将加载的数据合并到中央配置中。默认： True 。

返回:

None 。

在 1.0 版本加入.

merge() → None

按顺序合并所有配置源。

在 1.0 版本加入.

set_project_location(path: PathLike | str | None) → None

设置可以找到项目级配置文件的目录路径。

本身不执行任何文件加载；有关这方面的信息，请参见 load_project 。

在 1.0 版本加入.

set_runtime_path(path: PathLike | None) → None

设置运行时配置文件路径。

在 1.0 版本加入.

class invoke.config.DataProxy

实现嵌套的dict+attr访问的Helper类 Config 。

具体地说，用于 Config 本身，并包装(递归)分配为配置值的任何其他DICT。

警告

(此对象的或子类中的)所有方法都必须注意通过 self._set(name='value') ，否则它们将遇到递归错误！

在 1.0 版本加入.

__delattr__(name: str) → None

实现delattr(self，name)。

__eq__(other: object) → bool

返回self==值。

__hash__ = None

__repr__() → str

返回epr(Self)。

__setattr__(key: str, value: Any) → None

实现setattr(self，name，value)。

__weakref__

对象的弱引用列表

classmethod from_data(data: Dict[str, Any], root: DataProxy | None = None, keypath: Tuple[str, ...] = ()) → DataProxy

用作子字段值的“Baby”DataProxies的替代构造函数。

允许创建独立的DataProxy对象，同时还允许诸如 Config define their own ``_ _init__``而不混淆两者。

参数:

• data (dict) -- 这个特定的DataProxy的个人数据。必填项，它是被代理的数据。

• root -- 根DataProxy/Config上需要数据更新通知的可选句柄。

• keypath (tuple) -- 可选的元组，描述指向此DataProxy在 root 结构。如果满足以下条件，则需要 root 给予了(反之亦然)。

在 1.0 版本加入.

invoke.config.copy_dict(source: Dict[str, Any]) → Dict[str, Any]

退回一份新的 source 共享状态越少越好。

用途 merge_dicts 在引擎盖下，有一个空的 base 有关行为的详细信息，请参阅其文档。

在 1.0 版本加入.

invoke.config.excise(dict_: Dict[str, Any], keypath: Tuple[str, ...]) → None

删除由指向的关键点 keypath 从嵌套词典 dict_ ，如果存在。

在 1.0 版本加入.

invoke.config.merge_dicts(base: Dict[str, Any], updates: Dict[str, Any]) → Dict[str, Any]

递归合并词典 updates 转换成词典 base (变异 base 。)

• 本身是字典的值将被递归为。

• 值，这些值是一个输入中的字典和 not 其他输入中的字典(例如，如果我们的输入是 {'foo': 5} 和 {'foo': {'bar': 5}} )是不可调和的，并将生成例外。

• 非字典叶的值将遍历 copy.copy 以避免州政府的流血。

备注

这实际上是一个轻量级的 copy.deepcopy 它提供了对不匹配类型的保护(DICT与非DICT)，并避免了一些核心的深度复制问题(例如它如何在某些对象类型上爆炸)。

返回:

的价值 base ，它主要用于包装器函数，如 copy_dict 。

在 1.0 版本加入.

invoke.config.obliterate(base: Dict[str, Any], deletions: Dict[str, Any]) → None

删除中提到的所有(嵌套)键 deletions 、发件人 base 。

在 1.0 版本加入.