New auto_parser function for convenience and more visibility of the capture_parser feature (#721)

Author: mauvilsa

CHANGELOG.rst

@@ -15,6 +15,12 @@ paths are considered internals and can change in minor and patch releases.
 v4.40.0 (2025-05-??)
 --------------------
 
+Added
+^^^^^
+- New ``auto_parser`` function for convenience and more visibility of the
+  ``capture_parser`` feature (`#721
+  <https://github.com/omni-us/jsonargparse/pull/721>`__).
+
 Fixed
 ^^^^^
 - ``set_parsing_settings(validate_defaults=True)`` fails when the parser has a

DOCUMENTATION.rst

@@ -329,7 +329,8 @@ This can be easily implemented with :func:`.capture_parser` as follows:
 .. note::
 
     The official way to obtain the parser for command line tools based on
-    :func:`.auto_cli` is by using :func:`.capture_parser`.
+    :func:`.auto_cli` is by using :func:`.auto_parser`, which is just a
+    convenience function that calls :func:`.capture_parser`.
 
 
 Optionals as positionals

README.rst

@@ -27,6 +27,49 @@ a `substantial user base
 it serves as the framework behind pytorch-lightning's `LightningCLI
 <https://lightning.ai/docs/pytorch/stable/cli/lightning_cli.html>`__.
 
+Teaser examples
+---------------
+
+CLI with minimal boilerplate:
+
+.. code-block:: python
+
+    from jsonargparse import auto_cli
+
+    def main_function(...):  # your main parameters and logic here
+        ...
+
+    if __name__ == "__main__":
+        auto_cli(main_function)  # parses arguments and runs main_function
+
+Minimal boilerplate but manually parsing:
+
+.. code-block:: python
+
+    from jsonargparse import auto_parser
+
+    ...
+
+    if __name__ == "__main__":
+        parser = auto_parser(main_function)
+        cfg = parser.parse_args()
+        ...
+
+Powerful argparse-like low level parsers:
+
+.. code-block:: python
+
+    from typing import Union, Literal
+    from jsonargparse import ArgumentParser
+
+    parser = ArgumentParser()
+    parser.add_argument("--config", action="config")  # support config files
+    parser.add_argument("--opt", type=Union[int, Literal["off"])  # complex arguments via type hints
+    parser.add_function_arguments(main_function, "function")  # add entire function signatures
+    ...
+    cfg = parser.parse_args()
+    ...
+
 
 Features
 --------

jsonargparse/_cli.py

@@ -8,9 +8,13 @@
 from ._deprecated import deprecation_warning_cli_return_parser
 from ._namespace import Namespace, dict_to_namespace
 from ._optionals import get_doc_short_description
-from ._util import default_config_option_help
+from ._util import capture_parser, default_config_option_help
 
-__all__ = ["CLI", "auto_cli"]
+__all__ = [
+    "CLI",
+    "auto_cli",
+    "auto_parser",
+]
 
 
 ComponentType = Union[Callable, Type]
@@ -125,6 +129,14 @@ def auto_cli(
     return _run_component(component, init.get(subcommand))
 
 
+def auto_parser(*args, **kwargs) -> ArgumentParser:
+    """Same as auto_cli, but returns the parser, so doesn't parse arguments or run.
+
+    This is a shorthand for ``capture_parser(lambda: auto_cli(*args, **kwargs))``.
+    """
+    return capture_parser(lambda: auto_cli(*args, **kwargs))
+
+
 def get_help_str(component, logger):
     if isinstance(component, dict):
         return component.get("_help")

jsonargparse_tests/test_cli.py

@@ -15,7 +15,8 @@
 
 import pytest
 
-from jsonargparse import CLI, auto_cli, capture_parser, lazy_instance
+from jsonargparse import CLI, auto_cli, auto_parser, capture_parser, lazy_instance
+from jsonargparse._namespace import Namespace
 from jsonargparse._optionals import docstring_parser_support, ruyaml_support
 from jsonargparse.typing import final
 from jsonargparse_tests.conftest import json_or_yaml_dump, json_or_yaml_load, skip_if_docstring_parser_unavailable
@@ -28,6 +29,15 @@ def get_cli_stdout(*args, **kwargs) -> str:
     return out.getvalue()
 
 
+def simple_main(a1: int = 0, a2: bool = False):
+    pass
+
+
+def test_auto_parser():
+    parser = auto_parser(simple_main)
+    assert parser.parse_args([]) == Namespace(config=None, a1=0, a2=False)
+
+
 # failure cases