argclz.core.argument#

argclz.core.argument(*options: str | Validator, action: Literal['store', 'store_const', 'store_true', 'store_false', 'append', 'append_const', 'extend', 'count', 'help', 'version', 'boolean'] = ..., nargs: int | Literal['*', '+', '?', '...'] = ..., const: T = ..., default: T = ..., type: Type | Callable[[str], T] = ..., validator: Callable[[T], bool] = ..., choices: Sequence[T] = ..., required: bool = False, hidden: bool = False, help: str = ..., group: str | None = None, ex_group: str | None = None, metavar: str = ...) → T[source]#

create an argument attribute

Usage

>>> class Example:
...     a: str = argument('-a')

Type (caster)

The parameter type usually can be infered via the annotation of target attribute, like the a: str in above example.

There are some special rules to treat common type:

  • Literal types: Literal[...] annotations create a caster that restricts values to the specified literals.

  • Boolean flags: annotating with bool automatically sets up a store_true or store_false action, making the option a flag.

  • Container types: list[T] annotations infer a repeated option with append (or extend) action, converting each input to type T.

  • Tuple types: tuple annotations (e.g. tuple[int, ...]) use a comma-separated parser to split and convert values into a tuple of T.

If the default type infered does not fit your application, you can give it directly.

Validator

Although parameter type can handle some validation works, it is ignored when user assign value to the attribute directly. The parameter validator is used to perform the assignment validation work and raise a ValueError (normal case) if any improper assignments.

The parameter validator has been treated specially when use validator, which it can put at lastest position of options

>>> from argclz import argument, validator
>>> class Example:
...     a: str = argument('-a', validator.str.match(r'\d+'))
Parameters:

  • options – options strings

  • action – argument action. Please see argparse.ArgumentParser.add_argument(action) for detailed.

  • nargs – number of following values. Please see argparse.ArgumentParser.add_argument(nargs) for detailed.

  • const – Please see argparse.ArgumentParser.add_argument(const) for detailed.

  • default – default value of argument. Please see argparse.ArgumentParser.add_argument(default) for detailed.

  • type – type caster with signature (str) -> T. Please see argparse.ArgumentParser.add_argument(type) for detailed.

  • validator – value validator with signature (T) -> bool.

  • choices – Please see argparse.ArgumentParser.add_argument(choices) for detailed.

  • required – Please see argparse.ArgumentParser.add_argument(required) for detailed.

  • hidden – hide this argument from help document.

  • help – help document for this argument.

  • group – group name of this argument.

  • ex_group – the mutually exclusive group name of this argument.

  • metavar – name of argument value. Please see argparse.ArgumentParser.add_argument(metavar) for detailed.