tasks

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

class invoke.tasks.Call(task: Task, called_as: str | None = None, args: Tuple[str, ...] | None = None, kwargs: Dict[str, Any] | None = None)

Represents a call/execution of a Task with given (kw)args.

Similar to partial with some added functionality (such as the delegation to the inner task, and optional tracking of the name it’s being called by.)

在 1.0 版本加入.

__eq__(other: object) → bool

Return self==value.

__hash__ = None
__init__(task: Task, called_as: str | None = None, args: Tuple[str, ...] | None = None, kwargs: Dict[str, Any] | None = None) → None

Create a new Call object.

参数:

  • task – The Task object to be executed.

  • called_as (str) – The name the task is being called as, e.g. if it was called by an alias or other rebinding. Defaults to None, aka, the task was referred to by its default name.

  • args (tuple) – Positional arguments to call with, if any. Default: None.

  • kwargs (dict) – Keyword arguments to call with, if any. Default: None.

__repr__() → str

Return repr(self).

__weakref__

list of weak references to the object

clone(into: Type[Call] | None = None, with_: Dict[str, Any] | None = None) → Call

Return a standalone copy of this Call.

Useful when parameterizing task executions.

参数:

  • into – A subclass to generate instead of the current class. Optional.

  • with (dict) –

    A dict of additional keyword arguments to use when creating the new clone; typically used when cloning into a subclass that has extra args on top of the base class. Optional.

    备注

    This dict is used to .update() the original object’s data (the return value from its clone_data), so in the event of a conflict, values in with_ will win out.

在 1.0 版本加入.

在 1.1 版本发生变更: Added the with_ kwarg.

clone_data() → Dict[str, Any]

Return keyword args suitable for cloning this call into another.

在 1.1 版本加入.

make_context(config: Config) → Context

Generate a Context appropriate for this call, with given config.

在 1.0 版本加入.

class invoke.tasks.Task(body: Callable, name: str | None = None, aliases: Iterable[str] = (), positional: Iterable[str] | None = None, optional: Iterable[str] = (), default: bool = False, auto_shortflags: bool = True, help: Dict[str, Any] | None = None, pre: List[str] | str | None = None, post: List[str] | str | None = None, autoprint: bool = False, iterable: Iterable[str] | None = None, incrementable: Iterable[str] | None = None)

Core object representing an executable task & its argument specification.

For the most part, this object is a clearinghouse for all of the data that may be supplied to the @task decorator, such as name, aliases, positional etc, which appear as attributes.

In addition, instantiation copies some introspection/documentation friendly metadata off of the supplied body object, such as __doc__, __name__ and __module__, allowing it to “appear as” body for most intents and purposes.

在 1.0 版本加入.

__call__(*args: Any, **kwargs: Any) → T

Call self as a function.

__eq__(other: object) → bool

Return self==value.

__hash__() → int

Return hash(self).

__init__(body: Callable, name: str | None = None, aliases: Iterable[str] = (), positional: Iterable[str] | None = None, optional: Iterable[str] = (), default: bool = False, auto_shortflags: bool = True, help: Dict[str, Any] | None = None, pre: List[str] | str | None = None, post: List[str] | str | None = None, autoprint: bool = False, iterable: Iterable[str] | None = None, incrementable: Iterable[str] | None = None) → None
__repr__() → str

Return repr(self).

__weakref__

list of weak references to the object

argspec(body: Callable) → Signature

Returns a modified inspect.Signature based on that of body.

返回:

an inspect.Signature matching that of body, but with the initial context argument removed.

抛出:

TypeError – if the task lacks an initial positional Context argument.

在 1.0 版本加入.

在 2.0 版本发生变更: Changed from returning a two-tuple of (arg_names, spec_dict) to returning an inspect.Signature.

get_arguments(ignore_unknown_help: bool | None = None) → List[Argument]

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

参数:

ignore_unknown_help (bool) – Controls whether unknown help flags cause errors. See the config option by the same name for details.

在 1.0 版本加入.

在 1.7 版本发生变更: Added the ignore_unknown_help kwarg.

invoke.tasks.call(task: Task, *args: Any, **kwargs: Any) → Call

Describes execution of a Task, typically with pre-supplied arguments.

Useful for setting up pre/post task invocations. 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.

在 1.0 版本加入.

invoke.tasks.task(*args: Any, **kwargs: Any) → Callable

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 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 build iterable values.

  • incrementable: Iterable of argument names, declaring them to increment their 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.)

在 1.0 版本加入.

在 1.1 版本发生变更: Added the klass keyword argument.