collection

class invoke.collection.Collection(*args: Any, **kwargs: Any)

可执行任务的集合。请参阅 构建名称空间。

在 1.0 版本加入.

__eq__(other: object) → bool

Return self==value.

__getitem__(name: str | None = None) → Any

返回名为 name 的任务。支持别名和子集合。

如果此集合有默认任务，则在 name 为空或 None 时返回该任务。如果输入为空且未选择任何任务作为默认任务，将引发 ValueError。

子集合中的任务应以点形式给出，例如 ‘foo.bar’。子集合的默认任务将在子集合的名称上返回。

在 1.0 版本加入.

__hash__ = None

__repr__() → str

Return repr(self).

add_collection(coll: Collection, name: str | None = None, default: bool | None = None) → None

将 Collection coll 添加为此集合的子集合。

参数:

• coll – 要添加的 Collection。

• name (str) – 附加集合的名称。默认为集合自己的内部名称。

• default – 此子集合（的默认任务或集合）是否应作为父集合的默认调用。

在 1.0 版本加入.

在 1.5 版本发生变更: 添加了 default 参数。

add_task(task: Task, name: str | None = None, aliases: Tuple[str, ...] | None = None, default: bool | None = None) → None

将 Task task 添加到此集合中。

参数:

• task – 要添加到此集合中的 Task 对象。

• name – 可选的字符串名称绑定（覆盖任务自己的 name 属性和/或任何 Python 标识符（即 .func_name。）

• aliases – 除了主名称之外，可选的迭代器，用于将任务绑定为其他名称。这些将用于任务本身在内部声明的任何别名之外。

• default – 此任务是否应作为集合的默认任务。

在 1.0 版本加入.

configuration(taskpath: str | None = None) → Dict[str, Any]

从集合及其子集合中获取合并的配置值。

参数:

taskpath – （可选）任务名称/路径，与 __getitem__ 使用的相同（例如，可以为嵌套任务使用点形式等）。用于在合并配置值时决定在集合树中遵循的路径。

返回:

包含配置值的 dict。

在 1.0 版本加入.

configure(options: Dict[str, Any]) → None

（递归地）将 options 合并到当前的 configuration 中。

以这种方式配置的选项将对所有任务可用。建议使用唯一的键以避免与其他配置选项发生潜在冲突。

例如，如果你正在配置 Sphinx 文档构建目标目录，最好使用像 'sphinx.target' 这样的键，而不是简单的 'target'。

参数:

options – 实现字典协议的对象。

返回:

None.

在 1.0 版本加入.

classmethod from_module(module: module, name: str | None = None, config: Dict[str, Any] | None = None, loaded_from: str | None = None, auto_dash_names: bool | None = None) → Collection

返回从 module 创建的新 Collection。

检查 module 中的任何 Task 实例并将它们添加到新的 Collection 中，然后返回它。如果存在任何显式的命名空间集合（名为 ns 或 namespace），则优先加载该集合对象的副本。

当生成隐式/默认集合时，它将根据模块的 __name__ 属性命名，或者如果它是子模块，则根据其最后一个点部分命名。（即它通常应映射到实际的 .py 文件名。）

显式给定的集合只有在没有有效的 .name 属性时才会被赋予该模块派生的名称。

如果模块有文档字符串（ __doc__ ），它将被复制到生成的 Collection 上（并用于在帮助、列表等输出中显示。）

参数:

• name (str) – 字符串，如果提供，将覆盖任何自动派生的集合名称（或模块根命名空间上设置的名称，如果有的话。）

• config (dict) – 用于在返回新创建的 Collection 之前设置配置选项（节省你调用 configure 的时间。）如果导入的模块有根命名空间对象，config 将合并到其上（即覆盖任何冲突。）

• loaded_from (str) – 与常规类构造函数中的同名关键字参数相同——应该是找到模块的路径。

• auto_dash_names (bool) – 与常规类构造函数中的同名关键字参数相同——决定发出的名称是否自动添加短横线。

在 1.0 版本加入.

serialized() → Dict[str, Any]

返回适合序列化的此对象的版本。

请参阅 Program 及其 json 任务列表格式的文档；此方法是该功能的驱动。

在 1.0 版本加入.

subcollection_from_path(path: str) → Collection

给定子集合的 path，返回该子集合。

在 1.0 版本加入.

property task_names: Dict[str, List[str]]

将此集合的所有任务标识符作为一级字典返回。

具体来说，字典，其中主/”real”任务名称作为键，任何别名作为列表值。

它基本上将命名空间树折叠成一个易于扫描的调用字符串集合，因此适用于平面样式任务列表或转换为解析器上下文等用途。

在 1.0 版本加入.

task_with_config(name: str | None) → Tuple[str, Dict[str, Any]]

返回名为 name 的任务及其配置字典。

例如，在深度嵌套的树中，此方法返回 Task 和通过合并此 Collection 和任何嵌套的 Collections 创建的配置字典，直到实际持有 Task 的集合。

有关 name 参数的语义，请参阅 __getitem__。

返回:

Two-tuple of (Task, dict).

在 1.0 版本加入.

to_contexts(ignore_unknown_help: bool | None = None) → List[ParserContext]

将所有包含的任务和子任务作为解析器上下文列表返回。

参数:

ignore_unknown_help (bool) – 传递给每个任务的 get_arguments() 方法。有关详细信息，请参阅同名的配置选项。

在 1.0 版本加入.

在 1.7 版本发生变更: 添加了 ignore_unknown_help 关键字参数。

transform(name: str) → str

使用配置的自动短横线行为转换 name。

如果集合的 auto_dash_names 属性为 ``True``（默认），所有非前导/尾随下划线将转换为短横线。（前导/尾随下划线往往会在堆栈的其他地方被剥离。）

如果它为 False，则应用相反的操作——所有短横线将转换为下划线。

在 1.0 版本加入.