collection

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

A collection of executable tasks. See Constructing namespaces.

New in version 1.0.

__eq__(other: object) bool

Return self==value.

__getitem__(name: Optional[str] = None) Any

Returns task named name. Honors aliases and subcollections.

If this collection has a default task, it is returned when name is empty or None. If empty input is given and no task has been selected as the default, ValueError will be raised.

Tasks within subcollections should be given in dotted form, e.g. ‘foo.bar’. Subcollection default tasks will be returned on the subcollection’s name.

New in version 1.0.

__hash__ = None
__repr__() str

Return repr(self).

add_collection(coll: invoke.collection.Collection, name: Optional[str] = None, default: Optional[bool] = None) None

Add Collection coll as a sub-collection of this one.

Parameters
  • coll – The Collection to add.

  • name (str) – The name to attach the collection as. Defaults to the collection’s own internal name.

  • default – Whether this sub-collection(‘s default task-or-collection) should be the default invocation of the parent collection.

New in version 1.0.

Changed in version 1.5: Added the default parameter.

add_task(task: invoke.tasks.Task, name: Optional[str] = None, aliases: Optional[Tuple[str, ...]] = None, default: Optional[bool] = None) None

Add Task task to this collection.

Parameters
  • task – The Task object to add to this collection.

  • name – Optional string name to bind to (overrides the task’s own self-defined name attribute and/or any Python identifier (i.e. .func_name.)

  • aliases – Optional iterable of additional names to bind the task as, on top of the primary name. These will be used in addition to any aliases the task itself declares internally.

  • default – Whether this task should be the collection default.

New in version 1.0.

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

Obtain merged configuration values from collection & children.

Parameters

taskpath – (Optional) Task name/path, identical to that used for __getitem__ (e.g. may be dotted for nested tasks, etc.) Used to decide which path to follow in the collection tree when merging config values.

Returns

A dict containing configuration values.

New in version 1.0.

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

(Recursively) merge options into the current configuration.

Options configured this way will be available to all tasks. It is recommended to use unique keys to avoid potential clashes with other config options

For example, if you were configuring a Sphinx docs build target directory, it’s better to use a key like 'sphinx.target' than simply 'target'.

Parameters

options – An object implementing the dictionary protocol.

Returns

None.

New in version 1.0.

classmethod from_module(module: module, name: Optional[str] = None, config: Optional[Dict[str, Any]] = None, loaded_from: Optional[str] = None, auto_dash_names: Optional[bool] = None) invoke.collection.Collection

Return a new Collection created from module.

Inspects module for any Task instances and adds them to a new Collection, returning it. If any explicit namespace collections exist (named ns or namespace) a copy of that collection object is preferentially loaded instead.

When the implicit/default collection is generated, it will be named after the module’s __name__ attribute, or its last dotted section if it’s a submodule. (I.e. it should usually map to the actual .py filename.)

Explicitly given collections will only be given that module-derived name if they don’t already have a valid .name attribute.

If the module has a docstring (__doc__) it is copied onto the resulting Collection (and used for display in help, list etc output.)

Parameters
  • name (str) – A string, which if given will override any automatically derived collection name (or name set on the module’s root namespace, if it has one.)

  • config (dict) –

    Used to set config options on the newly created Collection before returning it (saving you a call to configure.)

    If the imported module had a root namespace object, config is merged on top of it (i.e. overriding any conflicts.)

  • loaded_from (str) – Identical to the same-named kwarg from the regular class constructor - should be the path where the module was found.

  • auto_dash_names (bool) – Identical to the same-named kwarg from the regular class constructor - determines whether emitted names are auto-dashed.

New in version 1.0.

serialized() Dict[str, Any]

Return an appropriate-for-serialization version of this object.

See the documentation for Program and its json task listing format; this method is the driver for that functionality.

New in version 1.0.

subcollection_from_path(path: str) invoke.collection.Collection

Given a path to a subcollection, return that subcollection.

New in version 1.0.

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

Return all task identifiers for this collection as a one-level dict.

Specifically, a dict with the primary/”real” task names as the key, and any aliases as a list value.

It basically collapses the namespace tree into a single easily-scannable collection of invocation strings, and is thus suitable for things like flat-style task listings or transformation into parser contexts.

New in version 1.0.

task_with_config(name: Optional[str]) Tuple[str, Dict[str, Any]]

Return task named name plus its configuration dict.

E.g. in a deeply nested tree, this method returns the Task, and a configuration dict created by merging that of this Collection and any nested Collections, up through the one actually holding the Task.

See __getitem__ for semantics of the name argument.

Returns

Two-tuple of (Task, dict).

New in version 1.0.

to_contexts(ignore_unknown_help: Optional[bool] = None) List[invoke.parser.context.ParserContext]

Returns all contained tasks and subtasks as a list of parser contexts.

Parameters

ignore_unknown_help (bool) – Passed on to each task’s get_arguments() method. See the config option by the same name for details.

New in version 1.0.

Changed in version 1.7: Added the ignore_unknown_help kwarg.

transform(name: str) str

Transform name with the configured auto-dashes behavior.

If the collection’s auto_dash_names attribute is True (default), all non leading/trailing underscores are turned into dashes. (Leading/trailing underscores tend to get stripped elsewhere in the stack.)

If it is False, the inverse is applied - all dashes are turned into underscores.

New in version 1.0.