Docs now reference methods via the public ArgumentParser class instead of internal mixin classes (#901)

Author: mauvilsa

CHANGELOG.rst

@@ -15,6 +15,12 @@ paths are considered internals and can change in minor and patch releases.
 v4.49.0 (unreleased)
 --------------------
 
+Changed
+^^^^^^^
+- Docs now reference methods via the public ``ArgumentParser`` class instead of
+  internal mixin classes (`#901
+  <https://github.com/omni-us/jsonargparse/pull/901>`__).
+
 Deprecated
 ^^^^^^^^^^
 - Implicit component discovery in ``auto_cli`` (calling without a ``components``

DOCUMENTATION.rst

@@ -699,10 +699,10 @@ which would be like ``--list+ file1 --list+ file2``. Not as simple as with
 The same ``list[<path_type>]`` behavior described here will work for arguments
 automatically created from type hints in signatures, that is with
 :func:`.auto_cli`, :meth:`add_function_arguments
-<.SignatureArguments.add_function_arguments>`, :meth:`add_class_arguments
-<.SignatureArguments.add_class_arguments>`, :meth:`add_method_arguments
-<.SignatureArguments.add_method_arguments>` and :meth:`add_subclass_arguments
-<.SignatureArguments.add_subclass_arguments>`.
+<.ArgumentParser.add_function_arguments>`, :meth:`add_method_arguments
+<.ArgumentParser.add_method_arguments>`, :meth:`add_class_arguments
+<.ArgumentParser.add_class_arguments>` and :meth:`add_subclass_arguments
+<.ArgumentParser.add_subclass_arguments>`.
 
 .. note::
 
@@ -1354,7 +1354,10 @@ these are described in the docstrings. To make this well written code
 configurable, it wouldn't make sense to duplicate information of types and
 parameter descriptions. To avoid this duplication, jsonargparse includes methods
 to automatically add annotated parameters as arguments, see
-:class:`.SignatureArguments`.
+:meth:`add_function_arguments <.ArgumentParser.add_function_arguments>`,
+:meth:`add_method_arguments <.ArgumentParser.add_method_arguments>`,
+:meth:`add_class_arguments <.ArgumentParser.add_class_arguments>` and
+:meth:`add_subclass_arguments <.ArgumentParser.add_subclass_arguments>`.
 
 Take for example a class with its init and a method with docstrings as follows:
 
@@ -1406,19 +1409,19 @@ initialized and the method executed as follows:
     myclass.mymethod(**cfg.myclass.method.as_dict())
 
 
-The :meth:`add_class_arguments <.SignatureArguments.add_class_arguments>` call
-adds to the ``myclass.init`` key the ``items`` argument with description as in
-the docstring, sets it as required since it lacks a default value. When parsed,
-it is validated according to the type hint, i.e., a dict with values ints or
-list of ints. Also since the init has the ``**kwargs`` argument, the keyword
+The :meth:`add_class_arguments <.ArgumentParser.add_class_arguments>` call adds
+to the ``myclass.init`` key the ``items`` argument with description as in the
+docstring, sets it as required since it lacks a default value. When parsed, it
+is validated according to the type hint, i.e., a dict with values ints or list
+of ints. Also since the init has the ``**kwargs`` argument, the keyword
 arguments from ``MyBaseClass`` are also added to the parser. Similarly, the
-:meth:`add_method_arguments <.SignatureArguments.add_method_arguments>` call
-adds to the ``myclass.method`` key, the arguments ``value`` as a required float
-and ``flag`` as an optional boolean with default value false.
+:meth:`add_method_arguments <.ArgumentParser.add_method_arguments>` call adds to
+the ``myclass.method`` key, the arguments ``value`` as a required float and
+``flag`` as an optional boolean with default value false.
 
 
 Instantiation of several classes added with :meth:`add_class_arguments
-<.SignatureArguments.add_class_arguments>` can be done more simply for an entire
+<.ArgumentParser.add_class_arguments>` can be done more simply for an entire
 config object using :meth:`instantiate <.ArgumentParser.instantiate>`. For the
 example above running ``cfg = parser.instantiate(cfg)`` would result in
 ``cfg.myclass.init`` containing an instance of ``MyClass`` initialized with
@@ -1889,7 +1892,7 @@ example from the standard library would be:
     Namespace(uniform=Namespace(a=0.7, b=3.4))
 
 Without the stubs resolver, the :meth:`add_function_arguments
-<.SignatureArguments.add_function_arguments>` call requires the
+<.ArgumentParser.add_function_arguments>` call requires the
 ``fail_untyped=False`` option. This has the disadvantage that type ``Any`` is
 given to the ``a`` and ``b`` arguments, instead of ``float``. And this means
 that the parser would not fail if given an invalid value, for instance a string.
@@ -1938,8 +1941,8 @@ with all nested subclasses instantiated, the :meth:`instantiate
 
 In addition to using a class as type hint in signatures, for low level
 construction of parsers, there are also the methods :meth:`add_class_arguments
-<.SignatureArguments.add_class_arguments>` and :meth:`add_subclass_arguments
-<.SignatureArguments.add_subclass_arguments>`. These methods accept a ``skip``
+<.ArgumentParser.add_class_arguments>` and :meth:`add_subclass_arguments
+<.ArgumentParser.add_subclass_arguments>`. These methods accept a ``skip``
 argument that can be used to exclude parameters within subclasses. This is done
 by giving its relative destination key, i.e. as ``param.init_args.subparam``. An
 individual argument can also be added using a class as type, i.e.
@@ -2001,10 +2004,9 @@ But a subclass of ``Calendar`` with an extended set of init parameters would
 also work.
 
 If the previous example were changed to use :meth:`add_subclass_arguments
-<.SignatureArguments.add_subclass_arguments>` instead of
-:meth:`add_class_arguments <.SignatureArguments.add_class_arguments>`, then
-subclasses ``MyClass`` would also be accepted. In this case the config would be
-like:
+<.ArgumentParser.add_subclass_arguments>` instead of :meth:`add_class_arguments
+<.ArgumentParser.add_class_arguments>`, then subclasses ``MyClass`` would also
+be accepted. In this case the config would be like:
 
 .. code-block:: yaml
 
@@ -2410,7 +2412,7 @@ Argument linking
 Some use cases could require adding arguments from multiple classes and some
 parameters get a value automatically computed from other arguments. This
 behavior can be obtained by using the :meth:`link_arguments
-<.ArgumentLinking.link_arguments>` parser method.
+<.ArgumentParser.link_arguments>` parser method.
 
 There are two types of links, defined with ``apply_on='parse'`` or
 ``apply_on='instantiate'``. As the names suggest, the former are set when
@@ -2474,8 +2476,8 @@ Applied on instantiate
 ----------------------
 
 For instantiation links, sources can be class groups (added with
-:meth:`add_class_arguments <.SignatureArguments.add_class_arguments>`) or
-subclass arguments (see :ref:`sub-classes`). The source key can be the entire
+:meth:`add_class_arguments <.ArgumentParser.add_class_arguments>`) or subclass
+arguments (see :ref:`sub-classes`). The source key can be the entire
 instantiated object or an attribute of the object. The target key has to be a
 single argument and can be inside init_args of a subclass. The order of
 instantiation used by :meth:`instantiate <.ArgumentParser.instantiate>` is

jsonargparse/__init__.py

@@ -20,11 +20,9 @@
 from ._instantiation import *  # noqa: F403
 from ._jsonnet import *  # noqa: F403
 from ._jsonschema import *  # noqa: F403
-from ._link_arguments import *  # noqa: F403
 from ._loaders_dumpers import *  # noqa: F403
 from ._namespace import *  # noqa: F403
 from ._paths import Path  # noqa: F401
-from ._signatures import *  # noqa: F403
 from ._subcommands import *  # noqa: F403
 from ._util import *  # noqa: F403
 from .typing import class_from_function, lazy_instance  # noqa: F401
@@ -51,19 +49,15 @@
     _instantiation,
     _jsonnet,
     _jsonschema,
-    _link_arguments,
     _loaders_dumpers,
     _namespace,
-    _signatures,
     _subcommands,
     _util,
 )
 
 __all__ += _cli.__all__
 __all__ += _core.__all__
-__all__ += _signatures.__all__
 __all__ += _from_config.__all__
-__all__ += _link_arguments.__all__
 __all__ += _subcommands.__all__
 __all__ += _jsonschema.__all__
 __all__ += _jsonnet.__all__

jsonargparse/_core.py

@@ -26,7 +26,6 @@
     previous_config,
 )
 from ._common import (
-    LoggerProperty,
     debug_mode_active,
     get_optionals_as_positionals_actions,
     is_subclasses_disabled,
@@ -41,7 +40,7 @@
 )
 from ._deprecated import ParserDeprecations, deprecated_skip_check, deprecated_yaml_comments
 from ._formatters import DefaultHelpFormatter, get_env_var
-from ._instantiation import get_class_instantiators
+from ._instantiation import InstantiateMethod
 from ._jsonnet import ActionJsonnet
 from ._jsonschema import ActionJsonSchema
 from ._link_arguments import ActionLink, ArgumentLinking
@@ -56,12 +55,10 @@
     Namespace,
     NSKeyError,
     get_non_meta_sorted_keys,
-    get_value_and_parent,
     is_meta_key,
     patch_namespace,
     recreate_branches,
     remove_meta,
-    split_key,
     split_key_leaf,
     split_key_root,
 )
@@ -102,13 +99,13 @@
     return_parser_if_captured,
 )
 
-__all__ = ["ArgumentParser", "ActionsContainer"]
+__all__ = ["ArgumentParser"]
 
 
 _parse_known_has_intermixed = "intermixed" in inspect.signature(argparse.ArgumentParser._parse_known_args).parameters
 
 
-class ActionsContainer(SignatureArguments, argparse._ActionsContainer):
+class ActionsContainer(ArgumentLinking, InstantiateMethod, SignatureArguments, argparse._ActionsContainer):
     """Extension of ``argparse._ActionsContainer`` to support additional functionalities."""
 
     _action_groups: Sequence["ArgumentGroup"]  # type: ignore[assignment]
@@ -229,7 +226,7 @@ class ArgumentGroup(ActionsContainer, argparse._ArgumentGroup):
     parser: Optional[Union["ArgumentParser", ActionsContainer]] = None
 
 
-class ArgumentParser(ParserDeprecations, ActionsContainer, ArgumentLinking, LoggerProperty, argparse.ArgumentParser):
+class ArgumentParser(ParserDeprecations, ActionsContainer, argparse.ArgumentParser):
     """Parser for command line, configuration files and environment variables."""
 
     formatter_class: type[argparse.HelpFormatter]
@@ -287,10 +284,6 @@ def __init__(
 
     ## Parsing methods ##
 
-    def parse_known_args(self, *args, **kwargs) -> NoReturn:
-        """Raises ``NotImplementedError``, not supported since typos in configs would go unnoticed."""
-        raise NotImplementedError("parse_known_args not supported because typos in configs would go unnoticed.")
-
     def _parse_known_args_internal(self, args=None, namespace=None, *, argcomplete: bool = False):
         if argcomplete:
             namespace = get_argcomplete_namespace(self, namespace)
@@ -716,9 +709,13 @@ def _load_config_parser_mode(
 
     ## Methods for adding to the parser ##
 
-    def add_subparsers(self, *args, **kwargs) -> NoReturn:
-        """Raises a ``NotImplementedError`` since jsonargparse uses ``add_subcommands``."""
-        raise NotImplementedError("In jsonargparse subcommands are added using the add_subcommands method.")
+    add_argument = ActionsContainer.add_argument
+    add_argument_group = ActionsContainer.add_argument_group
+    add_function_arguments = SignatureArguments.add_function_arguments
+    add_method_arguments = SignatureArguments.add_method_arguments
+    add_class_arguments = SignatureArguments.add_class_arguments
+    add_subclass_arguments = SignatureArguments.add_subclass_arguments
+    link_arguments = ArgumentLinking.link_arguments
 
     def add_subcommands(self, required: bool = True, dest: str = "subcommand", **kwargs) -> ActionSubCommands:
         """Adds subcommand parsers to the ArgumentParser.
@@ -1064,6 +1061,8 @@ def get_defaults(self, skip_validation: bool = False, **kwargs) -> Namespace:
 
         return cfg
 
+    set_defaults = ActionsContainer.set_defaults
+
     ## Completion script methods ##
 
     def _raise_invalidated_by_completion_script(self, *args, **kwargs) -> NoReturn:
@@ -1202,94 +1201,7 @@ def check_values(cfg):
         if not skip_required and not lenient_check.get():
             check_required(cfg, self, prefix)
 
-    def instantiate(
-        self,
-        cfg: Namespace,
-        instantiate_groups: bool = True,
-    ) -> Namespace:
-        """Instantiates all signature components in a configuration namespace.
-
-        Processes the configuration recursively, converting each signature
-        component registered with the parser into its corresponding Python
-        object:
-
-        - **Class/subclass type arguments** (``add_argument`` with a class type
-          or ``add_class_arguments``/``add_subclass_arguments``): An object with
-          ``class_path`` and optionally ``init_args`` is replaced by an instance
-          of the referenced class, created by calling
-          ``class_type(**init_args)``. For the case of classes with disabled
-          subclasses, the namespace can have directly the init args without the
-          ``class_path`` + ``init_args`` wrapper.
-
-        - **Callable type arguments**: A dot-import string pointing to a
-          function or method is resolved to the callable object. When
-          ``class_path``/``init_args`` is given instead and the class
-          instantiates into a callable (or is a subclass of the callable's
-          return type), the result is either a class instance or — when not all
-          call arguments are provided yet — a :func:`functools.partial` bound to
-          the given ``init_args``.
-
-        - **Instantiation order**: Components are processed in the order
-          determined by argument links applied on instantiation.
-
-        Args:
-            cfg: The configuration object to use. Must have been produced by
-                one of the ``parse_*`` methods and not modified in a way that
-                breaks the structure expected by the parser.
-            instantiate_groups: Whether class groups should be instantiated.
-
-        Returns:
-            A new configuration object where every registered signature
-            component has been replaced by its corresponding Python object.
-        """
-        components: list[Union[ActionTypeHint, _ActionConfigLoad, ArgumentGroup]] = []
-        for action in filter_non_parsing_actions(self._actions):
-            if isinstance(action, ActionTypeHint):
-                components.append(action)
-            elif isinstance(action, ActionLink) and isinstance(action.target[1], ActionTypeHint):
-                components.append(action.target[1])
-
-        if instantiate_groups:
-            skip = {c.dest for c in components}
-            groups = [g for g in self._action_groups if hasattr(g, "instantiate_class") and g.dest not in skip]
-            components.extend(groups)
-
-        components.sort(key=lambda x: -len(split_key(x.dest)))  # type: ignore[arg-type]
-        order = ActionLink.instantiation_order(self)
-        components = ActionLink.reorder(order, components)
-
-        cfg = cfg.clone(with_meta=False)
-        for component in components:
-            ActionLink.apply_instantiation_links(self, cfg, target=component.dest)
-            if isinstance(component, ActionTypeHint):
-                try:
-                    value, parent, key = get_value_and_parent(cfg, component.dest)
-                except (KeyError, AttributeError):
-                    pass
-                else:
-                    if value is not None:
-                        with parser_context(
-                            parent_parser=self,
-                            nested_links=ActionLink.get_nested_links(self, component),
-                            class_instantiators=get_class_instantiators(self),
-                            applied_instantiation_links=cfg.get("__applied_instantiation_links__"),
-                        ):
-                            parent[key] = component.instantiate_classes(value)
-            else:
-                with parser_context(
-                    load_value_mode=self.parser_mode,
-                    class_instantiators=get_class_instantiators(self),
-                    applied_instantiation_links=cfg.get("__applied_instantiation_links__"),
-                ):
-                    component.instantiate_class(component, cfg)
-
-        ActionLink.apply_instantiation_links(self, cfg, order=order)
-
-        subcommand, subparser = get_subcommand(self, cfg, fail_no_subcommand=False)
-        if subcommand is not None and subparser is not None:
-            cfg[subcommand] = subparser.instantiate(cfg[subcommand], instantiate_groups=instantiate_groups)
-
-        return cfg
+    instantiate = InstantiateMethod.instantiate
 
     def strip_unknown(self, cfg: Namespace) -> Namespace:
         """Removes all unknown keys from a configuration object.
@@ -1623,6 +1535,16 @@ def dump_header(self, dump_header: Optional[list[str]]):
             raise ValueError("Expected dump_header to be None or a list of strings.")
         self._dump_header = dump_header
 
+    # Not supported methods
+
+    def parse_known_args(self, *args, **kwargs) -> NoReturn:
+        """Raises ``NotImplementedError`` since typos in configs would go unnoticed."""
+        raise NotImplementedError("parse_known_args not supported because typos in configs would go unnoticed.")
+
+    def add_subparsers(self, *args, **kwargs) -> NoReturn:
+        """Raises ``NotImplementedError`` since jsonargparse uses ``add_subcommands``."""
+        raise NotImplementedError("In jsonargparse subcommands are added using the add_subcommands method.")
+
 
 from ._deprecated import parse_as_dict_patch  # noqa: E402