tasks: Task class & task-generating decorators

This module contains the core Task class & convenience decorators used to generate new tasks.

class invoke.tasks.Task(body, name=None, contextualized=False, aliases=(), positional=None, optional=(), default=False, auto_shortflags=True, help=None, pre=None)

Core object representing an executable task & its argument specification.


Returns two-tuple:

  • First item is list of arg names, in order defined.

    • I.e. we cannot simply use a dict’s keys() method here.
  • Second item is dict mapping arg names to default values or task.NO_DEFAULT (i.e. an ‘empty’ value distinct from None).


Return a list of Argument objects representing this task’s signature.

invoke.tasks.ctask(*args, **kwargs)

Wrapper for task which sets contextualized=True by default.

Please see task for documentation.

invoke.tasks.task(*args, **kwargs)

Marks wrapped callable object as a valid Invoke task.

May be called without any parentheses if no extra options need to be specified. Otherwise, the following keyword arguments are allowed in the parenthese’d form:

  • name: Default name to use when binding to a Collection. Useful for avoiding Python namespace issues (i.e. when the desired CLI level name can’t or shouldn’t be used as the Python level name.)
  • contextualized: Hints to callers (especially the CLI) that this task expects to be given a Context object as its first argument when called.
  • aliases: Specify one or more aliases for this task, allowing it to be invoked as multiple different names. For example, a task named mytask with a simple @task wrapper may only be invoked as "mytask". Changing the decorator to be @task(aliases=['myothertask']) allows invocation as "mytask" or "myothertask".
  • positional: Iterable overriding the parser’s automatic “args with no default value are considered positional” behavior. If a list of arg names, no args besides those named in this iterable will be considered positional. (This means that an empty list will force all arguments to be given as explicit flags.)
  • optional: Iterable of argument names, declaring those args to have optional values. Such arguments may be given as value-taking options (e.g. --my-arg=myvalue, wherein the task is given "myvalue") or as Boolean flags (--my-arg, resulting in True).
  • default: Boolean option specifying whether this task should be its collection’s default task (i.e. called if the collection’s own name is given.)
  • auto_shortflags: Whether or not to automatically create short flags from task options; defaults to True.
  • help: Dict mapping argument names to their help strings. Will be displayed in --help output.
  • pre: List of task names, for tasks that should get run prior to the wrapped task whenever it is executed via the command line.

If any non-keyword arguments are given, they are taken as the value of the pre kwarg for convenience’s sake. (It is an error to give both *args and pre at the same time.)

Previous topic

Runner: Executes shell commands

Next topic

util: Internal utilities

This Page