argread: Parse command-line arguments and options

This class provides the ArgReader class, instances of which can be used to customize available command-line options for a given interface.

The ArgReader class has the function ArgReader.parse(), which interprets sys.argv and splits it into a list of args and kwargs. The base ArgReader class will parse command-line arguments in useful ways, but one of the main intents is to subclass ArgReader and customize how various CLI arguments are parsed.

Here are some examples of the base interpreter, which can also be used with the convenience function readkeys().

>>> readkeys(["prog", "arg1", "arg2", "-v", "--name", "argread"])
("arg1", "arg2"), {"v": True, "name": "argread"}
>>> readkeys(["prog", "-v", "1", "2", "-name", "argread", "d=3"])
("2",), {"v": "1", "name": "argread", "d": "3"}

Notice that the 1 goes as the value of the option v. The 2 is not preceded by a str starting with a dash, so it gets interpreted as an arg.

There is an alternate function readflags() that interprets multi-letter args starting with a single dash differently:

>>> readflags(["prog", "-lh", "fname"])
("fname",), {"l": True, "h": True}

There is a third function readflagstar() that interprets arguments like tar

>>> readflagstar(["prog", "-cvf", "fname"])
(), {"c": True, "v": True, "f": "fname"}

These convenience functions make it easy to parse many command-line inputs with minimal effort, but it is also possible to declare richer and more specific interfaces by subclassing ArgReader.

For example

class MyParser(ArgReader):
    _optlist_noval = (
        "default",
        "verbose",
    )
    _optmap = {
        "d": "default",
        "v": verbose",
    }

has two properties. First -d and -v are abbreviations for --default and --verbose, respectively, because of the entries in MyParser._optmap. Second, neither option can take a “value”, so

$ prog -d hub url

would be parsed as

("hub", "url"), {"default": True}

In other words, the word hub didn’t get interpreted as the value for the option d as it would with the default ArgReader.

Another common use case is to convert CLI strings to another type. For example suppose you have an option i that takes in the index of something you want to work with, like

$ prog -i 3

The default readkeys() in this case would return

(), {"i": "3"}

you can convert this str "3" to an int with the following subclass

class MyConverter(ArgReader):
    _optconverters = {
        "i": int,
    }

This ArgReader also allows for convenient and powerful parsing of functions arguments. See for example

def f(a, b, **kw):
    ...

Users of this module create subclasses of ArgReader that process the expected keyword arguments to f(). The argument-parsing capabilities of ArgReader include

  • only allowing specific keys (ArgReader._optlist)

  • mapping kwargs to alternate names, e.g. using v as a shortcut for verbose (ArgReader._optmap)

  • specifying the type(s) allowed for specific options (ArgReader._opttypes)

  • creating aliases for values (ArgReader._optvalmap)

  • calling converter functions (e.g. int() to convert a str to an int) (ArgReader._optconverters)

Suppose you have a function

def f(a, b, **kw):
    ...

Where a should be a str, b should be an int, and the only kwargs are verbose and help, which should both be bool. However, users can use h as an alias for help and v for verbose. Then we could write a subclass of ArgReader to parse and validate args to this function.

class FKwargs(ArgReader):
    _optlist = ("help", "verbose")
    _optmap = {
        "h": "help",
        "v": "verbose",
    }
    _opttypes = {
        "a": str,
        "b": int,
        "help": bool,
        "verbose": bool,
    }
    _arglist = ("a", "b")
    _nargmin = 2
    _nargmax = 2

Here is how this parser handles an example with expected inputs.

>>> opts = FKwargs("me", 33, v=True)
>>> print(opts)
{'verbose': True}
>>> print(opts.get_argvals())
('me', 33)

In many cases it is preferable to use

within ArgReader._opttypes, e.g.

class FKwargs(ArgReader):
    _optlist = ("help", "verbose")
    _optmap = {
        "h": "help",
        "v": "verbose",
    }
    _opttypes = {
        "a": str,
        "b": INT_TYPES,
        "help": BOOL_TYPES,
        "verbose": BOOL_TYPES,
    }
    _arglist = ("a", "b")
    _nargmin = 2
    _nargmax = 2

so that values taken from numpy arrays are also recognized as valid “integers,” “floats,” or “booleans.”

Here are some examples of how FKwargs might handle bad inputs.

