ArgParseDecorator 1.0.0

A tool to easily build command line interpreters

About

argparseDecorator is a tool to ease working with the argparse library to build custom command line interpreters.

Instead of setting up the ArgumentParser object by hand and then adding subcommands and all the required arguments the argparseDecorator supplies a custom decorator to mark any function as a command and to generate the ArgumentParser from the function signature.

With this it is quite easy to make command line interfaces like, for example, a shell like cli:

from argparseDecorator import *

cli = ArgParseDecorator()


@cli.command
def ls(arg1, arg2, arg3)
    ...


@cli.command
def mv(...)
    ...


@cli.command
def cp(...)


...

cmdline = input()
cli.execute(cmdline)

The ArgParseDecorator uses both the signature of the decorated function and its docstring to infer information, metadata and description of the function arguments and passes them to the underlying ArgumentParser.

Here is an example for using ArgParseDecorator to create a hypothetical 'ls' command:

from __future__ import annotations  # required for Python 3.7 - 3.9. Not required for Python 3.10+
from argparsedecorator import *  # import the ArgParseDecorator API

cli = ArgParseDecorator()


@cli.command
def ls(
        files: ZeroOrMore[str],
        a: Flag = False,  # create '-a' flag that is 'False' if '-a' is not in the command line.
        ignore: Option | Exactly1[str] = "",  # create optional '--ignore PATTERN' argument
        columns: Option | int | Choices[Literal["range(1,5)"]] = 1,  # valid input for '--columns' is 1 to 4
        sort: Option | Choices[Literal["fwd", "rev"]] = "fwd",  # '--sort {fwd,rev}' with default 'fwd'
):
    """
    List information about files (the current directory by default).
    :param files: List of files, may be empty.

    :param a: do not ignore entries strating with '.'
    :alias a: --all

    :param ignore: do not list entries matching PATTERN
    :metavar ignore: PATTERN

    :param columns: number of output columns, must be between 1 and 4. Default is 1
    :alias columns: -c

    :param sort: alphabetic direction of output, either 'fwd' (default) or 'rev'
    :alias sort: -s
    """
    # for demonstration just return all input back to the caller, i.e. parser.execute(...)
    return {"files": files, "a": a, "ignore": ignore, "columns": columns, "sort": sort}

This example shows how annotations are used to add some metadata to the arguments which will be used by the argparse library to interpret the command line input. Take a look at the documentation to learn more about the supported annotations.

Now a command line can be parsed and executed like this:

   result = cli.execute("ls -a -c 2 --sort rev --ignore *.log")

ArgParseDecorator uses the docstring of the decorated function to get a help string for the command, and it also parses Sphinx style directives to provide help strings for arguments as well as additional metadata that can not be written as annotations.

The information provided by the docstring is used by the built-in help command:

 parser.execute("help ls")

usage:  ls [-a] [--ignore PATTERN] [--columns {1,2,3,4}] [--sort {fwd,rev}] [files ...]

List information about files (the current directory by default).

positional arguments:
  files                 List of files, may be empty.

options:
  -a, --all             do not ignore entries strating with '.'
  --ignore PATTERN      do not list entries matching PATTERN
  --columns {1,2,3,4}, -c {1,2,3,4}
                        number of output columns, must be between 1 and 4
  --sort {fwd,rev}, -s {fwd,rev}
                        alphabetic direction of output, either 'fwd' (default) or 'rev'

Requirements

• Works best with Python 3.10 or higher

  • the new type unions with '|' make the annotations much more readable

• Works with Python 3.7+

  • some features require the use of 'from __future__ import annotations'

• No other dependencies

Installation

{TODO} If the requirements are met, then a simple

 $ pip import argparseDecorator

will install the argParseDecorator module.

Documentation

Comprehensive documentation is available at https://argparseDecorator.readthedocs.io/.

Version

1.0 first release