Skip to main content

Command-line interface creation for lazy people using type hints.

Project description

Command-line interface creation for lazy people using type hints.


Such normal Python function with sphinx docstring:

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

if __name__ == '__main__':

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

$ python --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 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.


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.


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

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution (9.8 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page