1. Andy Mikhailenko
  2. argh


argh / README

Agrh, argparse!

Did you ever say "argh" trying to remember the details of optparse or argparse
API? If yes, this package may be useful for you. It provides a very simple
wrapper for argparse with support for hierarchical commands that can be bound
to modules or classes. Argparse can do it; argh makes it easy.

In a nutshell

Here's a list of features that `argh` adds to `argparse`:

* mark a function as a CLI command and specify its arguments before the parser
  is instantiated;
* nested commands made easy: no messing with subparsers (though they are of
  course used under the hood);
* infer agrument type from the default value;
* infer command name from function name;
* add an alias root command ``help`` for the ``--help`` argument;
* enable passing unwrapped arguments to certain functions instead of a
  `argparse.Namespace` object.

`Argh` is fully compatible with `argparse`. You can mix `argh`-agnostic and
`argh`-aware code. Just keep in mind that `argh.dispatch` does some extra
work that a custom dispatcher may not do.


    $  pip install argh


A very simple application with one command::

    from argh import *

    def main(args):
        return 'Hello ' + args.name

An application with multiple commands::

    def echo(text='hello'):
        print text

    def another_echo(text='hi there'):
        print text

    parser = ArghParser()
    parser.add_commands([echo, another_echo])

    if __name__ == '__main__':

The powerful API of `argparse` is also available::

    @arg('text', default='hello world', nargs='+', help='The message')
    def echo(args):
        print args.text

The approaches can be safely combined.


`Argh` runs on Python 2.x (since 2.6, incl. PyPy) and 3.x. See documentation.


See the `complete documentation`_ for details. If it's not complete enough,
feel free to ask your questions or submit bugs.

.. _complete documentation: http://packages.python.org/argh


Originally written by Andrey Mikhaylenko in 2010.

See file `AUTHORS` for a complete authors list of this application.

Please feel free to submit patches, report bugs or request features:


Here's the discussion group:


Real-life usage

Among applications that use `argh` are Tool_, OrgTool_, Watchdog_, Poni_, Pyg_,
Barman_ and more. Well, there's probably no need to keep a complete
and up-to-date list.
Still, please let me know anyway if you use `argh` in your project.
I'll be glad to know. :-)

.. _Tool: http://pypi.python.org/pypi/tool
.. _OrgTool: http://pypi.python.org/pypi/orgtool
.. _Watchdog: https://github.com/gorakhargosh/watchdog/
.. _Poni: https://github.com/melor/poni/commit/14e8ccbb50e9e17b95a2f2a0d2cd0af5d90ca22b
.. _Pyg: https://github.com/rubik/pyg/commit/a201de1d70536e7e4637a6079f03174b7b493ffa
.. _Barman: http://pgbarman.org


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
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/>.