Skip to content

Commit 39e551c

Browse files
hramezaniclaude
andauthored
Fix CLI descriptions lost under python -OO by falling back to json_schema_extra (#843)
Co-authored-by: Claude Opus 4.6 (1M context) <[email protected]>
1 parent 9ed7f48 commit 39e551c

2 files changed

Lines changed: 256 additions & 6 deletions

File tree

‎pydantic_settings/sources/providers/cli.py‎

Lines changed: 37 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,39 @@ class CliMutuallyExclusiveGroup(BaseModel):
9090
pass
9191

9292

93+
def _get_model_description(model_cls: type[Any]) -> str | None:
94+
"""Get model description from json_schema_extra or __doc__ fallback.
95+
96+
``json_schema_extra.description`` takes precedence over ``__doc__`` to
97+
match pydantic's own behaviour. When neither is available (e.g. under
98+
``python -OO`` where docstrings are stripped), returns ``None``.
99+
"""
100+
config: Any = {}
101+
if is_model_class(model_cls):
102+
config = model_cls.model_config
103+
elif is_pydantic_dataclass(model_cls):
104+
config = getattr(model_cls, '__pydantic_config__', {})
105+
json_schema_extra = config.get('json_schema_extra')
106+
if isinstance(json_schema_extra, dict):
107+
desc = json_schema_extra.get('description')
108+
if desc is not None:
109+
return desc
110+
elif callable(json_schema_extra):
111+
try:
112+
desc = None
113+
if is_model_class(model_cls):
114+
desc = model_cls.model_json_schema().get('description')
115+
elif is_pydantic_dataclass(model_cls):
116+
desc = TypeAdapter(model_cls).json_schema().get('description')
117+
if desc is not None:
118+
return desc
119+
except Exception:
120+
pass
121+
if model_cls.__doc__ is not None:
122+
return dedent(model_cls.__doc__)
123+
return None
124+
125+
93126
def _collect_sub_models(type_: Any, sub_models: list[type[BaseModel]]) -> None:
94127
"""Recursively collect BaseModel subclasses from possibly nested union types."""
95128
stripped = _strip_annotated(type_)
@@ -418,7 +451,7 @@ def __init__(
418451
_CliInternalArgParser(
419452
cli_exit_on_error=self.cli_exit_on_error,
420453
prog=self.cli_prog_name,
421-
description=None if settings_cls.__doc__ is None else dedent(settings_cls.__doc__),
454+
description=_get_model_description(settings_cls),
422455
formatter_class=formatter_class,
423456
prefix_chars=self.cli_flag_prefix_char,
424457
allow_abbrev=False,
@@ -1024,12 +1057,10 @@ def _add_parser_args(
10241057
subcommand_arg.args = [subcommand_alias]
10251058
subcommand_arg.kwargs['allow_abbrev'] = False
10261059
subcommand_arg.kwargs['formatter_class'] = self._formatter_class
1027-
subcommand_arg.kwargs['description'] = (
1028-
None if sub_model.__doc__ is None else dedent(sub_model.__doc__)
1029-
)
1060+
subcommand_arg.kwargs['description'] = _get_model_description(sub_model)
10301061
subcommand_arg.kwargs['help'] = None if len(arg.sub_models) > 1 else field_info.description
10311062
if self.cli_use_class_docs_for_groups:
1032-
subcommand_arg.kwargs['help'] = None if sub_model.__doc__ is None else dedent(sub_model.__doc__)
1063+
subcommand_arg.kwargs['help'] = _get_model_description(sub_model)
10331064

10341065
subparsers = (
10351066
self._add_subparsers(
@@ -1258,7 +1289,7 @@ def _add_parser_submodels(
12581289
if model_group_kwargs['_is_cli_mutually_exclusive_group'] and len(sub_models) > 1:
12591290
raise SettingsError('cannot use union with CliMutuallyExclusiveGroup')
12601291
if self.cli_use_class_docs_for_groups and len(sub_models) == 1:
1261-
model_group_kwargs['description'] = None if sub_models[0].__doc__ is None else dedent(sub_models[0].__doc__)
1292+
model_group_kwargs['description'] = _get_model_description(sub_models[0])
12621293

12631294
if model_default is not PydanticUndefined:
12641295
if is_model_class(type(model_default)) or is_pydantic_dataclass(type(model_default)):

‎tests/test_source_cli.py‎

Lines changed: 219 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,7 @@
5555
CliUnknownArgs,
5656
get_subcommand,
5757
)
58+
from pydantic_settings.sources.providers.cli import _get_model_description
5859

5960
ARGPARSE_OPTIONS_TEXT = 'options' if sys.version_info >= (3, 10) else 'optional arguments'
6061

@@ -3554,3 +3555,221 @@ def cli_cmd(self) -> None:
35543555
'baz': {'name': 'Hello world'},
35553556
},
35563557
}
3558+
3559+
3560+
def test_get_model_description_returns_docstring():
3561+
class MyModel(BaseModel):
3562+
"""My docstring."""
3563+
3564+
assert _get_model_description(MyModel) == 'My docstring.'
3565+
3566+
3567+
def test_get_model_description_returns_none_when_no_doc_and_no_schema_extra():
3568+
class MyModel(BaseModel):
3569+
pass
3570+
3571+
assert MyModel.__doc__ is None
3572+
assert _get_model_description(MyModel) is None
3573+
3574+
3575+
def test_get_model_description_json_schema_extra_fallback():
3576+
class MyModel(BaseModel):
3577+
model_config = ConfigDict(json_schema_extra={'description': 'Schema description.'})
3578+
3579+
MyModel.__doc__ = None # type: ignore
3580+
assert _get_model_description(MyModel) == 'Schema description.'
3581+
3582+
3583+
def test_get_model_description_schema_takes_precedence():
3584+
class MyModel(BaseModel):
3585+
"""Docstring description."""
3586+
3587+
model_config = ConfigDict(json_schema_extra={'description': 'Schema wins.'})
3588+
3589+
assert _get_model_description(MyModel) == 'Schema wins.'
3590+
3591+
3592+
def test_get_model_description_callable_json_schema_extra():
3593+
def add_description(schema: dict) -> None:
3594+
schema['description'] = 'From callable.'
3595+
3596+
class MyModel(BaseModel):
3597+
model_config = ConfigDict(json_schema_extra=add_description)
3598+
3599+
MyModel.__doc__ = None # type: ignore
3600+
assert _get_model_description(MyModel) == 'From callable.'
3601+
3602+
3603+
def test_get_model_description_dict_without_description_falls_back_to_doc():
3604+
class MyModel(BaseModel):
3605+
"""Docstring fallback."""
3606+
3607+
model_config = ConfigDict(json_schema_extra={'title': 'No description key here'})
3608+
3609+
assert _get_model_description(MyModel) == 'Docstring fallback.'
3610+
3611+
3612+
def test_get_model_description_callable_json_schema_extra_pydantic_dataclass():
3613+
def add_description(schema: dict) -> None:
3614+
schema['description'] = 'DC callable.'
3615+
3616+
@pydantic_dataclasses.dataclass(config=ConfigDict(json_schema_extra=add_description))
3617+
class MyDC:
3618+
x: int = 1
3619+
3620+
MyDC.__doc__ = None # type: ignore
3621+
assert _get_model_description(MyDC) == 'DC callable.'
3622+
3623+
3624+
def test_get_model_description_pydantic_dataclass():
3625+
@pydantic_dataclasses.dataclass(config=ConfigDict(json_schema_extra={'description': 'DC description.'}))
3626+
class MyDC:
3627+
x: int = 1
3628+
3629+
MyDC.__doc__ = None # type: ignore
3630+
assert _get_model_description(MyDC) == 'DC description.'
3631+
3632+
3633+
def test_get_model_description_base_settings():
3634+
class MySettings(BaseSettings):
3635+
model_config = SettingsConfigDict(json_schema_extra={'description': 'Settings description.'})
3636+
3637+
MySettings.__doc__ = None # type: ignore
3638+
assert _get_model_description(MySettings) == 'Settings description.'
3639+
3640+
3641+
def test_cli_json_schema_extra_description_fallback(capsys, monkeypatch):
3642+
"""Root parser uses json_schema_extra description when __doc__ is None (simulating python -OO)."""
3643+
3644+
class Settings(BaseSettings, cli_prog_name='example.py'):
3645+
"""This docstring will be removed."""
3646+
3647+
model_config = SettingsConfigDict(
3648+
cli_parse_args=True,
3649+
json_schema_extra={'description': 'JSON schema description.'},
3650+
)
3651+
my_var: str = 'default'
3652+
3653+
Settings.__doc__ = None # type: ignore
3654+
3655+
with monkeypatch.context() as m:
3656+
m.setattr(sys, 'argv', ['example.py', '--help'])
3657+
3658+
with pytest.raises(SystemExit):
3659+
Settings()
3660+
3661+
assert (
3662+
capsys.readouterr().out
3663+
== f"""usage: example.py [-h] [--my_var str]
3664+
3665+
JSON schema description.
3666+
3667+
{ARGPARSE_OPTIONS_TEXT}:
3668+
-h, --help show this help message and exit
3669+
--my_var str (default: default)
3670+
"""
3671+
)
3672+
3673+
3674+
def test_cli_json_schema_extra_takes_precedence_over_docstring(capsys, monkeypatch):
3675+
"""Even when __doc__ is available, json_schema_extra description should be used, instead."""
3676+
3677+
class Settings(BaseSettings, cli_prog_name='example.py'):
3678+
"""Docstring description."""
3679+
3680+
model_config = SettingsConfigDict(
3681+
cli_parse_args=True,
3682+
json_schema_extra={'description': 'JSON schema description.'},
3683+
)
3684+
my_var: str = 'default'
3685+
3686+
with monkeypatch.context() as m:
3687+
m.setattr(sys, 'argv', ['example.py', '--help'])
3688+
3689+
with pytest.raises(SystemExit):
3690+
Settings()
3691+
3692+
assert (
3693+
capsys.readouterr().out
3694+
== f"""usage: example.py [-h] [--my_var str]
3695+
3696+
JSON schema description.
3697+
3698+
{ARGPARSE_OPTIONS_TEXT}:
3699+
-h, --help show this help message and exit
3700+
--my_var str (default: default)
3701+
"""
3702+
)
3703+
3704+
3705+
def test_cli_use_class_docs_for_groups_json_schema_extra_fallback(capsys, monkeypatch):
3706+
"""cli_use_class_docs_for_groups falls back to json_schema_extra when __doc__ is None."""
3707+
3708+
class SubModel(BaseModel):
3709+
"""This docstring will be removed."""
3710+
3711+
model_config = ConfigDict(json_schema_extra={'description': 'Sub model schema description.'})
3712+
v1: int
3713+
3714+
SubModel.__doc__ = None # type: ignore
3715+
3716+
class Settings(BaseSettings, cli_prog_name='example.py'):
3717+
"""My application help text."""
3718+
3719+
sub_model: SubModel = Field(description='The field description')
3720+
model_config = SettingsConfigDict(cli_parse_args=True)
3721+
3722+
with monkeypatch.context() as m:
3723+
m.setattr(sys, 'argv', ['example.py', '--help'])
3724+
3725+
with pytest.raises(SystemExit):
3726+
Settings(_cli_use_class_docs_for_groups=True)
3727+
3728+
assert (
3729+
capsys.readouterr().out
3730+
== f"""usage: example.py [-h] [--sub_model [JSON]] [--sub_model.v1 int]
3731+
3732+
My application help text.
3733+
3734+
{ARGPARSE_OPTIONS_TEXT}:
3735+
-h, --help show this help message and exit
3736+
3737+
sub_model options:
3738+
Sub model schema description.
3739+
3740+
--sub_model [JSON] set sub_model from JSON string (default: {{}})
3741+
--sub_model.v1 int (required)
3742+
"""
3743+
)
3744+
3745+
3746+
def test_cli_subcommand_json_schema_extra_description_fallback(capsys):
3747+
"""Subcommand parser uses json_schema_extra description when __doc__ is None."""
3748+
3749+
class SubCmd(BaseSettings):
3750+
"""This docstring will be removed."""
3751+
3752+
model_config = SettingsConfigDict(json_schema_extra={'description': 'Subcommand schema description.'})
3753+
x: int = 1
3754+
3755+
SubCmd.__doc__ = None # type: ignore
3756+
3757+
class Root(BaseSettings, cli_prog_name='example.py'):
3758+
"""Root help."""
3759+
3760+
sub: CliSubCommand[SubCmd]
3761+
3762+
with pytest.raises(SystemExit):
3763+
CliApp.run(Root, cli_args=['sub', '--help'])
3764+
3765+
assert (
3766+
capsys.readouterr().out
3767+
== f"""usage: example.py sub [-h] [-x int]
3768+
3769+
Subcommand schema description.
3770+
3771+
{ARGPARSE_OPTIONS_TEXT}:
3772+
-h, --help show this help message and exit
3773+
-x int (default: 1)
3774+
"""
3775+
)

0 commit comments

Comments
 (0)