.. image:: https://github.com/timcera/cltoolbox/actions/workflows/python-package.yml/badge.svg
:alt: Tests
:target: https://github.com/timcera/cltoolbox/actions/workflows/python-package.yml
:height: 20
.. image:: https://img.shields.io/coveralls/github/timcera/cltoolbox
:alt: Test Coverage
:target: https://coveralls.io/r/timcera/cltoolbox?branch=master
:height: 20
.. image:: https://img.shields.io/pypi/v/cltoolbox.svg
:alt: Latest release
:target: https://pypi.python.org/pypi/cltoolbox/
:height: 20
.. image:: http://img.shields.io/pypi/l/cltoolbox.svg
:alt: BSD-3 clause license
:target: https://pypi.python.org/pypi/cltoolbox/
:height: 20
.. image:: http://img.shields.io/pypi/dd/cltoolbox.svg
:alt: cltoolbox downloads
:target: https://pypi.python.org/pypi/cltoolbox/
:height: 20
.. image:: https://img.shields.io/pypi/pyversions/cltoolbox
:alt: PyPI - Python Version
:target: https://pypi.org/project/cltoolbox/
:height: 20
cltoolbox: Easy Command Line Interfaces
=======================================
cltoolbox is a wrapper around ``argparse``, and allows you to write complete CLI
applications in seconds using a simple decorator.
Significant portions of this code are based on `mando`. The primary
differences between `mando` and `cltoolbox` are:
* `cltoolbox` supports automatic detection of Sphinx, Google, and Numpy
docstring formats by using the `docstring_parser` library
* `cltoolbox` supports python 3.7+
If you need support of the `mando` formatted docstring or python 2 you have to
use `mando` instead of `cltoolbox`.
Installation
------------
pip
~~~
.. code-block:: bash
pip install cltoolbox
conda
~~~~~
.. code-block:: bash
conda install -c conda-forge cltoolbox
The problem
-----------
The ``argparse`` module that comes with Python requires a programmer to
duplicate information that Python can easily parse from the function signature
and docstring. The ``cltoolbox`` does this for you by using decorators.
Quickstart
----------
.. code-block:: python
from cltoolbox import command, main
@command
def echo(text, capitalize=False):
"""Echo the given text."""
if capitalize:
text = text.upper()
print(text)
if __name__ == "__main__":
main()
Generated help:
.. code-block:: console
$ python example.py -h
usage: example.py [-h] {echo} ...
positional arguments:
{echo}
echo Echo the given text.
optional arguments:
-h, --help show this help message and exit
$ python example.py echo -h
usage: example.py echo [-h] [--capitalize] text
Echo the given text.
positional arguments:
text
optional arguments:
-h, --help show this help message and exit
--capitalize
Actual usage:
.. code-block:: console
$ python example.py echo spam
spam
$ python example.py echo --capitalize spam
SPAM
A *real* example
----------------
Something more complex and real-world-*ish*. The code:
.. code-block:: python
from cltoolbox import command, main
@command
def push(repository, all=False, dry_run=False, force=False, thin=False):
"""Update remote refs along with associated objects.
:param repository: Repository to push to.
:param --all: Push all refs.
:param -n, --dry-run: Dry run.
:param -f, --force: Force updates.
:param --thin: Use thin pack."""
print(
"Pushing to {0}. All: {1}, dry run: {2}, force: {3}, thin: {4}".format(
repository, all, dry_run, force, thin
)
)
if __name__ == "__main__":
main()
cltoolbox understands Sphinx, Google, and Numpy dostrings, from which it can
create short options and their help for you.
.. code-block:: console
$ python git.py push -h
usage: git.py push [-h] [--all] [-n] [-f] [--thin] repository
Update remote refs along with associated objects.
positional arguments:
repository Repository to push to.
optional arguments:
-h, --help show this help message and exit
--all Push all refs.
-n, --dry-run Dry run.
-f, --force Force updates.
--thin Use thin pack.
Let's try it!
.. code-block:: console
$ python git.py push --all myrepo
Pushing to myrepo. All: True, dry run: False, force: False, thin: False
$ python git.py push --all -f myrepo
Pushing to myrepo. All: True, dry run: False, force: True, thin: False
$ python git.py push --all -fn myrepo
Pushing to myrepo. All: True, dry run: True, force: True, thin: False
$ python git.py push --thin -fn myrepo
Pushing to myrepo. All: False, dry run: True, force: True, thin: True
$ python git.py push --thin
usage: git.py push [-h] [--all] [-n] [-f] [--thin] repository
git.py push: error: too few arguments
Amazed uh? Yes, cltoolbox got the short options and the help from the docstring!
You can put much more in the docstring, and if that isn't enough, there's an
``@arg`` decorator to customize the arguments that get passed to argparse.
Type annotations
----------------
cltoolbox understands Python 3-style type annotations and will warn the user if the
arguments given to a command are of the wrong type.
.. code-block:: python
from cltoolbox import command, main
@command
def duplicate(string, times: int):
"""Duplicate text.
:param string: The text to duplicate.
:param times: How many times to duplicate."""
print(string * times)
if __name__ == "__main__":
main()
.. code-block:: console
$ python3 test.py duplicate "test " 5
test test test test test
$ python3 test.py duplicate "test " foo
usage: test.py duplicate [-h] string times
test.py duplicate: error: argument times: invalid int value: 'foo'
The `cltoolbox` supports shell autocompletion via the
``argcomplete`` package and supports custom format classes. For a complete
documentation, visit https://timcera.bibucket.io/cltoolbox/.
Raw data
{
"_id": null,
"home_page": null,
"name": "cltoolbox",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "python, cli, argparse, arguments, command line, keyword arguments, docstring",
"author": null,
"author_email": "Tim Cera <tim@cerazone.net>",
"download_url": "https://files.pythonhosted.org/packages/6d/4b/88657b53822d29a727a6b4e6051ced899715ddd80c8db0bd1c2951015485/cltoolbox-3.0.1.tar.gz",
"platform": null,
"description": ".. image:: https://github.com/timcera/cltoolbox/actions/workflows/python-package.yml/badge.svg\n :alt: Tests\n :target: https://github.com/timcera/cltoolbox/actions/workflows/python-package.yml\n :height: 20\n\n.. image:: https://img.shields.io/coveralls/github/timcera/cltoolbox\n :alt: Test Coverage\n :target: https://coveralls.io/r/timcera/cltoolbox?branch=master\n :height: 20\n\n.. image:: https://img.shields.io/pypi/v/cltoolbox.svg\n :alt: Latest release\n :target: https://pypi.python.org/pypi/cltoolbox/\n :height: 20\n\n.. image:: http://img.shields.io/pypi/l/cltoolbox.svg\n :alt: BSD-3 clause license\n :target: https://pypi.python.org/pypi/cltoolbox/\n :height: 20\n\n.. image:: http://img.shields.io/pypi/dd/cltoolbox.svg\n :alt: cltoolbox downloads\n :target: https://pypi.python.org/pypi/cltoolbox/\n :height: 20\n\n.. image:: https://img.shields.io/pypi/pyversions/cltoolbox\n :alt: PyPI - Python Version\n :target: https://pypi.org/project/cltoolbox/\n :height: 20\n\ncltoolbox: Easy Command Line Interfaces\n=======================================\ncltoolbox is a wrapper around ``argparse``, and allows you to write complete CLI\napplications in seconds using a simple decorator.\n\nSignificant portions of this code are based on `mando`. The primary\ndifferences between `mando` and `cltoolbox` are:\n\n * `cltoolbox` supports automatic detection of Sphinx, Google, and Numpy\n docstring formats by using the `docstring_parser` library\n * `cltoolbox` supports python 3.7+\n\nIf you need support of the `mando` formatted docstring or python 2 you have to\nuse `mando` instead of `cltoolbox`.\n\nInstallation\n------------\npip\n~~~\n.. code-block:: bash\n\n pip install cltoolbox\n\nconda\n~~~~~\n.. code-block:: bash\n\n conda install -c conda-forge cltoolbox\n\nThe problem\n-----------\nThe ``argparse`` module that comes with Python requires a programmer to\nduplicate information that Python can easily parse from the function signature\nand docstring. The ``cltoolbox`` does this for you by using decorators.\n\nQuickstart\n----------\n\n.. code-block:: python\n\n from cltoolbox import command, main\n\n\n @command\n def echo(text, capitalize=False):\n \"\"\"Echo the given text.\"\"\"\n if capitalize:\n text = text.upper()\n print(text)\n\n\n if __name__ == \"__main__\":\n main()\n\nGenerated help:\n\n.. code-block:: console\n\n $ python example.py -h\n usage: example.py [-h] {echo} ...\n\n positional arguments:\n {echo}\n echo Echo the given text.\n\n optional arguments:\n -h, --help show this help message and exit\n\n $ python example.py echo -h\n usage: example.py echo [-h] [--capitalize] text\n\n Echo the given text.\n\n positional arguments:\n text\n\n optional arguments:\n -h, --help show this help message and exit\n --capitalize\n\nActual usage:\n\n.. code-block:: console\n\n $ python example.py echo spam\n spam\n $ python example.py echo --capitalize spam\n SPAM\n\n\nA *real* example\n----------------\n\nSomething more complex and real-world-*ish*. The code:\n\n.. code-block:: python\n\n from cltoolbox import command, main\n\n\n @command\n def push(repository, all=False, dry_run=False, force=False, thin=False):\n \"\"\"Update remote refs along with associated objects.\n\n :param repository: Repository to push to.\n :param --all: Push all refs.\n :param -n, --dry-run: Dry run.\n :param -f, --force: Force updates.\n :param --thin: Use thin pack.\"\"\"\n\n print(\n \"Pushing to {0}. All: {1}, dry run: {2}, force: {3}, thin: {4}\".format(\n repository, all, dry_run, force, thin\n )\n )\n\n\n if __name__ == \"__main__\":\n main()\n\ncltoolbox understands Sphinx, Google, and Numpy dostrings, from which it can\ncreate short options and their help for you.\n\n.. code-block:: console\n\n $ python git.py push -h\n usage: git.py push [-h] [--all] [-n] [-f] [--thin] repository\n\n Update remote refs along with associated objects.\n\n positional arguments:\n repository Repository to push to.\n\n optional arguments:\n -h, --help show this help message and exit\n --all Push all refs.\n -n, --dry-run Dry run.\n -f, --force Force updates.\n --thin Use thin pack.\n\nLet's try it!\n\n.. code-block:: console\n\n $ python git.py push --all myrepo\n Pushing to myrepo. All: True, dry run: False, force: False, thin: False\n\n $ python git.py push --all -f myrepo\n Pushing to myrepo. All: True, dry run: False, force: True, thin: False\n\n $ python git.py push --all -fn myrepo\n Pushing to myrepo. All: True, dry run: True, force: True, thin: False\n\n $ python git.py push --thin -fn myrepo\n Pushing to myrepo. All: False, dry run: True, force: True, thin: True\n\n $ python git.py push --thin\n usage: git.py push [-h] [--all] [-n] [-f] [--thin] repository\n git.py push: error: too few arguments\n\nAmazed uh? Yes, cltoolbox got the short options and the help from the docstring!\nYou can put much more in the docstring, and if that isn't enough, there's an\n``@arg`` decorator to customize the arguments that get passed to argparse.\n\n\nType annotations\n----------------\n\ncltoolbox understands Python 3-style type annotations and will warn the user if the\narguments given to a command are of the wrong type.\n\n.. code-block:: python\n\n from cltoolbox import command, main\n\n\n @command\n def duplicate(string, times: int):\n \"\"\"Duplicate text.\n\n :param string: The text to duplicate.\n :param times: How many times to duplicate.\"\"\"\n\n print(string * times)\n\n\n if __name__ == \"__main__\":\n main()\n\n.. code-block:: console\n\n $ python3 test.py duplicate \"test \" 5\n test test test test test\n\n $ python3 test.py duplicate \"test \" foo\n usage: test.py duplicate [-h] string times\n test.py duplicate: error: argument times: invalid int value: 'foo'\n\n\nThe `cltoolbox` supports shell autocompletion via the\n``argcomplete`` package and supports custom format classes. For a complete\ndocumentation, visit https://timcera.bibucket.io/cltoolbox/.\n",
"bugtrack_url": null,
"license": "BSD-3-Clause and MIT",
"summary": "Python library for creating and manipulating CLIs",
"version": "3.0.1",
"project_urls": {
"bitbucket": "https://bitbucket.org/timcera/cltoolbox/src/main/",
"documentation": "https://timcera.bitbucket.io/cltoolbox/docs/index.html#cltoolbox-documentation",
"github": "https://github.com/timcera/cltoolbox"
},
"split_keywords": [
"python",
" cli",
" argparse",
" arguments",
" command line",
" keyword arguments",
" docstring"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c572612fc870f2ab4f1ad7bf7879d81089cd1f6a5ff0295ca007cf480e17dc29",
"md5": "9f5d9e959d120f14448c21b2a3832135",
"sha256": "3aeb5d75313ed5e09d2a63f660c75777fc20156ac7dbab32c04780f366cac069"
},
"downloads": -1,
"filename": "cltoolbox-3.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9f5d9e959d120f14448c21b2a3832135",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 23306,
"upload_time": "2024-03-31T18:15:09",
"upload_time_iso_8601": "2024-03-31T18:15:09.870366Z",
"url": "https://files.pythonhosted.org/packages/c5/72/612fc870f2ab4f1ad7bf7879d81089cd1f6a5ff0295ca007cf480e17dc29/cltoolbox-3.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6d4b88657b53822d29a727a6b4e6051ced899715ddd80c8db0bd1c2951015485",
"md5": "7f01dee521a944d58363179bd90b0255",
"sha256": "dc50e45b858b94302585c35ac6859c612a2ae82c479127dc62ec586626e70af5"
},
"downloads": -1,
"filename": "cltoolbox-3.0.1.tar.gz",
"has_sig": false,
"md5_digest": "7f01dee521a944d58363179bd90b0255",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 42117,
"upload_time": "2024-03-31T18:15:07",
"upload_time_iso_8601": "2024-03-31T18:15:07.036688Z",
"url": "https://files.pythonhosted.org/packages/6d/4b/88657b53822d29a727a6b4e6051ced899715ddd80c8db0bd1c2951015485/cltoolbox-3.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-31 18:15:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "timcera",
"github_project": "cltoolbox",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"landscape": true,
"lcname": "cltoolbox"
}
JSON
