|
55 | 55 | CliUnknownArgs, |
56 | 56 | get_subcommand, |
57 | 57 | ) |
| 58 | +from pydantic_settings.sources.providers.cli import _get_model_description |
58 | 59 |
|
59 | 60 | ARGPARSE_OPTIONS_TEXT = 'options' if sys.version_info >= (3, 10) else 'optional arguments' |
60 | 61 |
|
@@ -3554,3 +3555,221 @@ def cli_cmd(self) -> None: |
3554 | 3555 | 'baz': {'name': 'Hello world'}, |
3555 | 3556 | }, |
3556 | 3557 | } |
| 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