Skip to content
Simple command/task runner that uses Python's standard library argparse under the hood
Branch: develop
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs
runcommands
.travis.yml
CHANGELOG
LICENSE
MANIFEST.in
README.rst
commands.py
commands.yaml
setup.cfg
setup.py
tox.ini

README.rst

RunCommands

A simple command runner that uses argparse from the Python standard library under the hood. Runs on Python 3 only (3.5 and up).

There are two basic use cases:

  1. Standalone console scripts.
  2. Collections of commands (similar to make, Fabric, etc).

Building on these, especially #2, there are a couple of more advanced use cases:

  1. A simple orchestration/deployment tool. If you have a simple build process and just need to rsync some files to a server, a few simple commands might be all you need.
  2. A wrapper for more sophisticated orchestration/deployment tools--an alternative to the Bash scripts you might use to drive Ansible playbooks and the like.

Basic Usage

Define a command:

from runcommands import command
from runcommands.commands import local

@command
def test():
    local('python -m unittest discover .')

Show its help:

> run test -h
usage: test [-h]

optional arguments:
  -h, --help  show this help message and exit

Run it:

> run test
..........
----------------------------------------------------------------------
Ran 0 tests in 0.000s

OK

Create a standalone console script using a standard setuptools entry point:

# setup.py
setup(
    ...
    entry_points="""
    [console_scripts]
    my-test-script = package.module:test.console_script

    """
)

Run it (after reinstalling the package):

> my-test-script
..........
----------------------------------------------------------------------
Ran 0 tests in 0.000s

OK

See the main documentation for more information on installation, defining & running commands, configuration, etc.

Features

  • Easily create standalone console scripts: simply define a function and wrap it with the @command decorator.
  • Create collections of commands (similar to make, Fabric, etc).
  • Run multiple commands in sequence: run build deploy.
  • Uses argparse under the hood so command line usage is familiar.
  • Provides built-in help/usage for all commands via argparse.
  • Provides command line completion (including example scripts for bash and fish).

Documentation

Detailed documentation is on Read the Docs.

License

MIT. See the LICENSE file in the source distribution.

TODO

  • Improve command line completion
  • Add more documentation and examples
  • Write tests
You can’t perform that action at this time.