invoke.tasks

Describes execution of a `.Task`, typically with pre-supplied arguments. Useful for setting up :ref:`pre/post task invocations <parameterizing-pre-post-tasks>`. It's actually just a convenient wrapper around the `.Call` class, which may be used directly instead if desired. For example, here's two build-like tasks that both refer to a ``setup`` pre-task, one with no baked-in argument values (and thus no need to use `.call`), and one that toggles a boolean flag:: @task def setup(c, clean=False): if clean: c.run("rm -rf target") # ... setup things here ... c.run("tar czvf target.tgz target") @task(pre=[setup]) def build(c): c.run("build, accounting for leftover files...") @task(pre=[call(setup, clean=True)]) def clean_build(c): c.run("build, assuming clean slate...") Please see the constructor docs for `.Call` for details - this function's ``args`` and ``kwargs`` map directly to the same arguments as in that method. .. versionadded:: 1.0

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.) * ``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 :ref:`optional values <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``). * ``iterable``: Iterable of argument names, declaring them to :ref:`build iterable values <iterable-flag-values>`. * ``incrementable``: Iterable of argument names, declaring them to :ref:`increment their values <incrementable-flag-values>`. * ``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. For arguments containing underscores (which are transformed into dashes on the CLI by default), either the dashed or underscored version may be supplied here. * ``pre``, ``post``: Lists of task objects to execute prior to, or after, the wrapped task whenever it is executed. * ``autoprint``: Boolean determining whether to automatically print this task's return value to standard output when invoked directly via the CLI. Defaults to False. * ``klass``: Class to instantiate/return. Defaults to `.Task`. 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.) .. versionadded:: 1.0 .. versionchanged:: 1.1 Added the ``klass`` keyword argument.