>>> FKwargs("my", help=True)
File "argread.py", line 172, in wrapper
    raise err.__class__(msg) from None
argread.ArgReadTypeError: FKwargs() takes 2 arguments, but 1 were given
>>> FKwargs(2, 3)
File "argread.py", line 172, in wrapper
    raise err.__class__(msg) from None
argread.ArgReadTypeError: FKwargs() arg 0 (name='a'): got type 'int';
expected 'str'
>>> FKwargs("my", 10, b=True)
File "argread.py", line 172, in wrapper
    raise err.__class__(msg) from None
argread.ArgReadNameError: FKwargs() unknown kwarg 'b'
>>> FKwargs("my", 10, h=1)
File "argread.py", line 172, in wrapper
    raise err.__class__(msg) from None
argread.ArgReadTypeError: FKwargs() kwarg 'help': got type 'int';
expected 'bool'

In order to use an instance of this FKwargs there are several approaches. The first is to call the parser class directly:

def f(a, b, **kw):
    opts = FKwargs(a, b, **kw)
    ...

Another method is to use FKwargs as a decorator

@FKwargs.parse
def f(a, b, **kw):
    ...

The decorator option ensures that a, b, and kw have all been validated. Users can then use kw.get("help") without needing to check for h.

class cape.argread.ArgReader(*args, **kw)

Class to parse command-line interface arguments

Call:
>>> parser = ArgReader(**kw)
Outputs:
parser: ArgReader

Instance of command-line argument parser

Attributes:
apply_argconverter(j: int, argname: str, rawval: Any)

Apply option converter function to raw positional arg value

Call:
>>> val = opts.apply_argconverter(j, argname, rawval)
Inputs:
opts: ArgReader

Keyword argument parser instance

j: int

Positional parameter (arg) index

argname: None | str

Positional parameter (arg) name, if appropriate

rawval: object

Value of option, before _optconverters

Outputs:
val: {rawval} | object

Result of calling optconverter for opt on rawval

Raises:

ArgReadTypeError if optconverter for opt is not callable

apply_cmdmap(cmdname: str) → str

Apply aliases for sub-command name

Call:
>>> fullcmdname = parser.apply_cmdmap(cmdname)
Inputs:
parser: ArgReader

Command-line argument parser

cmdname: str

Name of sub-command as supplied by user

Outputs:
fullcmdname: str

Standardized name of cmdname, usually just cmdname

apply_optconverter(opt: str, rawval: Any)

Apply option converter function to raw value

Call:
>>> val = opts.apply_optconverter(opt, rawval)
Inputs:
opts: ArgReader

Keyword argument parser instance

opt: str

De-aliased option name

rawval: object

Raw user value for opt before using optconverter

Outputs:
val: {rawval} | object

Result of calling optconverter for opt on rawval

Raises:

ArgReadTypeError if optconverter for opt is not callable

apply_optmap(rawopt: str) → str

Apply alias to raw option name, if applicable

Call:
>>> opt = opts.apply_optmap(rawopt)
Inputs:
opts: ArgReader

Keyword argument parser instance

rawopt: str

Option name or alias, before _optmap

Outputs:
opt: {rawopt} | str

De-aliased option name

apply_optvalmap(opt: str, rawval: Any)

Apply option value map (aliases for value), if any

Call:
>>> val = opts.apply_optconverter(opt, rawval)
Inputs:
opts: ArgReader

Keyword argument parser instance

opt: str

De-aliased option name

rawval: object

Raw user value for opt before using optconverter

Outputs:
val: {rawval} | object

Dealiased (by _optvalmap[opt]) value

argv

list[str] – List of raw CLI commands parsed

argvals

list – Current values of non-keyword arguments

classmethod check(func: Callable)

Decorator for a function to parse and validate its inputs

Call:
>>> wrapper = cls.parse(func)
Example:
@cls.check
def func(*a, **kw):
    ...
Inputs:
func: callable

A function, class, or callable instance

Outputs:
cls: type

A subclass of ArgReader

wrap: callable

A wrapped version of func that parses and validates args and kwargs according to cls before calling func

check_argtype(j: int, argname: str, val: Any)

Check type of positional arg after conversion function

Call:
>>> opts.check_argtype(opt, val)
Inputs:
opts: ArgReader

Keyword argument parser instance

