Collection: Task collections

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

A collection of executable tasks.

Create a new task collection/namespace.

May call with no arguments and use e.g. add_task/add_collection to insert objects, e.g.:

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

Otherwise, all *args 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')
__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.

__init__(*args, **kwargs)

Create a new task collection/namespace.

May call with no arguments and use e.g. add_task/add_collection to insert objects, e.g.:

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

Otherwise, all *args 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')
add_task(task, name=None)

Adds Task task to this collection.

The name the task is bound with is taken, in order, from:

* The ``name`` kwarg;
* If that is not given, the task object's ``name`` attribute;
* If that is empty, the task object's wrapped callable's ``.func_name``
attribute.
classmethod from_module(module)

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

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.

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