Invoke

What is Invoke?

https://secure.travis-ci.org/pyinvoke/invoke.png?branch=master

Invoke is a Python (2.6+ and 3.2+) task execution tool & library, drawing inspiration from various sources to arrive at a powerful & clean feature set.

  • Like Ruby’s Rake tool and Invoke’s own predecessor Fabric 1.x, it provides a clean, high level API for running shell commands and defining/organizing task functions from a tasks.py file:

    from invoke import run, task
    
    @task
    def clean(docs=False, bytecode=False, extra=''):
        patterns = ['build']
        if docs:
            patterns.append('docs/_build')
        if bytecode:
            patterns.append('**/*.pyc')
        if extra:
            patterns.append(extra)
        for pattern in patterns:
            run("rm -rf %s" % pattern)
    
    @task
    def build(docs=False):
        run("python setup.py build")
        if docs:
            run("sphinx-build docs docs/_build")
    
  • From GNU Make, it inherits an emphasis on minimal boilerplate for common patterns and the ability to run multiple tasks in a single invocation:

    $ invoke clean build
    
  • Following the lead of most Unix CLI applications, it offers a traditional flag-based style of command-line parsing, deriving flag names and value types from task signatures (optionally, of course!):

    $ invoke clean --docs --bytecode build --docs --extra='**/*.pyo'
    $ invoke clean -d -b build --docs -e '**/*.pyo'
    $ invoke clean -db build -de '**/*.pyo'
    
  • Like many of its predecessors, it offers advanced features as well – namespacing, task aliasing, before/after hooks, parallel execution and more.

For documentation, including detailed installation information, please see http://docs.pyinvoke.org. Post-install usage information may be found in invoke --help.

You can install the development version via pip install invoke==dev.

See Getting started for a quick-start guide.

What changed recently?

See the changelog for details.

How can I install it?

The recommended way to get Invoke is to install the latest stable release via pip:

$ pip install invoke

We currently support Python 2.6/2.7 and Python 3.2+. Users still on Python 2.5 or older are urged to upgrade.

As long as you have a supported Python interpreter, there are no other dependencies. Invoke is pure-Python, and contains copies of its few dependencies within its source tree.

Note

See this blog post for background on our decision to vendorize dependencies.

What if I want the bleeding edge?

Users who don’t intend to actively develop, but who still want to obtain the in-development version (to help test new features or to cope with any unfortunate lapses in release schedule) can still use pip, but should give the ==dev “version” explicitly:

$ pip install invoke==dev

How do I use it?

It’s broken!

Are you sure? Make sure you’ve read the FAQ!

It’s definitely broken, or doesn’t do what I want! How can I submit bugs?

Before submitting a bug, please do the following:

If you’ve found a new bug or thought up a new feature, please submit an issue on our Github at pyinvoke/invoke.

Warning

Please include the following info when submitting bug reports to ensure a prompt response:

  • Your Python interpreter version.
  • Your operating system & version.
  • What version of Invoke you’re using (& how you installed it).
  • Steps to replicate the error, if possible (including a copy of your code, the command you used to invoke it, and the full output of your run).

How can I contribute?

Thanks for asking! Please see our contribution documentation for details.

Our test suite is stored in the tests/ folder, and may be executed via $ invoke test (or, if your Invoke is currently inoperable, $ spec will suffice.)

How can I contact the developers / get help / see announcements?

You can get in touch with the developer & user community in any of the following ways: