argh


Nameargh JSON
Version 0.31.3 PyPI version JSON
download
home_pageNone
SummaryPlain Python functions as CLI commands without boilerplate
upload_time2024-07-13 17:54:59
maintainerNone
docs_urlhttps://pythonhosted.org/argh/
authorNone
requires_python>=3.8
licenseNone
keywords cli command line argparse optparse argument option
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            Argh: The Effortless CLI
========================

.. image:: https://github.com/neithere/argh/actions/workflows/lint-and-test.yml/badge.svg
    :target: https://github.com/neithere/argh/actions/workflows/lint-and-test.yml

.. image:: https://img.shields.io/pypi/format/argh.svg
    :target: https://pypi.python.org/pypi/argh

.. image:: https://img.shields.io/pypi/status/argh.svg
    :target: https://pypi.python.org/pypi/argh

.. image:: https://img.shields.io/pypi/v/argh.svg
    :target: https://pypi.python.org/pypi/argh

.. image:: https://img.shields.io/pypi/pyversions/argh.svg
    :target: https://pypi.python.org/pypi/argh

.. image:: https://img.shields.io/pypi/dd/argh.svg
    :target: https://pypi.python.org/pypi/argh

.. image:: https://readthedocs.org/projects/argh/badge/?version=stable
    :target: http://argh.readthedocs.org/en/stable/

.. image:: https://readthedocs.org/projects/argh/badge/?version=latest
    :target: http://argh.readthedocs.org/en/latest/

**The power of Argparse with plain Python functions!**

Building a command-line interface?  Found yourself uttering "argh!" while
struggling with the API of `argparse`?  Don't like the complexity but need
the power?

`Argh` builds on the power of `argparse` (which comes with Python) and makes it
really easy to use.  It eliminates the complex API and lets you "dispatch"
ordinary Python functions as CLI commands.

Installation
------------

::

    $ pip install argh

Example
-------

.. code-block:: python

    import argh

    def verify_paths(paths: list[str], *, verbose: bool = False):
        """
        Verify that all given paths exist.
        """
        for path in paths:
            if verbose:
                print(f"Checking {path}...")
            assert os.path.exists(path)

    argh.dispatch_command(verify_paths)

Now you can run the script like this:

.. code-block:: bash

    $ python app.py foo.txt bar/quux.txt

    $ python app.py foo.txt bar/quux.txt --verbose
    Checking foo.txt...
    Checking bar/quux.txt...

    $ python app.py -h
    usage: app.py [-h] [-v] [paths ...]

    Verify that all given paths exist.

    positional arguments:
      paths          -

    options:
      -h, --help     show this help message and exit
      -v, --verbose  False

Please check the documentation for examples of multiple commands, modularity,
help generation, advanced type annotations inspection, decorators and more:

* `Quick Start <https://argh.readthedocs.io/en/latest/quickstart.html>`_
* `Tutorial <https://argh.readthedocs.io/en/latest/tutorial.html>`_

Why Argh?
---------

`Argh`-powered applications are *simple* but *flexible*:

:Pythonic, KISS:
    Commands are plain Python functions.  Almost no CLI-specific API to learn.

:Reusable:
    Endpoint functions can be used directly outside of CLI context.

:Static typing friendly:
    100% of the code including endpoint functions can be type-checked.
    Argh is driven primarily by type annotations.

:DRY:
    Don't Repeat Yourself.  The amount of boilerplate code is minimal.
    Among other things, `Argh` will:

    * infer command name from function name;
    * infer arguments from function signature;
    * infer argument types, actions and much more from annotations.

:Modular:
    Declaration of commands can be decoupled from assembling and dispatching.

:Layered:
    The complexity of code raises with requirements.

:Transparent:
    You can directly access `argparse.ArgumentParser` if needed.

:Subcommands:
    Easily nested commands.  Argh isolates the complexity of subparsers.

:NIH free:
    `Argh` supports *completion*, *progress bars* and everything else by being
    friendly to excellent 3rd-party libraries.  No need to reinvent the wheel.

:Compact:
    No dependencies apart from Python's standard library.

Links
-----

See also the `project page on GitHub`_, `documentation`_ and `PyPI page`_.

.. _project page on GitHub: http://github.com/neithere/argh/
.. _documentation: http://argh.readthedocs.org
.. _PyPI page: http://pypi.python.org/pypi/argh

Author
------

Developed by Andrey Mikhaylenko since 2010.

