clargs 0.5.2

Easily generate commandline apps from your functions, based on type hints

Clargs

The goal of the clargs package is to create commandline interfaces from function signatures.

• Hit the ground running: With a single line, an existing function is turned into a command line program
• Extensible: It is flexible enough to do everything that argparse does, and keeps you in control
• No magic: All the extension does is call commands in argparse; you can log and see these commands
• Safe: The built-in python argparse module does all the work, so safety guarantees from that module apply
• Typing: Parameter types are set as PEP 484 type hints (e.g. def foo(bar: int))
• Standard: By using argparse, you get standard behaviour such as long/short parameters, combine flags, help function
• Don't repeat yourself: Every parameter is defined (changed, added, removed) in one spot and only one spot, the function definition
• Rich parameter types: Support for str, int, float, bool, pathlib.Path and typing.Literal (multiple-choice values)
• Richer parameter types: In addition, lists of these parameters are allowed, default values, boolean-flags (--foo/--no-foo), counts
• Simple: Pure python, no dependencies
• Documentation: Function's docstring creates --help documentation. Support for Sphynx, GoogleDoc, NumpyDoc, EpyText

Example

Check out the list of examples to see the package in action

A quick example (just to get you excited):

import clargs


def count(
    singular: str,
    plural: str,
    maxitems: int = 10,
    *,
    shout: bool = False,
):
    """
    Counts from 1 to given number (default = 10)

    This text should not appear

    @param singular: The singular form of the thing to count
    @param plural: The plural form of the thing to count
    @param maxitems: The number to count to
    @param shout: If True, will convert all expressions to capitals
    """
    for i in range(maxitems):
        text = f"{i + 1} {singular if i == 0 else plural}"
        if shout:
            text = text.upper()
        print(text)


if __name__ == "__main__":
    clargs.create_parser_and_run(count)

> python main.py --help
usage: main.py [-h] [--shout [SHOUT]] singular plural [maxitems]

Counts from 1 to given number (default = 10)

positional arguments:
  singular              The singular form of the thing to count
  plural                The plural form of the thing to count
  maxitems              The number to count to

options:
  -h, --help            show this help message and exit
  --shout [SHOUT], -s [SHOUT]
                        If True, will convert all expressions to capitals> python main.py bottle bottles
1 bottle
2 bottles
3 bottles
4 bottles
5 bottles
6 bottles
7 bottles
8 bottles
9 bottles
10 bottles
> python main.py bottle bottles 5 --shout=yes
1 BOTTLE
2 BOTTLES
3 BOTTLES
4 BOTTLES
5 BOTTLES

Supported types

The type of the parameter (given through a type-hint) determines what the input is parsed at. If no type-hint is given, str is assumed.

str, int, float, pathlib.Path

These types just call the constructor on the string (e.g. python main.py --input-file /tmp/myfile.txt --repeat 5 will assign pathlib.Path("/tmp/myfile.txt") to input_file and int("5") to repeat (assuming a function signature like: def run(*, input_file: pathlib.Path, repeat: int)).

bool

Booleans need some special work internally (since bool("False") == True). Any parameter of type bool will accept Yes, No, True and False (case-insensitive) as values. Booleans can also be made Flags, see below under "Extra Types".

typing.Literal["foo", "bar", "baz"]

Using typing.Literal parameters can be made that can only have certain values. The type of the parameters can be any of the types above

list[X] or typing.Sequence[X]

Lists of items is supported (for all pf the above types). For instance a signature of def sum(*, terms: typing.List[float]) -> float means you can use python sum.py --terms 1.2 4 -5

typing.Optional[X] and None | X

typing.Optional or a union with None is ignored, so this won't affect the command line signature.

Extra Types

In addition to normal types, the clargs package defines some special types.

clargs.Flag

Is an alias for bool (should be recognised by static type-checkers). Creates --foo/--no-foo parameter pair to control booleans

clargs.Count

Is an alias for int (should be recognised by static type-checkers). Counts how often a parameter is present (mostly used in --verbose --verbose --verbose parameters)

Custom Type

I hope to add types quickly in future versions.

In the meantime, any type not listed here will also work as long as an explicit conversion function is defined.

Subparsers

Using subparsers it's possible to add multiple functions to your cli. See an example here

Compare to other solutions

clargs is far from the first solutions. Before development I looked at some of the alternatives out there, and found them

• clize is an amazing product, however it's just getting started with PEP 484 typing support (and made some decisions in the past to use the type hints for other things, which feel limits flexibility now).
• [TODO]