Class Collection

invoke/collection.py:12–608

A collection of executable tasks. See :doc:`/concepts/namespaces`. .. versionadded:: 1.0

class Collection:
    """
    A collection of executable tasks. See :doc:`/concepts/namespaces`.

    .. versionadded:: 1.0
    """

    def __init__(self, *args: Any, **kwargs: Any) -> None:
        """
        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.

        In either case:

        * The first positional argument may be a string, which (if given) is
          used as the collection's default name when performing namespace
          lookups;
        * A ``loaded_from`` keyword argument may be given, which sets metadata
          indicating the filesystem path the collection was loaded from. This
          is used as a guide when loading per-project :ref:`configuration files
          <config-hierarchy>`.
        * An ``auto_dash_names`` kwarg may be given, controlling whether task
          and collection names have underscores turned to dashes in most cases;
          it defaults to ``True`` but may be set to ``False`` to disable.

          The CLI machinery will pass in the value of the
          ``tasks.auto_dash_names`` config value to this kwarg.

        **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 abovementioned
        optional positional 'name' argument and ``loaded_from`` kwarg) are
        expected to be `.Task` or `.Collection` instances which will be passed