The preparse project allows to preparse arguments before the main parsing. Its ability to deabbreviate options is especially useful for use with click.

The preparse project allows for preprocessing a list of arguments so that they can be parsed definitively in a later step. This way, the functionality of another parsing system can be modified. The project is especially adapted to work with the click project.

Here is the implementation of the expit project (Version 1.0.10) to illustrate how preparse can be used to modify click.

import math

import click
import preparse

__all__ = ["function", "main"]


def function(x: float) -> float:
    "The expit function."
    try:
        p = math.exp(-x)
    except OverflowError:
        p = float("+inf")
    return 1 / (1 + p)


@preparse.PreParser(posix=False).click()
@click.command(add_help_option=False)
@click.help_option("-h", "--help")
@click.version_option(None, "-V", "--version")
@click.argument("x", type=float)
def main(x: float) -> None:
    "Apply the expit function to x."
    click.echo(function(x))

The PreParser class

This class is the centerpiece of the preparse. Its behaviour follows the principles of getopt from C.

class preparse.PreParser(optdict: Any = None, prog: Any = None, abbr: Any = preparse.Abbr.COMPLETE, order: Any = preparse.Order.PERMUTE, warn: Callable = str)

Calling the class creates und returns a new instance.

abbr

This property determines the approach of the instance to abbreviations of long options.

click(parser: Any, cmd: Any = True, ctx: Any = True) -> preparse.Click

This method returns a decorator that infuses the current instance into parse_args.

copy() -> Self

This method returns a copy of the current instance.

optdict

This property holds a dictionary. Its keys are the options. Its values specify nargs.

order

This property decides how to order flags and positional arguments. Passing a value equal to "infer_given" to the property saves Order.POSIX to the property if bool(os.environ.get("POSIXLY_CORRECT")) and elsewise Order.GIVEN. Passing a value equal to "infer_permute" to the property saves Order.POSIX to the property if bool(os.environ.get("POSIXLY_CORRECT")) and elsewise Order.PERMUTE.

parse_args(args: Optional[Iterable] = None) -> List[str]

This method is at the core of the class. It returns a preparsed list of arguments. If None is passed as args then sys.argv[1:] is used. If the method is applied repeatedly to a list there will be no changes after the first run.

prog

This property represents the name of the program. If the value passed to the property is None then str(sys.argv[0]) is saved.

reflectClickCommand(cmd: click.Command) -> None

This method alters the current instance to reflect a click.Command object. Concretely the optdict property is changed.

reflectClickContext(ctx: click.Context) -> None

This method alters the current instance to reflect a click.Context object. Concretely the prog property is changed.

todict() -> dict

This method a dict representing the current instance.

warn

This property holds a function that is called whenever parse_args encounters a warning. The warning is given as the only positional arguments. No keyword arguments are given. Its return value is discarded. Therefore, str is used to discard the warnings.

The Click class

This dataclass provides decorators for embedding a PreParser object.

class preparse.Click(parser: Any, cmd: Any = True, ctx: Any = True)

Calling the class creates und returns a new instance.

__call__(target: Any) -> Any

This magic method implements self(target). It works as a decorator that embeds its parser into a given target from the library click.

cmd

This property determines if the reflectClickCommand method of parser is to be called.

ctx

This property determines if the reflectClickContext method of parser is to be called.

parser

This property holds the parser to be embedded.

The Enums

These classes are subclasses of enum.IntEnum. Any value different from 0 (meaning no) and 1 (meaning yes) is interpreted as 2 (meaning intermediate).

class preparse.Abbr

Name	Value	Explanation
REJECT	0	The parser rejects abbreviations and interprets them as unknown options instead.
KEEP	1	The parser keeps abbreviations as abbreviations.
COMPLETE	2	The parser replaces abbreviations with the full options.

class preparse.Order

Name	Value	Explanation
GIVEN	0	The parser does not seperate flags from positional arguments.
POSIX	1	The parser assumes the posix standard.
PERMUTE	2	The parser corrects to posix standard.

class preparse.Nargs

Name	Value	Explanation
NO_ARGUMENT	0	The option does not take an argument.
REQUIRED_ARGUMENT	1	The option requires an argument.
OPTIONAL_ARGUMENT	2	The option may take an argument.

The Warnings

These classes are subclasses of Warning that are specifically designed to communicate issues with parsing.

class preparse.PreparseWarning

This abstract base class is the base for all other warning types.

class preparse.PreparseAmbiguousOptionWarning(prog: Any, option: Any, possibilities: Any)

This class warns about ambiguous options.

class preparse.PreparseInvalidOptionWarning(prog: Any, option: Any)

This class warns about invalid options.

class preparse.PreparseRequiredArgumentWarning(prog: Any, option: Any)

This class warns about missing required arguments.

class preparse.PreparseUnallowedArgumentWarning(prog: Any, option: Any)

This class warns about unallowed arguments.

class preparse.PreparseUnrecognizedOptionWarning(prog: Any, option: Any)

This class warns about unrecognized options.