clizy 0.0.2

Quickstart

Such normal Python function with sphinx docstring:

# ls.py
import clizy

def ls(filename, long: bool, all: bool, human_readable: bool, limit: int=None):
    """
    Fake command for listing.

    :param filename: filename, what else did you expect?
    :param long: long listing or something
    :param all: all, like including hidden files dude
    :param human_readable: show human readable stats
    :param limit: limit the number of files printed
    """
    print(locals())

if __name__ == '__main__':
    clizy.run(ls)

Creates a command line interface. When you call the script with --help, you can see what was generated:

$ python ls.py --help
usage: ls [-h] [-l] [-a] [-H] [-L LIMIT] filename

Fake command for listing.

positional arguments:
  filename              filename, what else did you expect?

optional arguments:
  -h, --help            show this help message and exit
  -l, --long            long listing or something
  -a, --all             all, like including hidden files dude
  -H, --human-readable  show human readable stats
  -L LIMIT, --limit LIMIT
                        limit the number of files printed

Why

Why to use clizy over argparse, docopt and Click?

argparse is quite verbose and magical, its gentle introduction is literally 14 pages long.

docopt introduced its own, very strict, documentation language which you have to learn first.

Click makes developers use decorators even for information available in the function itself (variable names, type hints, default values).

Clizy simplifies command line interface creation by using things we all use and know - type hints, arguments names, default values and docstrings.

Rules

The rules for function arguments are simple and sane enough:

• names are chosen automatically based on names.

• No default value, no type hint - positional argument str.

• No default value, type hint List[?] - positional arguments with one or more values.

• Default value, no type hint - optional argument, type str.

• Default value, type hint bool - optional argument without any value. If present on the command line. function receives True, if not function receives False.

• Type hint int, float or str - value is expected to have used type.

Limitations

Simplification comes at cost of flexibility, you should consider if these limitations when choosing this library:

• select a letter for short options is not possible, it’s chosen automatically

• global options are not supported for multiple functions

  • they have to be always explicit for each function

• optional arguments cannot be required

  • actually both required and optional does not make sense in the first place

• types are limited to primitives

• there is no support for a choice

  • you can still do if value not in ['A', 'B']: raise ValueError

• there is no support for a user input

  • you can still use input for normal input and getpass.getpass for passwords

• mutually exclusive options are not supported

  • you can still use if value1 and value2: raise ValueError