dryparse.objects

Object model of a command line program.

Option

class Option(short: str = '', long: str = '', argname: ~typing.Optional[str] = None, default=None, argtype: type = <class 'bool'>, desc: ~typing.Optional[str] = None)
Parameters

  • short (str) – Regex pattern that the short version of this option should match against. Usually this is a hyphen followed by a single letter (e.g. -s).

  • long (str) – Regex pattern that the long version of this option should match against. Usually this is two hyphens followed by multiple letters. (e.g. --long)

Attributes

help: OptionHelp

Customizable help object.

build(option: Optional[str] = None)

Each time this option is specified on the command line, this method is called. The positional arguments in the function signature determine what formats are acceptable for the option.

The build function can be assigned by option.build =.

Parameters

option – The exact way the option was specified. This is useful when the option text is specified as a regex, or when you want to know if the option was specified using its short or long format.

Examples

Assume that the long version of the option is --option.

  1. If the signature is build(self, **kwargs), the option is a bool option and can be specified as --option.

  2. If the signature is build(self, arg, **kwargs), the option can be specified as --option ARG

Command

class Command(name, regex=None, desc: Optional[str] = None)

A CLI command.

You can assign arbitrary attributes dynamically. Only attributes of types Option, Command, Group and others from dryparse.objects have special meaning to the parser.

Examples

>>> docker = Command("docker")
>>> docker.context = Option("-c", "--context")
>>> docker.run = Command("run", desc="Run a command in a new container")
__call__(*args, help=None, **kwargs)

Execute the command. Unless overridden, this will process special options like help, and handle subcommands.

RootCommand

class RootCommand(name, regex=None, desc='', version='0.0.0')

Command that corresponds to the program itself.

Parameters

version (str) – Version of the program that is printed when the --version option is given.

Group

class Group(name: str)

A group of commands or options.

Arguments

class Arguments(*pattern: Union[type, Tuple[type, Union[int, ellipsis, range]]])

Specification for positional arguments of a command.

Positional arguments are specified on the command line as regular strings, but usually we want to restrict the number of allowed arguments, their data types, add custom validation, etc. An instance of Arguments holds a pattern of acceptable argument types. The arguments are converted (and effectively validated) using convert().

Attributes

pattern

Determines the number of arguments and their types. Each item of this list represents an argument or multiple arguments of a given type. The order of arguments is important.

There are two acceptable formats for each entry:

  • type: Accepts a single argument of the given type.

  • (type, number): Accepts number arguments of type type.

Note that number can be an int, ... (ellipsis) or range. An int specifies a fixed number of required arguments. Ellipsis is a special value meaning zero or more arguments. A range specifies a range of acceptable argument numbers.

values

The list of argument values held by this instance. This attribute is assigned when you call assign(), and will be None until then.

Notes

  • (type, ...)- and (type, range)- style patterns cannot be followed by further patterns. Instead, you should implement a custom converter function.

  • For boolean types, you might want to use Bool instead of bool, because of potentially undesired behaviors like bool("false") == True, etc.

Examples

Here’s an exhaustive list of example use cases:

>>> # Single argument of type int
>>> Arguments(int)
>>> # Two arguments of type bool
>>> Arguments((bool, 2))
>>> # Single int and two bools
>>> Arguments(int, (bool, 2))
>>> # Zero or more strings
>>> Arguments((str, ...))
>>> # Same as the above
>>> Arguments()
>>> # One or more strings
>>> Arguments(str, (str, ...))
>>> # Between 2 and 4 strings
>>> Arguments((str, range(2, 4)))
>>> # One int and zero or more strings
>>> Arguments(int, (str, ...))
>>> # ERROR: there can be no patterns after a (type, ...)-style pattern
>>> Arguments(int, (int, ...), str)
>>> # ERROR: there can be no patterns after a (type, range)-style pattern
>>> Arguments(int, (int, range(1, 2)), str)
convert(args: Sequence[str], allow_extra_args=False) → Union[List[Any], Any]

Convert (and consequently validate) a list of args that were specified on the command line to a list of arguments conforming to pattern.

If the conversion of any of the arguments throws an exception, the conversion (and validation) will fail. (TODO exception)

If the pattern only expects one argument, then the single parsed argument will be returned, instead of a list with one element.

Parameters

  • args – Arguments to convert.

  • allow_extra_args – Do not raise an exception if there are more args than can fit into self.pattern.

assign(args: List[str], allow_extra_args=False)

Assign a set of arguments specified on the command line to be held by this instance.

The arguments are converted and validated using convert() in order to conform to pattern.

Parameters

allow_extra_args – See convert().

Returns

List of the converted arguments.

Advanced

Meta

class Meta(*args, **kwargs)

Meta wrapper for Command that can be used to access special attributes of Command.

Notes

  • Do not modify the options, command, subcommands and argument_aliases attributes.

call(*args, **kwargs)

Callback function for when this command is invoked.

You can freely assign this method on an instance of Meta. Just keep in mind that the signature must support all arguments and options that can be passed to it after the command is parsed. The function can but need not have a self argument; but if it does, it must be the first. This argument can be used to access the associated ResolvedCommand object.

set_callback(func: Callable[[Command], Any])

Set the callback function to be called when this command is invoked.

When the command is parsed, the callback will be called with all the CLI arguments passed as arguments to the callback.

ResolvedCommand

class ResolvedCommand(command: Command, deepcopy=True)

Wrapper around Command that provides access to option values and argument values as if they were regular attributes.

Examples

>>> # Initialize a simple command with an option
>>> cmd = Command("test")
>>> cmd.option = Option("--option", default="DEFAULT")
>>> # Convert Command into a ResolvedCommand
>>> parsed_cmd = ResolvedCommand(cmd)
>>> print(parsed_cmd.option)
DEFAULT
>>> # Assignment works like with a regular command
>>> parsed_cmd.option = "NON_DEFAULT"
>>> print(parsed_cmd)
NON_DEFAULT