j: int

Positional parameter (arg) index

argname: None | str

Positional parameter (arg) name, if appropriate

val: object

Value for parameter in position j, after conversion

Raises:

ArgReadTypeError if val has wrong type

check_argval(j: int, argname: str, val: Any)

Check positional arg value against list of recognized values

Call:
>>> opts.check_optval(opt, rawval)
Inputs:
opts: ArgReader

Keyword argument parser instance

j: int

Positional parameter (arg) index

argname: None | str

Positional parameter (arg) name, if appropriate

val: object

Value for arg in position j

Raises:

ArgReadValueError if argname has an optval setting and val is not in it

check_optname(opt: str)

Check validity of an option name

Call:
>>> opts.check_optname(opt)
Inputs:
opts: ArgReader

Keyword argument parser instance

opt: str

De-aliased option name

Raises:

ArgReadNameError if opt is not recognized

check_opttype(opt: str, val: Any)

Check type of option value after conversion function

Call:
>>> opts.check_opttype(opt, rawval)
Inputs:
opts: ArgReader

Keyword argument parser instance

opt: str

De-aliased option name

val: object

Value for opt

Raises:

ArgReadTypeError if val has wrong type

check_optval(opt: str, val: Any)

Check option value against list of recognized values

Call:
>>> opts.check_optval(opt, rawval)
Inputs:
opts: ArgReader

Keyword argument parser instance

opt: str

De-aliased option name

val: object

Value for opt

Raises:

ArgReadValueError if opt has an optval setting and val is not in it

check_rawargtype(j: int, argname: str, rawval: Any)

Check type of positional arg prior to conversion function

Call:
>>> opts.check_rawargtype(opt, rawval)
Inputs:
opts: ArgReader

Keyword argument parser instance

j: int

Positional parameter (arg) index

argname: None | str

Positional parameter (arg) name, if appropriate

rawval: object

Value of option, before _optconverters

Raises:

ArgReadTypeError if rawval has wrong type

check_rawopttype(opt: str, rawval: Any)

Check type of option value prior to conversion function

Call:
>>> opts.check_rawopttype(opt, rawval)
Inputs:
opts: ArgReader

Keyword argument parser instance

opt: str

De-aliased option name

rawval: object

Raw user value for opt before using optconverter

Raises:

ArgReadTypeError if rawval has wrong type

cmdname

str – Name of subcommand to use, if any

decide_cmdname(argv: list | None = None) → SubCmdTuple

Identify sub-command if appropriate

Call:
>>> cmdname, subargv = parser.decide_cmdname(argv=None)
Inputs:
parser: ArgReader

Command-line argument parser

argv: {None} | list[str]

Raw command-line args to parse {sys.argv}

Outputs:
cmdname: str

(Standardized) name of sub-command as supplied by user

subargv: list[str]

Command-line arguments for sub-command to parse

equal_sign_key = True

Option to allow equal-sign options, e.g. key=val becomes {"key": "val"}

exc_cls

Base exception class: Exception

alias of ArgReadError

fullparse(argv: list | None = None) → SubParserTuple

Identify sub-command and use appropriate parser

Call:
>>> cmdname, subparser = parser.fullparse(argv=None)
Inputs:
parser: ArgReader

Command-line argument parser

argv: {None} | list[str]

Optional arguments to parse, else sys.argv

Outputs:
cmdname: None | str

Name of command, if identified or inferred

subparser: ArgReadder

Parser for cmdname applied to remaining CLI args

fullparse_check(argv: list | None = None) → SubParserCheck

Identify sub-command and use appropriate parser

Call:
>>> cmdname, subparser, ierr = parser.fullparse_check(argv)
Inputs:
parser: ArgReader

Command-line argument parser

argv: {None} | list[str]

Optional arguments to parse, else sys.argv

Outputs:
cmdname: None | str

Name of command, if identified or inferred

subparser: ArgReadder

Parser for cmdname applied to remaining CLI args

ierr: int

Return code

genr8_help() → str

Generate automatic help message to use w/ -h

Call:
>>> msg = parser.genr8_optshelp()
Inputs:
parser: ArgReader

Command-line argument parser

Outputs:
msg: str

Help message

genr8_opthelp(opt: str) → str

Generate a help message for a particular option

