Reference

Arger

Bases: ArgumentParser

Contains one parser or multiple commands (subparsers).

Source code in arger/main.py

class Arger(ap.ArgumentParser):
    """Contains one parser or multiple commands (subparsers)."""

    def __init__(
        self,
        func: tp.Callable | None = None,
        version: str | None = None,
        sub_parser_title="commands",
        formatter_class=ap.ArgumentDefaultsHelpFormatter,
        exceptions_to_catch: tp.Sequence[type[Exception]] = (),
        _doc_str: DocstringTp | None = None,
        _level=0,
        **kwargs,
    ):
        """
        Args:
            func: A callable to parse the root parser's arguments.
            version: Adds the `--version` flag.
            sub_parser_title: The sub-parser title to pass.
            exceptions_to_catch: Exceptions to catch and print their messages.
                This will exit with code 1 and hide the traceback.

            _doc_str: Internally passed from `arger.add_cmd`.
            _level: Internal.

            **kwargs: All the arguments that are supported by
                    [ArgumentParser](https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser)

        Examples:
            Adding a version flag:
                version = '%(prog)s 2.0'
                `Arger()` is equivalent to `Arger().add_argument('--version', action='version', version=version)`
        """
        kwargs.setdefault("formatter_class", formatter_class)

        self.sub_parser_title = sub_parser_title
        self.sub_parser: ap._SubParsersAction | None = None

        self.args: dict[str, Argument] = OrderedDict()
        docstr = DocstringParser.parse(func) if _doc_str is None else _doc_str
        kwargs.setdefault("description", docstr.description)
        kwargs.setdefault("epilog", docstr.epilog)

        super().__init__(**kwargs)

        self.set_defaults(**{LEVEL: _level})
        self.func = func
        self.exceptions_to_catch = exceptions_to_catch
        self._add_arguments(docstr, _level)

        if version:
            self.add_argument("--version", action="version", version=version)

    def _add_arguments(self, docstr: DocstringTp, level: int):
        if not self.func:
            return
        option_generator = FlagsGenerator(self.prefix_chars)
        sign = inspect.signature(self.func, eval_str=True)

        for param in sign.parameters.values():
            param_doc = docstr.params.get(param.name)
            self.args[param.name] = Argument.create(param, param_doc, option_generator)

        # parser level defaults
        self.set_defaults(**{f"{FUNC_PREFIX}{level}": self._dispatch})

        for arg_name, arg in self.args.items():
            # useful only when `_namespace_` is requested or it is a kwarg
            if arg_name.startswith("_"):
                continue
            arg.add_to(self)

    def run(self, *args: str, capture_sys=True, **kwargs) -> ap.Namespace:
        """Parse CLI and dispatch functions.

        Args:
            capture_sys: Whether to capture `sys.argv` if `args` is not passed. Useful during testing.
            *args: The arguments passed to `self.parse_args(args)`.
            **kwargs: Passed to the `parse_args` method.
        """
        if not args and capture_sys:
            args = tuple(sys.argv[1:])
        namespace = self.parse_args(args, **kwargs)
        kwargs = vars(namespace)
        kwargs[NS_PREFIX] = copy.copy(namespace)
        kwargs["_arger_"] = self
        # dispatch all functions as in hierarchy
        for level in range(kwargs.get(LEVEL, 0) + 1):
            func_name = f"{FUNC_PREFIX}{level}"
            if func_name in kwargs:
                kwargs[func_name](**kwargs)

        return namespace

    @tp.overload
    def add_cmd(self, func: tp.Callable[P, R]) -> "Arger": ...

    @tp.overload
    def add_cmd(self, func: None = None, **kwargs) -> tp.Callable[[tp.Callable[P, R]], "Arger"]: ...

    def add_cmd(self, func: tp.Callable | None = None, **kwargs) -> tp.Any:
        """Create a sub-command from the function.

        All of its parameters will be converted to CLI arguments based on their types.

        Args:
            func: The function to create a sub-command from.
            **kwargs: Passed to the `subparser.add_parser` method.

        Returns:
            Arger: A new parser created from the function.
        """
        if not self.sub_parser:
            self.sub_parser = self.add_subparsers(title=self.sub_parser_title)

        def _wrapper(fn: tp.Callable[P, R]) -> "Arger":
            docstr = DocstringParser.parse(fn)
            arger = self.sub_parser.add_parser(  # type: ignore
                name=kwargs.pop("name", fn.__name__),
                help=kwargs.pop("help", docstr.description),
                func=fn,
                _doc_str=docstr,
                _level=self.get_default(LEVEL) + 1,
                **kwargs,
            )
            return tp.cast(Arger, arger)

        if func is None:
            return _wrapper
        return _wrapper(func)

    def add_commands(self, *func: tp.Callable) -> tuple["Arger", ...]:
        """Add multiple sub-commands to the main command at once."""
        return tuple(self.add_cmd(fn) for fn in func)

    def _dispatch(self, **ns: tp.Any) -> tp.Any:
        """Calls the given function with arguments parsed from the CLI.

        Args:
            ns: The namespace dictionary after parsing.
        """

        kwargs = {}
        args = []
        for arg_name, arg in self.args.items():
            val = ns[arg_name]
            if arg.kind in {
                inspect.Parameter.POSITIONAL_ONLY,
                inspect.Parameter.POSITIONAL_OR_KEYWORD,
            }:
                args.append(val)
            elif arg.kind == inspect.Parameter.VAR_POSITIONAL:
                args.extend(val)
            else:
                kwargs[arg_name] = val
        return self.func(*args, **kwargs) if self.func else None

