collection
¶
-
class
invoke.collection.
Collection
(*args, **kwargs)¶ A collection of executable tasks. See Constructing namespaces.
New in version 1.0.
-
__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 orNone
. 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.
-
add_collection
(coll, name=None, default=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.5.
New in version 1.0.
- coll – The
-
add_task
(task, name=None, aliases=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
.) - 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.
- task – The
-
configuration
(taskpath=None)¶ 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)¶ (Recursively) merge
options
into the currentconfiguration
.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, name=None, config=None, loaded_from=None, auto_dash_names=None)¶ Return a new
Collection
created frommodule
.Inspects
module
for anyTask
instances and adds them to a newCollection
, returning it. If any explicit namespace collections exist (namedns
ornamespace
) 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 resultingCollection
(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 toconfigure
.)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
()¶ Return an appropriate-for-serialization version of this object.
See the documentation for
Program
and itsjson
task listing format; this method is the driver for that functionality.New in version 1.0.
-
subcollection_from_path
(path)¶ Given a
path
to a subcollection, return that subcollection.New in version 1.0.
-
task_names
¶ 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)¶ 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 thisCollection
and any nestedCollections
, up through the one actually holding theTask
.See
__getitem__
for semantics of thename
argument.Returns: Two-tuple of ( Task
,dict
).New in version 1.0.
-
to_contexts
()¶ Returns all contained tasks and subtasks as a list of parser contexts.
New in version 1.0.
-
transform
(name)¶ Transform
name
with the configured auto-dashes behavior.If the collection’s
auto_dash_names
attribute isTrue
(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.
-