Invoke

2.2.1 · active · verified Sat Mar 28

Invoke is a Python library for managing shell-oriented subprocesses and organizing executable Python code into CLI-invokable tasks. It provides a clean, high-level API for running shell commands and defining/organizing task functions from a `tasks.py` file, drawing inspiration from tools like Make and Rake. The current version is 2.2.1, with releases occurring periodically to introduce new features and address issues.

Warnings

breaking Invoke 2.0.0 removed support for Python versions less than 3.6. Code targeting older Python 2.x or early Python 3.x (e.g., 3.4, 3.5) will break.
Fix: Ensure your project uses Python 3.6 or newer. Update your Python environment if necessary.
breaking The `Task.argspec` method's return value changed in 2.0.0 to return an `inspect.Signature` object instead of a tuple. This affects users directly inspecting task function signatures programmatically.
Fix: Adjust code that directly accesses `Task.argspec` to handle the `inspect.Signature` object. For most users, this will not be an issue as `Task.argspec` is an advanced internal method.
breaking The default value for `MockContext.repeat_init` changed from `False` to `True` in Invoke 2.0.0. This can affect testing setups using `MockContext`.
Fix: Review existing tests that use `MockContext` and explicitly set `repeat_init=False` in the constructor if the old behavior is desired. Otherwise, adapt tests to the new default.
deprecated The `invoke.util.encode_output` function was effectively removed in Invoke 2.0.0 as it became a no-op under Python 3.
Fix: Remove any manual calls to `invoke.util.encode_output` from your codebase, as it no longer serves a purpose in Python 3 environments.
gotcha All functions decorated with `@task` must accept at least one positional argument, conventionally named `c`, `ctx`, or `context`, which represents the `invoke.Context` object. Forgetting this argument will cause the task to fail at runtime.
Fix: Always include `c` (or `ctx`/`context`) as the first positional argument in your `@task` decorated functions: `@task def my_task(c, ...):`

Install

pip install invoke Install latest stable release

Imports

task
```
from invoke import task
```
Used as a decorator to define CLI-invokable functions.
Collection
```
from invoke import Collection
```
Used to organize tasks into namespaces.
run
```
from invoke import run
```
Used for programmatic execution of shell commands outside of a task context.

Quickstart

Create a `tasks.py` file in your project root. Define functions decorated with `@task`, ensuring the first argument is `c` (for context). Then run tasks from your terminal using `invoke <task_name>` (e.g., `invoke greet --name='Alice'`).

from invoke import task

@task
def greet(c, name='World'):
    """Says hello to the specified name."""
    print(f"Hello, {name}!")

@task
def clean(c):
    """Removes temporary build files."""
    # Example of running a shell command
    c.run("echo 'Cleaning build directory...'", warn=True)
    # For a real scenario, you might do:
    # c.run("rm -rf build/")

view raw JSON →