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} = False):
    "Run the specified command, possibly hiding its output.

    If ``hide=True``, *all* output will be hidden. It can also
    be set to one of "stdout" or "stderr" to hide just the
    specified output stream.

    "

Note

The default inner type for bool_or is str. bool_or(str) is equivalent to bool_or.

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

This can also be combined with the container option like so:

@command
def fetch(fields: {'container': dict, type: bool_or(int)}):
    "Get data from somewhere and show the specified fields.

    If ``fields=True``, all fields will be shown with their
    original names. If fields are specified, only those fields
    will be shown, with their names mapped. For example,
    ``fields`` could be::

        {'givenName': 'first_name', 'sn': 'last_name'}

    "

Note

When combined with container, the type passed to bool_or is applied to the values in the container rather than being applied to the literal strings passed on the command line.

type¶: alias of builtins.str

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, envvar)[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

envvar¶

Environment variable containing a default value to use when the arg isn’t specified on the command line.

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, envvar=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.
envvar (str) – Environment variable containing a default value to use when the arg isn’t specified on the command line.
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.

RunCommands

Navigation

args¶