cmdargparse 0.1.0

A declarative way to define `cmd2` argument parsers.

cmdargparse

The package provides a declarative way to define cmd2 argument parsers.

Usage

The core functionality is driven by three components:

• cmdargument for defining an argument parser
• cmdfield for declaring the arguments
• cmdcommand for attatching an argument parser to a command

class MyApplication(cmd2.Cmd):

    @cmdargument
    class _MyCommandArgs(cmdargument):
        my_argument: str = cmdfield.argument(...)
        my_option: str = cmdfield.option(...)
        my_flag: str = cmdfield.flag(...)

    @cmdcommand(_MyCommandArgs)
    def do_mycommand(self, args: _MyCommandArgs) -> None:
        args.pfields(self)

Example Application

Arguments (positional)

• choices
  The restricted set of values allowed for the argument.
• choicesmap
  Additional values allowed for the argument that each map to the specified value in the restricted set of values.
• default
  The arguments default value if not specified.
  (Providing a default value makes the argument optional.)
• type
  Explicitly specifies the type to be used by argparse.
  https://docs.python.org/3/library/argparse.html#type
• help
  Brief description of the argument.
• helpvar
  Reference name of the argument value in the help message.

Examples

arg: str | None = cmdfield.argument(
    ("alpha", "beta"),
    {
        "a": "alpha",
        "b": "beta",
    },
    default=None,
)

Options (non-positional, value-bound)

• decl
  Specifies the primary option declaration.
• altdecl
  Specifies the alternative option declaration.
• choices
  The restricted set of values allowed for the option.
• choicesmap
  Additional values allowed for the option that each map to the specified value in the restricted set of values.
• default
  The options default value if not specified.
• form
  Specifies the default form of the option declaration.
• decls
  Explicitly specifies all option declarations.
• more_decls
  Specifies additional option declarations.
• type
  Explicitly specifies the type to be used by argparse.
  https://docs.python.org/3/library/argparse.html#type
• required
  Marks the option as required.
• help
  Brief description of the option.
• helpvar
  Reference name of the option value in the help message.

Examples

xx: str | None = cmdfield.option()
yy: int | None = cmdfield.option([1, 2, 3])
zz: str = cmdfield.option(required=True)

Declarations

aa: str | None = cmdfield.option()                       # -aa  OR  --aa
bb: str | None = cmdfield.option("--cc")                 # -bb, --cc  OR  --cc
dd: str | None = cmdfield.option("-ee")                  # -ee  OR  --dd, -ee
ff: str | None = cmdfield.option("--gg", "-ii")          # --gg, -ii
jj: str | None = cmdfield.option(form="--")              # --jj
kk: str | None = cmdfield.option(form="-")               # -kk
mm: str | None = cmdfield.option(decls="--mm")           # --mm
nn: str | None = cmdfield.option(decls="-oo")            # -oo
pp: str | None = cmdfield.option(decls=("--rr", "-ss"))  # --rr, -ss
tt: str | None = cmdfield.option(more_decls="-uu")       # -tt, -uu

Flags (non-positional, non-value)

• decl
  Specifies the primary flag declaration.
• altdecl
  Specifies the alternative flag declaration.
• invert
  Sets the value False instead of True if the flag is specified.
• const
  The value to set if the flag is specified.
• form
  Specifies the default form of the flag declaration.
• decls
  Explicitly specifies all flag declarations.
• more_decls
  Specifies additional flag declarations.
• type
  Explicitly specifies the type to be used by argparse.
  https://docs.python.org/3/library/argparse.html#type
• help
  Brief description of the flag.

Examples

vv: bool = cmdfield.flag()
ww: bool = cmdfield.flag(invert=True)
xx: float | None = cmdfield.flag(const=1.23)
yy: str | None = cmdfield.flag(const="text")
zz: Literal["ltr"] | None = cmdfield.flag(const="ltr")

Declarations

aa: bool = cmdfield.flag()                       # -aa  OR  --aa
bb: bool = cmdfield.flag("--cc")                 # -bb, --cc  OR  --cc
dd: bool = cmdfield.flag("-ee")                  # -ee  OR  --dd, -ee
ff: bool = cmdfield.flag("--gg", "-ii")          # --gg, -ii
jj: bool = cmdfield.flag(form="--")              # --jj
kk: bool = cmdfield.flag(form="-")               # -kk
mm: bool = cmdfield.flag(decls="--mm")           # --mm
nn: bool = cmdfield.flag(decls="-oo")            # -oo
pp: bool = cmdfield.flag(decls=("--rr", "-ss"))  # --rr, -ss
tt: bool = cmdfield.flag(more_decls="-uu")       # -tt, -uu

Q&A

Changing the default declaration form

The cmdargument decorator accepts a form argument to select the default declaration form for an argument parser, which can be either -name (default) or --name.

It is also possible to change the global default declaration form by using the cmdargument.default_form function.