Call:
>>> msg = parser.genr8_opthelp(opt)
Inputs:
parser: ArgReader

Command-line argument parser

opt: str

Name of option

Outputs:
msg: str

Help message for option opt

genr8_optshelp() → str

Generate help message for all the options in _optlist

Call:
>>> msg = parser.genr8_optshelp()
Inputs:
parser: ArgReader

Command-line argument parser

Outputs:
msg: str

Help message for all options

get_a_kw() → ArgTuple

Get dictionary of kwargs, applying defaults

Call:
>>> a, kw = opts.get_a_kw()
Inputs:
opts: ArgReader

Keyword argument parser instance

Outputs:
kwargs: dict

Keyword arguments and values currently parsed

get_aliases(opt: str) → list

Get list of aliases for a particular option

Call:
>>> names = parser.get_aliases(opt)
Inputs:
parser: ArgReader

Command-line argument parser

opt: str

Name of option

Outputs:
names: list[str]

List of aliases, including opt; primary name first

get_argdict() → dict

Get dictionary of all args and kwargs by name

Unnamed positional arguments will have names like arg5.

Call:
>>> kw = parser.get_argdict()
Outputs:
kw: dict

Dictionary of positional and keyword names and values

classmethod get_argname(j: int)

Get name for an argument by index, if applicable

Call:
>>> argname = cls.get_argname(j)
Inputs:
cls: type

A subclass of ArgReader

j: int

Positional parameter (arg) index

Outputs:
argname: None | str

Argument option name, if applicable

get_args() → ArgTuple

Get full list of args and options from parsed inputs

Call:
>>> args, kwargs = parser.get_args()
Outputs:
args: list[str]

List of positional parameter argument values

kwargs: dict

Dictionary of named options and their values

get_argtuple() → tuple

Get list of all args and kwargs by name

Unnamed positional arguments will have names like arg5.

Call:
>>> argtuple = parser.get_argtuple()
Outputs:
argtuple: tuple[str, object]

Tuple of name/value pairs, including overwritten kwargs

get_argvals() → tuple

Return a copy of the current positional parameter values

Call:
>>> args = opts.get_argvals()
Inputs:
opts: ArgReader

Keyword argument parser instance

Outputs:
args: tuple[object]

Current values of positional parameters

get_cli_args() → ArgTuple

Get full list of args and options from parsed inputs

Call:
>>> args, kwargs = parser.get_cli_args()
Outputs:
args: list[str]

List of positional parameter argument values

kwargs: dict

Dictionary of named options and their values

kwargs[“__replaced__”]: tuple

Overwritten repeat CLI options

get_cli_kwargs() → dict

Get full list of kwargs, including repeated values

Call:
>>> args, kwargs = parser.get_args()
Outputs:
kwargs: dict

Dictionary of named options and their values

classmethod get_cls_name() → str

Get a name to use for a given class

Call:
>>> clsname = cls.get_cls_name()
Inputs:
cls: type

A subclass of ArgReader

Outputs:
clsname: str

cls._name if set, else cls.__name__

get_kwargs() → dict

Get dictionary of kwargs, applying defaults

Call:
>>> kwargs = opts.get_kwargs()
Inputs:
opts: ArgReader

Keyword argument parser instance

Outputs:
kwargs: dict

Keyword arguments and values currently parsed

get_opt(opt: str, vdef: Any | None = None)

Get value of one option

Call:
>>> val = opts.get_opt(opt, vdef=None)
Inputs:
opts: ArgReader

Keyword argument parser instance

opt: str

Name of option

vdef: {None} | object

Default value if opt not found in opts or _rc

classmethod get_optconverter(opt: str)

Get option value converter, if any, for option opt

Output must be a callable function that takes one argument

Call:
>>> func = cls.get_optconverter(opt)
Inputs:
cls: type

A subclass of ArgReader

opt: str

Full (non-aliased) name of option

Outputs:
func: None | function | callable

Function or other callable object

classmethod get_optlist() → set

Get list of allowed options from cls and its bases

This combines the _optlist attribute from cls and any bases it might have that are also subclasses of ArgReader.

If optlist is an empty set, then no constraints are applied to option names.

Call:
>>> optlist = cls.get_opttype(opt)
Inputs:
cls: type

A subclass of ArgReader

Outputs:
optlist: set[str]

Single type or list of types for opt