__init__(func=None, version=None, sub_parser_title='commands', formatter_class=ap.ArgumentDefaultsHelpFormatter, exceptions_to_catch=(), _doc_str=None, _level=0, **kwargs)

Parameters:

Name	Type	Description	Default
func	Callable | None	A callable to parse the root parser's arguments.	None
version	str | None	Adds the --version flag.	None
sub_parser_title		The sub-parser title to pass.	'commands'
exceptions_to_catch	Sequence[type[Exception]]	Exceptions to catch and print their messages. This will exit with code 1 and hide the traceback.	()
_doc_str	DocstringTp | None	Internally passed from arger.add_cmd.	None
_level		Internal.	0
**kwargs		All the arguments that are supported by ArgumentParser	{}

Examples:

Adding a version flag: version = '%(prog)s 2.0' Arger() is equivalent to Arger().add_argument('--version', action='version', version=version)

Source code in arger/main.py

def __init__(
    self,
    func: tp.Callable | None = None,
    version: str | None = None,
    sub_parser_title="commands",
    formatter_class=ap.ArgumentDefaultsHelpFormatter,
    exceptions_to_catch: tp.Sequence[type[Exception]] = (),
    _doc_str: DocstringTp | None = None,
    _level=0,
    **kwargs,
):
    """
    Args:
        func: A callable to parse the root parser's arguments.
        version: Adds the `--version` flag.
        sub_parser_title: The sub-parser title to pass.
        exceptions_to_catch: Exceptions to catch and print their messages.
            This will exit with code 1 and hide the traceback.

        _doc_str: Internally passed from `arger.add_cmd`.
        _level: Internal.

        **kwargs: All the arguments that are supported by
                [ArgumentParser](https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser)

    Examples:
        Adding a version flag:
            version = '%(prog)s 2.0'
            `Arger()` is equivalent to `Arger().add_argument('--version', action='version', version=version)`
    """
    kwargs.setdefault("formatter_class", formatter_class)

    self.sub_parser_title = sub_parser_title
    self.sub_parser: ap._SubParsersAction | None = None

    self.args: dict[str, Argument] = OrderedDict()
    docstr = DocstringParser.parse(func) if _doc_str is None else _doc_str
    kwargs.setdefault("description", docstr.description)
    kwargs.setdefault("epilog", docstr.epilog)

    super().__init__(**kwargs)

    self.set_defaults(**{LEVEL: _level})
    self.func = func
    self.exceptions_to_catch = exceptions_to_catch
    self._add_arguments(docstr, _level)

    if version:
        self.add_argument("--version", action="version", version=version)

add_cmd(func=None, **kwargs)

add_cmd(func: tp.Callable[P, R]) -> Arger

add_cmd(func: None = None, **kwargs) -> tp.Callable[[tp.Callable[P, R]], Arger]

Create a sub-command from the function.

All of its parameters will be converted to CLI arguments based on their types.

Parameters:

Name	Type	Description	Default
func	Callable | None	The function to create a sub-command from.	None
**kwargs		Passed to the subparser.add_parser method.	{}

Returns:

Name	Type	Description
Arger	Any	A new parser created from the function.

Source code in arger/main.py

def add_cmd(self, func: tp.Callable | None = None, **kwargs) -> tp.Any:
    """Create a sub-command from the function.

    All of its parameters will be converted to CLI arguments based on their types.

    Args:
        func: The function to create a sub-command from.
        **kwargs: Passed to the `subparser.add_parser` method.

    Returns:
        Arger: A new parser created from the function.
    """
    if not self.sub_parser:
        self.sub_parser = self.add_subparsers(title=self.sub_parser_title)

    def _wrapper(fn: tp.Callable[P, R]) -> "Arger":
        docstr = DocstringParser.parse(fn)
        arger = self.sub_parser.add_parser(  # type: ignore
            name=kwargs.pop("name", fn.__name__),
            help=kwargs.pop("help", docstr.description),
            func=fn,
            _doc_str=docstr,
            _level=self.get_default(LEVEL) + 1,
            **kwargs,
        )
        return tp.cast(Arger, arger)

    if func is None:
        return _wrapper
    return _wrapper(func)

add_commands(*func)

Add multiple sub-commands to the main command at once.

Source code in arger/main.py

def add_commands(self, *func: tp.Callable) -> tuple["Arger", ...]:
    """Add multiple sub-commands to the main command at once."""
    return tuple(self.add_cmd(fn) for fn in func)

run(*args, capture_sys=True, **kwargs)

Parse CLI and dispatch functions.

Parameters:

Name	Type	Description	Default
capture_sys		Whether to capture sys.argv if args is not passed. Useful during testing.	True
*args	str	The arguments passed to self.parse_args(args).	()
**kwargs		Passed to the parse_args method.	{}

Source code in arger/main.py

def run(self, *args: str, capture_sys=True, **kwargs) -> ap.Namespace:
    """Parse CLI and dispatch functions.

    Args:
        capture_sys: Whether to capture `sys.argv` if `args` is not passed. Useful during testing.
        *args: The arguments passed to `self.parse_args(args)`.
        **kwargs: Passed to the `parse_args` method.
    """
    if not args and capture_sys:
        args = tuple(sys.argv[1:])
    namespace = self.parse_args(args, **kwargs)
    kwargs = vars(namespace)
    kwargs[NS_PREFIX] = copy.copy(namespace)
    kwargs["_arger_"] = self
    # dispatch all functions as in hierarchy
    for level in range(kwargs.get(LEVEL, 0) + 1):
        func_name = f"{FUNC_PREFIX}{level}"
        if func_name in kwargs:
            kwargs[func_name](**kwargs)

    return namespace

Argument

Source code in arger/main.py

