Quick Start

Summary

• Add runcommands dependency
• Add commands.py to top level project directory
• Import built in commands
• Write custom commands

Details

First, add runcommands to the project’s requirements. If you’re using setuptools, add it to install_requires in setup.py. Or you can add it to your pip requirements file.

Optionally, you can just run pip install runcommands or use one of the other Installation methods.

Next, create a Python module named commands.py in the top level of the project. In that module, you can import the built-in commands like this:

# commands.py
from runcommands.commands import copy_file, local

And then run them like this:

> run local --help
local [-h] [-b] [--no-background] [-c CD] [-e ENVIRON] [-r]
             [--no-replace-env] [-p [PATHS [PATHS ...]]] [-s] [--no-shell]
             [-S STDOUT] [--stderr STDERR] [-E] [--no-echo] [-R]
             [--no-raise-on-error] [-d] [--no-dry-run]
             ARG [ARG ...]

Run a local command via :func:`subprocess.run`

[...]

> run local ls
[...]

Here’s how you define a custom command:

# commands.py
from runcommands import command
from runcommands.commands import copy_file, local

@command
def test(where='.'):
    """Discover and run unit tests."""
    local(['python', '-m', 'unittest', 'discover', where])

The new test command can be run like this:

> run test
....................