classmethod get_opttype(opt: str)

Get the type(s) allowed for the value of option opt

If opttype is None, no constraints are placed on the value of opt. The “value” differs from the “raw value” in that the “value” is after any converters have been applied.

Call:
>>> opttype = cls.get_opttype(opt)
Inputs:
cls: type

A subclass of ArgReader

opt: str

Full (non-aliased) name of option

Outputs:
opttype: None | type | tuple

Single type or list of types for opt

classmethod get_optvalmap(opt: str)

Get option value aliases, if any, for option opt

Output must be a dict

Call:
>>> valmap = cls.get_optvalmap(opt)
Inputs:
cls: type

A subclass of ArgReader

opt: str

Full (non-aliased) name of option

Outputs:
valmap: None | dict

Map of alias values for opt

classmethod get_optvals(opt: str)

Get a set/list/tuple of allowed values for option opt

If optvals is not None, the full (post-optconverter) value will be checked if it is in optvals.

Call:
>>> optvals = cls.get_optvals(opt)
Inputs:
cls: type

A subclass of ArgReader

opt: str

Full (non-aliased) name of option

Outputs:
optvals: None | set | tuple

Tuple, list, set, or frozenset of allowed values

classmethod get_rawopttype(opt: str)

Get the type(s) allowed for the raw value of option opt

If opttype is None, no constraints are placed on the raw value of opt. The “raw value” is the value for opt before any converters have been applied.

Call:
>>> opttype = cls.get_rawopttype(opt)
Inputs:
cls: type

A subclass of ArgReader

opt: str

Full (non-aliased) name of option

Outputs:
opttype: None | type | tuple

Single type or list of types for raw opt

classmethod getx_cls_arg(attr: str, argname: str, vdef: Any | None = None) → Any

Get dict class attribute for positional parameter

If argname is None, the parameter (arg) has no name, and only "_arg_default_" and "_default_" can be used from getattr(cls, attr).

Otherwise, this will look in the bases of cls if getattr(cls, attr) does not have argname. If cls is a subclass of another ArgReader class, it will search through the bases of cls until the first time it finds a class attribute attr that is a dict containing key.

Call:
>>> v = cls.getx_cls_key(attr, key, vdef=None)
Inputs:
cls: type

A subclass of ArgReader

attr: str

Name of class attribute to search

key: str

Key name in cls.__dict__[attr]

vdef: {None} | object

Default value to use if not found in class attributes

Outputs:
v: None | ojbect

Any value, None if not found

classmethod getx_cls_dict(attr: str) → dict

Get combined dict for cls and its bases

This allows a subclass of ArgReader to only add to the _opttypes or _optmap attribute rather than manually include contents of all the bases.

Call:
>>> clsdict = cls.getx_cls_dict(attr)
Inputs:
cls: type

A subclass of ArgReader

attr: str

Name of class attribute to search

Outputs:
clsdict: dict

Combination of getattr(cls, attr) and getattr(base, attr) for each base in cls.__bases__, etc.

classmethod getx_cls_key(attr: str, key: str, vdef: Any | None = None) → Any

Access key from a dict class attribute

This will look in the bases of cls if getattr(cls, attr) does not have key. If cls is a subclass of another ArgReader class, it will search through the bases of cls until the first time it finds a class attribute attr that is a dict containing key.

Call:
>>> v = cls.getx_cls_key(attr, key, vdef=None)
Inputs:
cls: type

A subclass of ArgReader

attr: str

Name of class attribute to search

key: str

Key name in cls.__dict__[attr]

vdef: {None} | object

Default value to use if not found in class attributes

Outputs:
v: None | ojbect

Any value, None if not found

classmethod getx_cls_set(attr: str) → set

Get combined set for cls and its bases

This allows a subclass of ArgReader to only add to the _optlist attribute rather than manually include the _optlist of all the bases.

Call:
>>> v = cls.getx_cls_set(attr)
Inputs:
cls: type

A subclass of ArgReader

attr: str

Name of class attribute to search

Outputs:
v: set

Combination of getattr(cls, attr) and getattr(base, attr) for each base in cls.__bases__, etc.

help_frontdesk(cmdname: str | None, opt: str = 'help') → bool

Display help message for front-desk parser, if appropriate

Call:
>>> q = parser.help_frontdesk(cmdname)
Inputs:
parser: ArgReader

