Collection: Task collections

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

A collection of executable tasks.

Create a new task collection/namespace.

Collection offers a set of methods for building a collection of tasks from scratch, plus a convenient constructor wrapping said API.

The method approach

May initialize with no arguments and use methods (e.g. add_task/add_collection) to insert objects:

c = Collection()
c.add_task(some_task)

If an initial string argument is given, it is used as the default name for this collection, should it be inserted into another collection as a sub-namespace:

docs = Collection('docs')
docs.add_task(doc_task)
ns = Collection()
ns.add_task(top_level_task)
ns.add_collection(docs)
# Valid identifiers are now 'top_level_task' and 'docs.doc_task'
# (assuming the task objects were actually named the same as the
# variables we're using :))

For details, see the API docs for the rest of the class.

The constructor approach

All *args given to Collection (besides the optional first ‘name’ argument) are expected to be Task or Collection instances which will be passed to add_task/add_collection as appropriate. Module objects are also valid (as they are for add_collection). For example, the below snippet results in the same two task identifiers as the one above:

ns = Collection(top_level_task, Collection('docs', doc_task))

If any **kwargs are given, the keywords are used as the initial name arguments for the respective values:

ns = Collection(
    top_level_task=some_other_task,
    docs=Collection(doc_task)
)

That’s exactly equivalent to:

docs = Collection(doc_task)
ns = Collection()
ns.add_task(some_other_task, 'top_level_task')
ns.add_collection(docs, 'docs')

See individual methods’ API docs for details.

__getitem__(name=None)

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.

add_task(task, name=None, default=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.)
  • default – Whether this task should be the collection default.
configuration(taskpath=None)

Obtain merged configuration values from collection & children.

Note

Merging uses copy.deepcopy to prevent state bleed.

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.
configure(options)

Merge options dict into this collection’s configuration.

Options configured this way will be available to all contextualized 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.
classmethod from_module(module, name=None, config=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.

Parameters:
  • name – 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

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

split_path(path)

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 ('', '').

task_names

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.

task_with_config(name)

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

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

Previous topic

cli: CLI entrypoint

Next topic

Context: Configuration & execution state

This Page