Invoke

What is Invoke?

BIG HONKIN’ DISCLAIMER: This software is currently in beta. It’s test-driven and dogfooded, but feature set & documentation has holes & rough spots. Please make sure you search the known issues before submitting new bug reports – we already know it doesn’t do X, Y and Z and will be sprinting to beef things up ASAP.

Thank you!

---

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?

Getting started

Many core ideas & API calls are explained in the tutorial/getting-started document:

• Getting started
  • Defining and running task functions
  • Parameterizing tasks
  • Listing tasks
  • Running shell commands
  • Declaring pre-tasks
  • Creating namespaces
  • Handling configuration state
    • Using contexts in your tasks
    • Boilerplate reduction

Concepts

Dig deeper into specific topics:

• Command-line interface
  • Background
    • Basics
    • The multiple tasks vs positional args problem
  • Invocation basics
    • Tasks and task options
    • Multiple tasks
    • Mixing things up
  • Type mapping
    • Methodologies
    • Other types
• Task execution
  • Base case
  • Pre-tasks
  • Task deduplication
  • Foregoing deduplication of tasks
  • Parameterizing tasks
  • Getting hairy: one task, with one pre-task, parameterized
  • Still hairy: one task, with a pre-task that itself has a pre-task
  • All the things: two tasks, each with pre-tasks, both parameterized
• Loading collections
  • Task module discovery
  • Additional load options
• Constructing namespaces
  • Starting out
  • Naming your tasks
    • Aliases
  • Nesting collections
  • Importing modules as collections
  • Default tasks
  • Mix and match
  • More shortcuts

API

Know what you’re looking for & just need API details? View our auto-generated API documentation:

• cli: CLI entrypoint
• Collection: Task collections
• Context: Configuration & execution state
• exceptions: Custom exception subclasses
• Executor: Task execution machinery
• Loader: Loading of task definition files
• parser: Command-line parser
  • Argument: CLI arguments/flags
  • Context: Task-oriented parser context
  • Parser: Core parsing state machine
• Runner: Executes shell commands
• tasks: Task class & task-generating decorators
• util: Internal utilities

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

Before submitting a bug, please do the following:

• Search the existing bug reports to make sure it’s not a pre-existing issue.
• Check with the mailing list or IRC in case the problem is non-bug-related.

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.

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:

• IRC: #invoke on Freenode
• Twitter: @pyinvoke
• Mailing list: invoke@librelist.com (see the LibreList homepage for usage details).
• Blog: TK