class Argument:
    kind: inspect._ParameterKind

    def __init__(
        self,
        *,
        type: tp.Callable[[str], tp_utils.T] | ap.FileType | None = None,
        metavar: str | None = None,
        required: bool | None = None,
        nargs: int | str | None = None,
        const: tp.Any = None,
        choices: tp.Iterable[tp.Any] | None = None,
        action: str | type[ap.Action] | None = None,
        flags: tp.Sequence[str] = (),
        **kwargs: tp.Any,
    ):
        """Represent positional arguments to the command that are required by default.

        Analogous to
        [ArgumentParser.add_argument](https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser.add_argument)

        Args:
            type: The type to which the command-line argument should be converted.

                Obtained from the type annotation.
                Use the `Argument` class itself if you want to pass variables to `Arger.add_argument`.

                Example: `typing.cast(int, Argument(type=int))`. If not passed, it is returned as a string.

            metavar: A name for the argument in usage messages.

            nargs: The number of command-line arguments that should be consumed.
                To be generated from the type hint.

                Example: Types and how they are converted to `nargs`:

                * `Tuple[str, ...] -> nargs='+'`
                * `Tuple[str, str] -> nargs=2`
                * `List[str]|tuple|list -> nargs=*`

                Note: Even though `Tuple[str, ...]` does not strictly mean "one or more",
                it is supported to make `nargs='+'` easier to add.

            const: Covered by the type hint and the given default value.
            choices: Use `enum.Enum` as the type hint to generate choices automatically.
            action: The basic type of action to be taken
                when this argument is encountered at the command line.

            flags: These are generated from the argument name.
                If you want to override the generated flags, you can pass them explicitly.

            default (tp.Any): The value produced if the argument is absent from the command line.

                * The default value assigned to a keyword argument helps determine
                    the type of option and action if it is not type-annotated.
                * The default value is assigned directly to the parser's default for that option.
                * In addition, it determines the `ArgumentParser` action:
                    * A default value of `False` implies `store_true`, while `True` implies `store_false`.
                    * If the default value is a list, the action is `append`
                    (multiple instances of that option are permitted).
                    * Strings or `None` imply a `store` action.

            kwargs: Delegated to the `ArgumentParser.add_argument` method.
        """
        for var_name in (
            "type",
            "metavar",
            "required",
            "nargs",
            "const",
            "choices",
            "action",
        ):
            value = locals()[var_name]
            if value is not None:
                kwargs[var_name] = value
        self.flags = flags
        self.kwargs = kwargs

    def __repr__(self):
        """Helps during tests."""
        return f"<{self.__class__.__name__}: {self.flags}, {self.kwargs!r}>"

    @classmethod
    def create(
        cls,
        param: inspect.Parameter,
        pdoc: ParamDocTp | None,
        option_generator: FlagsGenerator,
    ) -> "Argument":
        hlp = pdoc.doc if pdoc else ""

        arg = None
        if isinstance(param.annotation, Argument):
            arg = param.annotation
        elif tp_utils.has_annotated(param.annotation):
            typ, arg = tp_utils.get_annotated_args(param.annotation)
            assert isinstance(arg, Argument), "Annotation should be an `arger.Argument` instance."
            param = param.replace(annotation=typ)

        if arg is None:
            arg = Argument()

        if pdoc and pdoc.flags and (not arg.flags):
            arg.flags = pdoc.flags

        arg.kwargs.setdefault("help", hlp)
        arg.update(param, option_generator)
        return arg

    def update(
        self,
        param: inspect.Parameter,
        option_generator: FlagsGenerator,
    ):
        self.kind = param.kind
        if param.kind == inspect.Parameter.VAR_POSITIONAL:
            self.kwargs.setdefault("nargs", "*")
        self._update(param, option_generator)

    def _update(
        self,
        param: inspect.Parameter,
        option_generator: FlagsGenerator,
    ):
        if param.default is _EMPTY:  # it will become a positional argument
            self.flags = (param.name,)
            self._update_type(param.annotation)
        else:  # it will become a flag
            self.kwargs.setdefault("dest", param.name)
            if not self.flags:
                self.flags = tuple(option_generator.generate(param.name))
            self._update_default(param.annotation, param.default)

    def _update_type(self, typ: tp.Any):
        """Update type from annotation."""
        if (typ is not _EMPTY) and (not isinstance(typ, Argument)) and ("type" not in self.kwargs):
            self.kwargs.setdefault("type", typ)
            if "action" not in self.kwargs:
                self.kwargs["action"] = TypeAction

    def _update_default(self, typ: tp.Any, default: tp.Any):
        """Update type and default externally"""
        if "default" not in self.kwargs:
            self.kwargs["default"] = default
        else:
            default = self.kwargs["default"]

        typ = self.kwargs.pop("type", typ)
        if default is not None and typ is _EMPTY:
            typ = type(default)

        if typ is bool:
            self.kwargs["action"] = "store_true" if default is False else "store_false"
        else:
            self._update_type(typ)

    def add_to(self, parser: "Arger"):
        return parser.add_argument(*self.flags, **self.kwargs)

__init__(*, type=None, metavar=None, required=None, nargs=None, const=None, choices=None, action=None, flags=(), **kwargs)

Represent positional arguments to the command that are required by default.

Analogous to ArgumentParser.add_argument

Parameters:

Name	Type	Description	Default
type	Callable[[str], T] | FileType | None	The type to which the command-line argument should be converted. Obtained from the type annotation. Use the Argument class itself if you want to pass variables to Arger.add_argument. Example: typing.cast(int, Argument(type=int)). If not passed, it is returned as a string.	None
metavar	str | None	A name for the argument in usage messages.	None
nargs	int | str | None	The number of command-line arguments that should be consumed. To be generated from the type hint. Example: Types and how they are converted to nargs: Tuple[str, ...] -> nargs='+' Tuple[str, str] -> nargs=2 List[str]|tuple|list -> nargs=* Note: Even though Tuple[str, ...] does not strictly mean "one or more", it is supported to make nargs='+' easier to add.	None
const	Any	Covered by the type hint and the given default value.	None
choices	Iterable[Any] | None	Use enum.Enum as the type hint to generate choices automatically.	None
action	str | type[Action] | None	The basic type of action to be taken when this argument is encountered at the command line.	None
flags	Sequence[str]	These are generated from the argument name. If you want to override the generated flags, you can pass them explicitly.	()
default	Any	The value produced if the argument is absent from the command line. The default value assigned to a keyword argument helps determine the type of option and action if it is not type-annotated. The default value is assigned directly to the parser's default for that option. In addition, it determines the ArgumentParser action: A default value of False implies store_true, while True implies store_false. If the default value is a list, the action is append (multiple instances of that option are permitted). Strings or None imply a store action.	required
kwargs	Any	Delegated to the ArgumentParser.add_argument method.	{}

Source code in arger/main.py

def __init__(
    self,
    *,
    type: tp.Callable[[str], tp_utils.T] | ap.FileType | None = None,
    metavar: str | None = None,
    required: bool | None = None,
    nargs: int | str | None = None,
    const: tp.Any = None,
    choices: tp.Iterable[tp.Any] | None = None,
    action: str | type[ap.Action] | None = None,
    flags: tp.Sequence[str] = (),
    **kwargs: tp.Any,
):
    """Represent positional arguments to the command that are required by default.

    Analogous to
    [ArgumentParser.add_argument](https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser.add_argument)

    Args:
        type: The type to which the command-line argument should be converted.

            Obtained from the type annotation.
            Use the `Argument` class itself if you want to pass variables to `Arger.add_argument`.

            Example: `typing.cast(int, Argument(type=int))`. If not passed, it is returned as a string.

        metavar: A name for the argument in usage messages.

        nargs: The number of command-line arguments that should be consumed.
            To be generated from the type hint.

            Example: Types and how they are converted to `nargs`:

            * `Tuple[str, ...] -> nargs='+'`
            * `Tuple[str, str] -> nargs=2`
            * `List[str]|tuple|list -> nargs=*`

            Note: Even though `Tuple[str, ...]` does not strictly mean "one or more",
            it is supported to make `nargs='+'` easier to add.

        const: Covered by the type hint and the given default value.
        choices: Use `enum.Enum` as the type hint to generate choices automatically.
        action: The basic type of action to be taken
            when this argument is encountered at the command line.

        flags: These are generated from the argument name.
            If you want to override the generated flags, you can pass them explicitly.

        default (tp.Any): The value produced if the argument is absent from the command line.

            * The default value assigned to a keyword argument helps determine
                the type of option and action if it is not type-annotated.
            * The default value is assigned directly to the parser's default for that option.
            * In addition, it determines the `ArgumentParser` action:
                * A default value of `False` implies `store_true`, while `True` implies `store_false`.
                * If the default value is a list, the action is `append`
                (multiple instances of that option are permitted).
                * Strings or `None` imply a `store` action.

        kwargs: Delegated to the `ArgumentParser.add_argument` method.
    """
    for var_name in (
        "type",
        "metavar",
        "required",
        "nargs",
        "const",
        "choices",
        "action",
    ):
        value = locals()[var_name]
        if value is not None:
            kwargs[var_name] = value
    self.flags = flags
    self.kwargs = kwargs

__repr__()

Helps during tests.

Source code in arger/main.py

def __repr__(self):
    """Helps during tests."""
    return f"<{self.__class__.__name__}: {self.flags}, {self.kwargs!r}>"