See `contributors <https://argh.readthedocs.io/en/latest/contributors.html>`_
for a list of contributors to this library.

Contribute
----------

The fastest way to improve this project is to submit tested and documented
patches or detailed bug reports.

Donate
------

You can `donate via Liberapay`_.  This may speed up development or simply
make the original author happy :)

.. _donate via Liberapay: https://liberapay.com/neithere/donate

Licensing
---------

Argh is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published
by the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

Argh is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with Argh.  If not, see <http://gnu.org/licenses/>.


            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "argh",
    "maintainer": null,
    "docs_url": "https://pythonhosted.org/argh/",
    "requires_python": ">=3.8",
    "maintainer_email": "Andy Mikhaylenko <neithere@gmail.com>",
    "keywords": "cli, command line, argparse, optparse, argument, option",
    "author": null,
    "author_email": "Andy Mikhaylenko <neithere@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/4f/34/bc0b3577a818b4b70c6e318d23fe3c81fc3bb25f978ca8a3965cd8ee3af9/argh-0.31.3.tar.gz",
    "platform": null,
    "description": "Argh: The Effortless CLI\n========================\n\n.. image:: https://github.com/neithere/argh/actions/workflows/lint-and-test.yml/badge.svg\n    :target: https://github.com/neithere/argh/actions/workflows/lint-and-test.yml\n\n.. image:: https://img.shields.io/pypi/format/argh.svg\n    :target: https://pypi.python.org/pypi/argh\n\n.. image:: https://img.shields.io/pypi/status/argh.svg\n    :target: https://pypi.python.org/pypi/argh\n\n.. image:: https://img.shields.io/pypi/v/argh.svg\n    :target: https://pypi.python.org/pypi/argh\n\n.. image:: https://img.shields.io/pypi/pyversions/argh.svg\n    :target: https://pypi.python.org/pypi/argh\n\n.. image:: https://img.shields.io/pypi/dd/argh.svg\n    :target: https://pypi.python.org/pypi/argh\n\n.. image:: https://readthedocs.org/projects/argh/badge/?version=stable\n    :target: http://argh.readthedocs.org/en/stable/\n\n.. image:: https://readthedocs.org/projects/argh/badge/?version=latest\n    :target: http://argh.readthedocs.org/en/latest/\n\n**The power of Argparse with plain Python functions!**\n\nBuilding a command-line interface?  Found yourself uttering \"argh!\" while\nstruggling with the API of `argparse`?  Don't like the complexity but need\nthe power?\n\n`Argh` builds on the power of `argparse` (which comes with Python) and makes it\nreally easy to use.  It eliminates the complex API and lets you \"dispatch\"\nordinary Python functions as CLI commands.\n\nInstallation\n------------\n\n::\n\n    $ pip install argh\n\nExample\n-------\n\n.. code-block:: python\n\n    import argh\n\n    def verify_paths(paths: list[str], *, verbose: bool = False):\n        \"\"\"\n        Verify that all given paths exist.\n        \"\"\"\n        for path in paths:\n            if verbose:\n                print(f\"Checking {path}...\")\n            assert os.path.exists(path)\n\n    argh.dispatch_command(verify_paths)\n\nNow you can run the script like this:\n\n.. code-block:: bash\n\n    $ python app.py foo.txt bar/quux.txt\n\n    $ python app.py foo.txt bar/quux.txt --verbose\n    Checking foo.txt...\n    Checking bar/quux.txt...\n\n    $ python app.py -h\n    usage: app.py [-h] [-v] [paths ...]\n\n    Verify that all given paths exist.\n\n    positional arguments:\n      paths          -\n\n    options:\n      -h, --help     show this help message and exit\n      -v, --verbose  False\n\nPlease check the documentation for examples of multiple commands, modularity,\nhelp generation, advanced type annotations inspection, decorators and more:\n\n* `Quick Start <https://argh.readthedocs.io/en/latest/quickstart.html>`_\n* `Tutorial <https://argh.readthedocs.io/en/latest/tutorial.html>`_\n\nWhy Argh?\n---------\n\n`Argh`-powered applications are *simple* but *flexible*:\n\n:Pythonic, KISS:\n    Commands are plain Python functions.  Almost no CLI-specific API to learn.\n\n:Reusable:\n    Endpoint functions can be used directly outside of CLI context.\n\n:Static typing friendly:\n    100% of the code including endpoint functions can be type-checked.\n    Argh is driven primarily by type annotations.\n\n:DRY:\n    Don't Repeat Yourself.  The amount of boilerplate code is minimal.\n    Among other things, `Argh` will:\n\n    * infer command name from function name;\n    * infer arguments from function signature;\n    * infer argument types, actions and much more from annotations.\n\n:Modular:\n    Declaration of commands can be decoupled from assembling and dispatching.\n\n:Layered:\n    The complexity of code raises with requirements.\n\n:Transparent:\n    You can directly access `argparse.ArgumentParser` if needed.\n\n:Subcommands:\n    Easily nested commands.  Argh isolates the complexity of subparsers.\n\n:NIH free:\n    `Argh` supports *completion*, *progress bars* and everything else by being\n    friendly to excellent 3rd-party libraries.  No need to reinvent the wheel.\n\n:Compact:\n    No dependencies apart from Python's standard library.\n\nLinks\n-----\n\nSee also the `project page on GitHub`_, `documentation`_ and `PyPI page`_.\n\n.. _project page on GitHub: http://github.com/neithere/argh/\n.. _documentation: http://argh.readthedocs.org\n.. _PyPI page: http://pypi.python.org/pypi/argh\n\nAuthor\n------\n\nDeveloped by Andrey Mikhaylenko since 2010.\n\nSee `contributors <https://argh.readthedocs.io/en/latest/contributors.html>`_\nfor a list of contributors to this library.\n\nContribute\n----------\n\nThe fastest way to improve this project is to submit tested and documented\npatches or detailed bug reports.\n\nDonate\n------\n\nYou can `donate via Liberapay`_.  This may speed up development or simply\nmake the original author happy :)\n\n.. _donate via Liberapay: https://liberapay.com/neithere/donate\n\nLicensing\n---------\n\nArgh is free software: you can redistribute it and/or modify\nit under the terms of the GNU Lesser General Public License as published\nby the Free Software Foundation, either version 3 of the License, or\n(at your option) any later version.\n\nArgh is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU Lesser General Public License for more details.\n\nYou should have received a copy of the GNU Lesser General Public License\nalong with Argh.  If not, see <http://gnu.org/licenses/>.\n\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "Plain Python functions as CLI commands without boilerplate",
    "version": "0.31.3",
    "project_urls": {
        "Discussions": "https://github.com/neithere/argh/discussions",
        "Documentation": "https://argh.readthedocs.io/en/latest",
        "Homepage": "https://github.com/neithere/argh",
        "Issue Tracker": "https://github.com/neithere/argh/issues",
        "Releases": "https://github.com/neithere/argh/releases"
    },
    "split_keywords": [
        "cli",
        " command line",
        " argparse",
        " optparse",
        " argument",
        " option"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "d252fcd83710b6f8786df80e5d335882d1b24d1f610f397703e94a6ffb0d6f66",
                "md5": "d34a4a7cdafa488a5c99baf754fe574d",
                "sha256": "2edac856ff50126f6e47d884751328c9f466bacbbb6cbfdac322053d94705494"
            },
            "downloads": -1,
            "filename": "argh-0.31.3-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "d34a4a7cdafa488a5c99baf754fe574d",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 44844,
            "upload_time": "2024-07-13T17:54:57",
            "upload_time_iso_8601": "2024-07-13T17:54:57.706215Z",
            "url": "https://files.pythonhosted.org/packages/d2/52/fcd83710b6f8786df80e5d335882d1b24d1f610f397703e94a6ffb0d6f66/argh-0.31.3-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "4f34bc0b3577a818b4b70c6e318d23fe3c81fc3bb25f978ca8a3965cd8ee3af9",
                "md5": "b3526d2a5126defffdb8075e1c34f0c8",
                "sha256": "f30023d8be14ca5ee6b1b3eeab829151d7bbda464ae07dc4dd5347919c5892f9"
            },
            "downloads": -1,
            "filename": "argh-0.31.3.tar.gz",
            "has_sig": false,
            "md5_digest": "b3526d2a5126defffdb8075e1c34f0c8",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 57570,
            "upload_time": "2024-07-13T17:54:59",
            "upload_time_iso_8601": "2024-07-13T17:54:59.729095Z",
            "url": "https://files.pythonhosted.org/packages/4f/34/bc0b3577a818b4b70c6e318d23fe3c81fc3bb25f978ca8a3965cd8ee3af9/argh-0.31.3.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-07-13 17:54:59",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "neithere",
    "github_project": "argh",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "tox": true,
    "lcname": "argh"
}
        
Elapsed time: 0.33931s