Skip to content

Overview

A wrapper around argparser to help build CLIs from functions. Uses type-hints extensively 🐍.

PyPi Version Python Version PyPI License

Setup

⚙️ Installation

Install it directly into an activated virtual environment:

1
$ pip install arger

or add it to your Poetry project:

1
$ poetry add arger

📚 Usage

  • create a python file called test.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
from arger import Arger


def main(param1: int, param2: str, kw1=None, kw2=False):
    """Example function with types documented in the docstring.
    :param param1: The first parameter.
    :param param2: The second parameter.
    :param kw1: this is optional parameter.
    :param kw2: this is boolean. setting flag sets True.
    """
    print(locals())


arger = Arger(
    main,
    prog="pytest",  # for testing purpose. otherwise not required
)

if __name__ == "__main__":
    arger.run()

  • Here Arger is just a subclass of ArgumentParser. It will not conceal you from using other argparse libraries.

  • run this normally with

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
$ python test.py -h
usage: pytest [-h] [-k KW1] [-w] param1 param2

Example function with types documented in the docstring.

positional arguments:
  param1             The first parameter.
  param2             The second parameter.

optional arguments:
  -h, --help         show this help message and exit
  -k KW1, --kw1 KW1  this is optional parameter. (default: None)
  -w, --kw2          this is boolean. setting flag sets True. (default: False)

1
2
$ python test.py 100 param2
{'param1': 100, 'param2': 'param2', 'kw1': None, 'kw2': False}
  • Checkout examples folder and documentation to see more of arger in action. It supports any level of sub-commands.

Features

  • Uses docstring to parse help comment for arguments. Supports
  • Flags will be generated from parameter-name.
  • e.g. def main(param: ...) -> -p, --param
  • If needed you could declare it inside docstring like :param arg1: -a --arg this is the document.
  • one can use Argument class to pass any values to the parser.add_argument function

  • The decorated functions can be composed to form nested sub-commands of any level.

  • Most of the Standard types supported. Please see examples for more supported types with examples.

NOTE - *args supported but no **kwargs support yet. - all optional arguments that start with underscore is not passed to Parser. They are considered private to the function implementation. Some parameter names with special meaning - _namespace_ -> to get the output from the ArgumentParser.parse_args() - _arger_ -> to get the parser instance

Argparser enhancements

  • web-ui : https://github.com/nirizr/argparseweb
  • extra actions : https://github.com/kadimisetty/action-hero
  • automatic shell completions using argcomplete