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

A collection of executable tasks.


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. ‘’. Subcollection default tasks will be returned on the subcollection’s name.

add_collection(coll, name=None)

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

  • coll – The Collection to add.
  • name (str) – The name to attach the collection as. Defaults to the collection’s own internal name.
add_task(task, name=None, aliases=None, default=None)

Add Task task to this collection.

  • 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.

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.

(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 '' than simply 'target'.

Parameters:options – An object implementing the dictionary protocol.
classmethod from_module(module, name=None, config=None, loaded_from=None, auto_dash_names=None)

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.

  • 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.

Obtain first collection + remainder, of a task path.

E.g. for "subcollection.taskname", return ("subcollection", "taskname"); for "subcollection.nested.taskname" return ("subcollection", "nested.taskname"), etc.

An empty path becomes simply ('', '').


Return all task identifiers for this collection as a dict.

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


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).

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


Transform name with the configured auto-dashes behavior.

If auto_dash_names 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.


Take a Lexicon and apply transform to its keys and aliases.

Returns:A new Lexicon.