CLI Improve Docstring Help Text (#359)

Co-authored-by: Hasan Ramezani <[email protected]>

Author: kschwab

docs/index.md

@@ -1120,7 +1120,7 @@ parser methods that can be customised, along with their argparse counterparts (t
 * `add_argument_group_method` - (`argparse.ArgumentParser.add_argument_group`)
 * `add_parser_method` - (`argparse._SubParsersAction.add_parser`)
 * `add_subparsers_method` - (`argparse.ArgumentParser.add_subparsers`)
-* `formatter_class` - (`argparse.HelpFormatter`)
+* `formatter_class` - (`argparse.RawDescriptionHelpFormatter`)
 
 For a non-argparse parser the parser methods can be set to `None` if not supported. The CLI settings will only raise an
 error when connecting to the root parser if a parser method is necessary but set to `None`.

pydantic_settings/sources.py

@@ -8,11 +8,12 @@
 import typing
 import warnings
 from abc import ABC, abstractmethod
-from argparse import SUPPRESS, ArgumentParser, HelpFormatter, Namespace, _SubParsersAction
+from argparse import SUPPRESS, ArgumentParser, Namespace, RawDescriptionHelpFormatter, _SubParsersAction
 from collections import deque
 from dataclasses import is_dataclass
 from enum import Enum
 from pathlib import Path
+from textwrap import dedent
 from types import FunctionType
 from typing import (
     TYPE_CHECKING,
@@ -916,7 +917,7 @@ class CliSettingsSource(EnvSettingsSource, Generic[T]):
             Defaults to `argparse._SubParsersAction.add_parser`.
         add_subparsers_method: The root parser add subparsers (sub-commands) method.
             Defaults to `argparse.ArgumentParser.add_subparsers`.
-        formatter_class: A class for customizing the root parser help text. Defaults to `argparse.HelpFormatter`.
+        formatter_class: A class for customizing the root parser help text. Defaults to `argparse.RawDescriptionHelpFormatter`.
     """
 
     def __init__(
@@ -938,7 +939,7 @@ def __init__(
         add_argument_group_method: Callable[..., Any] | None = ArgumentParser.add_argument_group,
         add_parser_method: Callable[..., Any] | None = _SubParsersAction.add_parser,
         add_subparsers_method: Callable[..., Any] | None = ArgumentParser.add_subparsers,
-        formatter_class: Any = HelpFormatter,
+        formatter_class: Any = RawDescriptionHelpFormatter,
     ) -> None:
         self.cli_prog_name = (
             cli_prog_name if cli_prog_name is not None else settings_cls.model_config.get('cli_prog_name', sys.argv[0])
@@ -990,7 +991,10 @@ def __init__(
 
         root_parser = (
             _CliInternalArgParser(
-                cli_exit_on_error=self.cli_exit_on_error, prog=self.cli_prog_name, description=settings_cls.__doc__
+                cli_exit_on_error=self.cli_exit_on_error,
+                prog=self.cli_prog_name,
+                description=None if settings_cls.__doc__ is None else dedent(settings_cls.__doc__),
+                formatter_class=formatter_class,
             )
             if root_parser is None
             else root_parser
@@ -1359,7 +1363,7 @@ def _connect_root_parser(
         add_argument_group_method: Callable[..., Any] | None = ArgumentParser.add_argument_group,
         add_parser_method: Callable[..., Any] | None = _SubParsersAction.add_parser,
         add_subparsers_method: Callable[..., Any] | None = ArgumentParser.add_subparsers,
-        formatter_class: Any = HelpFormatter,
+        formatter_class: Any = RawDescriptionHelpFormatter,
     ) -> None:
         self._root_parser = root_parser
         self._parse_args = self._connect_parser_method(parse_args_method, 'parsed_args_method')
@@ -1413,7 +1417,7 @@ def _add_parser_args(
                         field_name,
                         help=field_info.description,
                         formatter_class=self._formatter_class,
-                        description=model.__doc__,
+                        description=None if model.__doc__ is None else dedent(model.__doc__),
                     ),
                     model=model,
                     added_args=[],
@@ -1505,7 +1509,9 @@ def _add_parser_submodels(
         model_group_kwargs: dict[str, Any] = {}
         model_group_kwargs['title'] = f'{arg_names[0]} options'
         model_group_kwargs['description'] = (
-            sub_models[0].__doc__
+            None
+            if sub_models[0].__doc__ is None
+            else dedent(sub_models[0].__doc__)
             if self.cli_use_class_docs_for_groups and len(sub_models) == 1
             else field_info.description
         )

tests/test_settings.py

@@ -2411,27 +2411,61 @@ class Cfg(BaseSettings):
 
 
 def test_cli_help_string_format(capsys, monkeypatch):
-    class Cfg(BaseSettings):
+    class Cfg(BaseSettings, cli_parse_args=True):
         date_str: str = '%Y-%m-%d'
 
-    argparse_options_text = 'options' if sys.version_info >= (3, 10) else 'optional arguments'
+    class MultilineDoc(BaseSettings, cli_parse_args=True):
+        """
+        My
+        Multiline
+        Doc
+        """
 
     with monkeypatch.context() as m:
         m.setattr(sys, 'argv', ['example.py', '--help'])
 
         with pytest.raises(SystemExit):
-            Cfg(_cli_parse_args=True)
+            Cfg()
 
         assert (
             re.sub(r'0x\w+', '0xffffffff', capsys.readouterr().out, flags=re.MULTILINE)
             == f"""usage: example.py [-h] [--date_str str]
 
-{argparse_options_text}:
+{ARGPARSE_OPTIONS_TEXT}:
   -h, --help      show this help message and exit
   --date_str str  (default: %Y-%m-%d)
 """
         )
 
+        with pytest.raises(SystemExit):
+            MultilineDoc()
+        assert (
+            capsys.readouterr().out
+            == f"""usage: example.py [-h]
+
+My
+Multiline
+Doc
+
+{ARGPARSE_OPTIONS_TEXT}:
+  -h, --help  show this help message and exit
+"""
+        )
+
+        with pytest.raises(SystemExit):
+            cli_settings_source = CliSettingsSource(MultilineDoc, formatter_class=argparse.HelpFormatter)
+            MultilineDoc(_cli_settings_source=cli_settings_source(args=True))
+        assert (
+            capsys.readouterr().out
+            == f"""usage: example.py [-h]
+
+My Multiline Doc
+
+{ARGPARSE_OPTIONS_TEXT}:
+  -h, --help  show this help message and exit
+"""
+        )
+
 
 def test_cli_nested_dataclass_arg():
     @pydantic_dataclasses.dataclass