Command-line argument parser

cmdname: None | str

Name of sub-command, if specified

opt: {"help"} | str

Name of option to trigger help message

Outputs:
q: bool

Whether front-desk help was triggered

infer_cmdname() → str | None

Infer sub-command if not determined by first argument

This command is usually overwritten in subclasses for special command-line interfaces where the primary task is inferred from options. This version always returns None

Call:
>>> cmdname = parser.infer_cmdname()
Inputs:
parser: ArgReader

Command-line argument parser

Outputs:
cmdname: str

Name of sub-command

init_post()

Custom post-initialization hook

This function is called in the standard __init__(). The default init_post() does nothing. Users may define custom actions in init_post() in subclasses to make certain changes at the end of parsing

Call:
>>> opts.init_post()
Inputs:
opts: ArgReader

Keyword argument parser instance

kwargs_double_dash

list[str] – List of options that were entered with a double dash

kwargs_equal_sign

list[str] – List of options that were entered using key=val syntax

kwargs_replaced

list[str] – List of options that have duplicates

kwargs_sequence

list[str] – List of options in original order

kwargs_single_dash

list[str] – List of options that were entered with a single dash

param_sequence

list[str, object] – List of option name and value as parsed (includes duplicates in their original order)

parse(argv: list | None = None) → ArgTuple

Parse CLI args

Call:
>>> a, kw = parser.parse(argv=None)
Inputs:
parser: ArgReader

Command-line argument parser

argv: {None} | list[str]

Optional arguments to parse, else sys.argv

Outputs:
a: list

List of positional arguments

kw: dict

Dictionary of options and their values

parse_args(args: tuple)

Parse positional parameters

Call:
>>> opts.parse_args(args)
Inputs:
opts: ArgReader

Keyword argument parser instance

args: list | tuple

Ordered list of positional argument values

parse_cli_full(argv: list | None = None) → ArgTuple

Parse CLI args

Call:
>>> a, kw = parser.parse_cli_full(argv=None)
Inputs:
parser: ArgReader

Command-line argument parser

argv: {None} | list[str]

Optional arguments to parse, else sys.argv

Outputs:
a: list

List of positional arguments

kw: dict

Dictionary of options and their values

kw[“__replaced__”]: list[(str, any)]

List of any options replaced by later values

prog

str – Name of program read from argv[0]

reconstruct(params: list | None = None) → list

Recreate a command from parsed information

Call:
>>> cmdlist = parser.reconstruct()
Inputs:
parser: ArgReader

Command-line argument parser

params: {None} | list[tuple]

Optional list of parameters (default from parser)

Outputs:
cmdlist: list[str]

Reconstruction of originally parsed command

save_arg(arg: Any)

Save a positional argument

Call:
>>> parser.save_arg(arg, narg=None)
Inputs:
parser: ArgReader

Command-line argument parser

arg: str

Name/value of next parameter

save_double_dash(k: str, v: bool | str = True)

Save a double-dash keyword and value

Call:
>>> parser.save_double_dash(k, v=True)
Inputs:
parser: ArgReader

Command-line argument parser

k: str

Name of key to save

v: {True} | False | str

Value to save

save_equal_key(k: str, v: Any)

Save an equal-sign key/value pair, like "mach=0.9"

Call:
>>> parser.save_equal_key(k, v)
Inputs:
parser: ArgReader

Command-line argument parser

k: str

Name of key to save

v: str

Value to save

save_single_dash(k: str, v: bool | str = True)

Save a single-dash keyword and value

Call:
>>> parser.save_single_dash(k, v=True)
Inputs:
parser: ArgReader

Command-line argument parser

k: str

Name of key to save

v: {True} | False | str

Value to save

set_arg(j: int, rawval: Any)

Set the value of the j-th positional argument

Call:
>>> opts.set_arg(j, rawval)
Inputs:
opts: ArgReader

Keyword argument parser instance

j: int >= 0

Argument index

rawval: object

Value for arg j, before _optconverters

set_args(args: tuple)

Set the values of positional arguments

Call:
>>> opts.set_args(args)
Inputs:
opts: ArgReader

Keyword argument parser instance

args: list | tuple

Ordered list of positional argument values

set_opt(rawopt: str, rawval: Any)

Set the value of a single option

