args

class runcommands.args.bool_or[source]

Used to indicate that an arg can be a flag or an option.

Use like this:

@command
def local(config, cmd, hide: {'type': bool_or(str)} = False):
    "Run the specified command, possibly hiding its output."

Allows for this:

run local --hide all     # Hide everything
run local --hide         # Hide everything with less effort
run local --hide stdout  # Hide stdout only
run local --no-hide      # Don't hide anything
class runcommands.args.Arg(*, command, parameter, name, container, type, positional, default, choices, help, inverse_help, short_option, long_option, no_inverse, inverse_short_option, inverse_long_option, action, nargs, mutual_exclusion_group)[source]

Encapsulates an arg belonging to a command.

command

Command this arg belongs to.

Type:Command
parameter

Function parameter this arg is derived from.

Type:Parameter
name

Normalized arg name.

Type:str
container

Container type to collect args into. If this is passed, or if the default value is a container type, values for this arg will be collected into a container of the appropriate type.

Type:type
type

The arg’s type. By default, a positional arg will be parsed as str and an optional/keyword arg will be parsed as the type of its default value (or as str if the default value is None). If a container is specified, or if the default value for the arg is a container, the type will be applied to the container’s values.

Type:type
positional

An arg will automatically be considered positional if it doesn’t have a default value, so this doesn’t usually need to be passed explicitly. It can be used to force an arg that would normally be optional to be positional.

Type:bool
default

Default value for the arg.

Type:object
choices

A sequence of allowed choices for the arg.

Type:sequence
help

Help string for the arg.

Type:str
inverse_help

Inverse help string for the arg (for the --no-xyz variation of boolean args).

Type:str
short_option

Short command line option.

Type:str
long_option

Long command line option.

Type:str
inverse_short_option

Inverse short option for boolean args.

Type:str
inverse_long_option

Inverse long option for boolean args.

Type:str
action

argparse Action.

Type:Action
nargs

Number of command line args to consume.

Type:int|str
mutual_exclusion_group

Name of mutual exclusion group to add this arg to.

Type:str
convert_value(value: str)[source]

Convert string value to this arg’s type.

class runcommands.args.ArgConfig(*, container=None, type=None, choices=None, help=None, inverse_help=None, short_option=None, long_option=None, no_inverse=False, inverse_short_option=None, inverse_long_option=None, inverse_option=None, action=None, nargs=None, mutual_exclusion_group=None, default)[source]

Configuration for an arg.

This can be used as a function parameter annotation to explicitly configure an arg, overriding default behavior.

Parameters:
  • container (type) – Container type to collect args into. If this is passed, or if the default value is a container type, values for this arg will be collected into a container of the appropriate type.
  • type (type) – The arg’s type. By default, a positional arg will be parsed as str and an optional/keyword arg will be parsed as the type of its default value (or as str if the default value is None). If a container is specified, or if the default value for the arg is a container, the type will be applied to the container’s values.
  • choices (sequence) – A sequence of allowed choices for the arg.
  • help (str) – Help string for the arg.
  • inverse_help (str) – Inverse help string for the arg (for the --no-xyz variation of boolean args).
  • short_option (str) – Short command line option.
  • long_option (str) – Long command line option.
  • inverse_short_option (str) – Inverse short option for boolean args.
  • inverse_long_option (str) – Inverse long option for boolean args.
  • action (Action) – argparse Action.
  • nargs (int|str) – Number of command line args to consume.
  • mutual_exclusion_group (str) – Name of mutual exclusion group to add this arg to.
  • default – Default value for positional args.

Note

For convenience, regular dicts can be used to annotate args instead; they will be converted to instances of this class automatically.