https://github.com/wylee/runcommands
Simple command/task runner that uses Python's standard library argparse under the hood
https://github.com/wylee/runcommands
argparse command-line commands completion console-scripts python python3 runner tasks
Last synced: about 1 month ago
JSON representation
Simple command/task runner that uses Python's standard library argparse under the hood
- Host: GitHub
- URL: https://github.com/wylee/runcommands
- Owner: wylee
- License: mit
- Created: 2017-02-23T19:44:07.000Z (almost 9 years ago)
- Default Branch: dev
- Last Pushed: 2025-01-25T03:10:19.000Z (about 1 year ago)
- Last Synced: 2025-09-29T12:26:48.906Z (4 months ago)
- Topics: argparse, command-line, commands, completion, console-scripts, python, python3, runner, tasks
- Language: Python
- Homepage: https://runcommands.readthedocs.io/
- Size: 878 KB
- Stars: 10
- Watchers: 3
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.rst
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
RunCommands
+++++++++++
A simple command runner that uses ``argparse`` from the Python standard
library under the hood. Runs on Python 3 only (3.9 and up). Uses
annotations to configure options.
There are two basic use cases:
1. Standalone console scripts (including scripts with subcommands).
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:
.. code-block:: python
from runcommands import arg, command
from runcommands.commands import local
@command
def test(*tests: arg(help='Specific tests to run (instead of using discovery)')):
if tests:
local(('python', '-m', 'unittest', tests))
else:
local('python -m unittest discover .')
Show its help::
> run test -h
test [-h] [TESTS [TESTS ...]]
positional arguments:
TESTS Specific tests to run (instead of using discovery)
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:
.. code-block:: toml
# pyproject.toml
[project.scripts]
my-test-script = "package.module:test.console_script"
Reinstall the package to install the script and then run it::
> 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.
* Easily create standalone console scripts that have subcommands (a la
``git``).
* 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
* Add more tests (current coverage is 45%)
.. _main documentation: http://runcommands.readthedocs.io/
.. _Read the Docs: `main documentation`_