Call:
>>> opts.set_opt(rawopt, rawval)
Inputs:
opts: ArgReader

Keyword argument parser instance

rawopt: str

Name or alias of option to set

rawval: object

Pre-conversion value of rawopt

set_opts(a: dict)

Set a collection of options

Call:
>>> opts.set_opts(a)
Inputs:
opts: ArgReader

Keyword argument parser instance

a: dict

Dictionary of options to update into opts

show_help(opt: str = 'help') → bool

Display help message for non-front-desk parser if requested

Call:
>>> q = parser.show_help(opt="help")
Inputs:
parser: ArgReader

Command-line argument parser

opt: {"help"} | str

Name of option to trigger help message

Outputs:
q: bool

Whether front-desk help was triggered

single_dash_lastkey = False

Option to interpret multi-char words with a single dash the way POSIX command tar does, e.g. -cvf val becomes {"c": True, "v": True, "f": "val"}

single_dash_split = False

Option to interpret multi-char words with a single dash as single-letter boolean options, e.g. -lh becomes {"l": True, "h": True}

validate_argval(j: int, argname: str, rawval: Any)

Validate a raw positional parameter (arg) value

Call:
>>> val = opts.validate_argval(j, argname, rawval)
Inputs:
opts: ArgReader

Keyword argument parser instance

j: int

Argument index

argname: None | str

Argument name, if applicable

rawval: object

Value of option, before _optconverters

Outputs:
val: object

Converted value, either rawval or optconverter(rawval)

validate_opt(rawopt: str, rawval: Any) → OptPair

Validate a raw option name and raw value

Replaces rawopt with non-aliased name and applies any optconverter to rawval. Raises an exception if option name, type, or value does not match expectations.

Call:
>>> optpair = opts.validate_opt(rawopt, rawval)
>>> opt, val = opts.validate_opt(rawopt, rawval)
Inputs:
opts: ArgReader

Keyword argument parser instance

rawopt: str

Name or alias of option, before _optlist

rawval: object

Value of option, before _optconverters

Outputs:
optpair: OptPair

tuple of de-aliased option name and converted value

opt: str

De-aliased option name (after optmap applied)

val: object

Converted value, either rawval or optconverter(rawval)

validate_optval(opt: str, rawval: Any)

Validate a raw option value

Call:
>>> val = opts.validate_optval(opt, rawval)
Inputs:
opts: ArgReader

Keyword argument parser instance

opt: str

De-aliased option name (after optmap applied)

rawval: object

Value of option, before _optconverters

Outputs:
val: object

Converted value, either rawval or optconverter(rawval)

class cape.argread.ArgTuple(a, kw)
a

Alias for field number 0

kw

Alias for field number 1

cape.argread.BOOL_TYPES = (<class 'bool'>, <class 'numpy.bool'>)

Collection of boolean-like types: bool | numpy.bool_

cape.argread.FLOAT_TYPES = (<class 'float'>, <class 'numpy.floating'>)

Collection of floating-point types: float | numpy.float16 | numpy.float32 | numpy.float64 | numpy.float128

class cape.argread.FlagsArgReader(*args, **kw)

Subclass of ArgReader for readflags()

The class attribute FlagsArgRead.single_dash_split is set to True so that -opt val is interpreted as

{"o": True, "p": True, "t": True}

and "val" becomes an argument.

single_dash_split = True

Option to interpret multi-char words with a single dash as single-letter boolean options, e.g. -lh becomes {"l": True, "h": True}

cape.argread.INT_TYPES = (<class 'int'>, <class 'numpy.integer'>)

Collection of integer (including unsigned) types: int | numpy.int8 | numpy.int16 | numpy.int32 | numpy.int64 | numpy.uint8 | numpy.uint16 | numpy.uint32 | numpy.uint64

class cape.argread.KeysArgReader(*args, **kw)

Subclass of ArgReader for readkeys()

The class attribute KeysArgRead.single_dash_split is set to False so that -opt val is interpreted as

{"opt": "val"}
single_dash_split = False

Option to interpret multi-char words with a single dash as single-letter boolean options, e.g. -lh becomes {"l": True, "h": True}

class cape.argread.MetaArgReader(name: str, bases: tuple, namespace: dict)

Metaclass for ArgReader

