RunCommands
+++++++++++
A simple command runner that uses ``argparse`` from the Python standard
library under the hood. Runs on Python 3 only (3.7 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:: python
# 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.
* 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
* Write tests
.. _main documentation: http://runcommands.readthedocs.io/
.. _Read the Docs: `main documentation`_
Raw data
{
"_id": null,
"home_page": "https://runcommands.readthedocs.io",
"name": "runcommands",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6,<4.0",
"maintainer_email": "",
"keywords": "run,commands,console,scripts,terminal",
"author": "Wyatt Baldwin",
"author_email": "self@wyattbaldwin.com",
"download_url": "https://files.pythonhosted.org/packages/68/4f/7639beca21aa241110790323db1100490f8f7af37f5b5db04fc5bdc89db2/runcommands-1.0a71.tar.gz",
"platform": null,
"description": "RunCommands\n+++++++++++\n\nA simple command runner that uses ``argparse`` from the Python standard\nlibrary under the hood. Runs on Python 3 only (3.7 and up). Uses annotations to\nconfigure options.\n\nThere are two basic use cases:\n\n1. Standalone console scripts (including scripts with subcommands).\n2. Collections of commands (similar to make, Fabric, etc).\n\nBuilding on these, especially #2, there are a couple of more advanced\nuse cases:\n\n1. A simple orchestration/deployment tool. If you have a simple build\n process and just need to ``rsync`` some files to a server, a few\n simple commands might be all you need.\n2. A wrapper for more sophisticated orchestration/deployment tools--an\n alternative to the Bash scripts you might use to drive Ansible\n playbooks and the like.\n\nBasic Usage\n===========\n\nDefine a command:\n\n.. code-block:: python\n\n from runcommands import arg, command\n from runcommands.commands import local\n\n @command\n def test(*tests: arg(help='Specific tests to run (instead of using discovery)')):\n if tests:\n local(('python', '-m', 'unittest', tests))\n else:\n local('python -m unittest discover .')\n\nShow its help::\n\n > run test -h\n test [-h] [TESTS [TESTS ...]]\n\n positional arguments:\n TESTS Specific tests to run (instead of using discovery)\n\n optional arguments:\n -h, --help show this help message and exit\n\nRun it::\n\n > run test\n ..........\n ----------------------------------------------------------------------\n Ran 0 tests in 0.000s\n\n OK\n\nCreate a standalone console script using a standard setuptools entry\npoint:\n\n.. code-block:: python\n\n # setup.py\n setup(\n ...\n entry_points=\"\"\"\n [console_scripts]\n my-test-script = package.module:test.console_script\n\n \"\"\"\n )\n\nRun it (after reinstalling the package)::\n\n > my-test-script\n ..........\n ----------------------------------------------------------------------\n Ran 0 tests in 0.000s\n\n OK\n\nSee the `main documentation`_ for more information on installation,\ndefining & running commands, configuration, etc.\n\nFeatures\n========\n\n* Easily create standalone console scripts: simply define a function and\n wrap it with the ``@command`` decorator.\n* Easily create standalone console scripts that have subcommands (a la\n ``git``).\n* Create collections of commands (similar to make, Fabric, etc).\n* Run multiple commands in sequence: ``run build deploy``.\n* Uses ``argparse`` under the hood so command line usage is familiar.\n* Provides built-in help/usage for all commands via ``argparse``.\n* Provides command line completion (including example scripts for bash\n and fish).\n\nDocumentation\n=============\n\nDetailed documentation is on `Read the Docs`_.\n\nLicense\n=======\n\nMIT. See the LICENSE file in the source distribution.\n\nTODO\n====\n\n* Improve command line completion\n* Add more documentation and examples\n* Write tests\n\n.. _main documentation: http://runcommands.readthedocs.io/\n.. _Read the Docs: `main documentation`_\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A framework for writing console scripts and running commands",
"version": "1.0a71",
"split_keywords": [
"run",
"commands",
"console",
"scripts",
"terminal"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "4a1922494501459bf01cb808fd5ff079",
"sha256": "3d0dfa51b1d40435526f572b8b0298099c9369dd44d68ce5d0906ce579989f64"
},
"downloads": -1,
"filename": "runcommands-1.0a71-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4a1922494501459bf01cb808fd5ff079",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6,<4.0",
"size": 70710,
"upload_time": "2022-12-02T21:12:33",
"upload_time_iso_8601": "2022-12-02T21:12:33.511878Z",
"url": "https://files.pythonhosted.org/packages/da/cf/0a8bcea46d18df33ed36e96ecd59ed951c9877092ce89b569bb43a688283/runcommands-1.0a71-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "85cbb861d77d62f3f8b0e1c09c8f99f9",
"sha256": "d33b352a0fab76da4a8448da4b300fdf377f1ac54b22bc6036b8968a0d479a3e"
},
"downloads": -1,
"filename": "runcommands-1.0a71.tar.gz",
"has_sig": false,
"md5_digest": "85cbb861d77d62f3f8b0e1c09c8f99f9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6,<4.0",
"size": 61332,
"upload_time": "2022-12-02T21:12:36",
"upload_time_iso_8601": "2022-12-02T21:12:36.873144Z",
"url": "https://files.pythonhosted.org/packages/68/4f/7639beca21aa241110790323db1100490f8f7af37f5b5db04fc5bdc89db2/runcommands-1.0a71.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-02 21:12:36",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "runcommands"
}
JSON