This metaclass combines attributes w/ bases. For example if creating a new class Class2 that inherits from Class1, this will automatically combine Class1._optlist` and ``Class2._optlist and save the result as Class2._optlist. This happens behind the scenes so that users do not need to worry about repeating _optlist entries.

classmethod combine_attrs(clsj: type, cls: type)

Combine attributes of clsj and cls

Call:
>>> metacls.combine_attrs(clsj, cls)
Inputs:
metacls: type

The MetaArgReader metaclass

clsj: type

Parent class (basis) to combine into cls

cls: type

New class in which to save combined attributes

classmethod combine_dict(clsj: type, cls: type, attr: str)

Combine one dict-like class attribute of clsj and cls

Call:
>>> metacls.combine_dict(clsj, cls, attr)
Inputs:
metacls: type

The MetaArgReader metaclass

clsj: type

Parent class (basis) to combine into cls

cls: type

New class in which to save combined attributes

attr: str

Name of attribute to combine

classmethod combine_tuple(clsj: type, cls: type, attr: str)

Combine one tuple-like class attribute of clsj and cls

Call:
>>> metacls.combine_tuple(clsj, cls, attr)
Inputs:
metacls: type

The MetaArgReader metaclass

clsj: type

Parent class (basis) to combine into cls

cls: type

New class in which to save combined attributes

attr: str

Name of attribute to combine

cape.argread.OPTLIST_TYPES = (<class 'set'>, <class 'tuple'>, <class 'frozenset'>, <class 'list'>)

Acceptable types for ArgReader._optlist

class cape.argread.OptPair(opt, val)

Option name/value pair

opt

Alias for field number 0

val

Alias for field number 1

cape.argread.STR_TYPES = (<class 'str'>, <class 'numpy.str_'>)

Collection of string-like types: str | numpy.str_

class cape.argread.SubCmdTuple(cmdname, argv)
argv

Alias for field number 1

cmdname

Alias for field number 0

class cape.argread.SubParserCheck(cmdname, subparser, ierr)
cmdname

Alias for field number 0

ierr

Alias for field number 2

subparser

Alias for field number 1

class cape.argread.SubParserTuple(cmdname, subparser)
cmdname

Alias for field number 0

subparser

Alias for field number 1

class cape.argread.TarFlagsArgReader(*args, **kw)

Subclass of ArgReader for readflags()

The class attributes are

TarArgRead.single_dash_split = True
TarArgRead.single_dash_lastkey = True

so that -opt val is interpreted as

{"o": True, "p": True, "t": "val"}
single_dash_lastkey = True

Option to interpret multi-char words with a single dash the way POSIX command tar does, e.g. -cvf val becomes {"c": True, "v": True, "f": "val"}

single_dash_split = True

Option to interpret multi-char words with a single dash as single-letter boolean options, e.g. -lh becomes {"l": True, "h": True}

cape.argread.randomstr(n: int = 15) → str

Create a random string encded as a hexadecimal integer

Call:
>>> txt = randomstr(n=15)
Inputs:
n: {15} | int

Number of random bytes to encode

cape.argread.readflags(argv=None)

Parse args where -cj becomes c=True, j=True

Call:
>>> a, kw = readflags(argv=None)
Inputs:
argv: {None} | list[str]

List of args other than sys.argv

Outputs:
a: list[str]

List of positional args

kw: dict[str | bool]

Keyword arguments

cape.argread.readflagstar(argv=None)

Parse args where -cf a becomes c=True, f="a"

Call:
>>> a, kw = readflags(argv=None)
Inputs:
argv: {None} | list[str]

List of args other than sys.argv

Outputs:
a: list[str]

List of positional args

kw: dict[str | bool]

Keyword arguments

cape.argread.readkeys(argv=None)

Parse args where -cj becomes cj=True

Call:
>>> a, kw = readkeys(argv=None)
Inputs:
argv: {None} | list[str]

List of args other than sys.argv

Outputs:
a: list[str]

List of positional args

kw: dict[str | bool]

Keyword arguments

cape.argread.readkeys_full(argv=None)

Parse args where -cj becomes cj=True

Call:
>>> a, kw = readkeys_full(argv=None)
Inputs:
argv: {None} | list[str]

List of args other than sys.argv

Outputs:
a: list[str]

List of positional args

kw: dict[str | bool]

Keyword arguments