Add support for suppressing fields from CLI help. (#436)

docs/index.md

@@ -1326,6 +1326,42 @@ print(Settings().model_dump())
 #> {'my_arg': 'hi'}
 ```
 
+#### Suppressing Fields from CLI Help Text
+
+To suppress a field from the CLI help text, the `CliSuppress` annotation can be used for field types, or the
+`CLI_SUPPRESS` string constant can be used for field descriptions.
+
+```py
+import sys
+
+from pydantic import Field
+
+from pydantic_settings import CLI_SUPPRESS, BaseSettings, CliSuppress
+
+
+class Settings(BaseSettings, cli_parse_args=True):
+ """Suppress fields from CLI help text."""
+
+ field_a: CliSuppress[int] = 0
+ field_b: str = Field(default=1, description=CLI_SUPPRESS)
+
+
+try:
+ sys.argv = ['example.py', '--help']
+ Settings()
+except SystemExit as e:
+ print(e)
+ #> 0
+"""
+usage: example.py [-h]
+
+Suppress fields from CLI help text.
+
+options:
+ -h, --help show this help message and exit
+"""
+```
+
 ### Integrating with Existing Parsers
 
 A CLI settings source can be integrated with existing parsers by overriding the default CLI settings source with a user

pydantic_settings/__init__.py

@@ -1,11 +1,13 @@
 from .main import BaseSettings, CliApp, SettingsConfigDict
 from .sources import (
+ CLI_SUPPRESS,
  AzureKeyVaultSettingsSource,
  CliExplicitFlag,
  CliImplicitFlag,
  CliPositionalArg,
  CliSettingsSource,
  CliSubCommand,
+ CliSuppress,
  DotEnvSettingsSource,
  EnvSettingsSource,
  InitSettingsSource,
@@ -27,6 +29,8 @@
  'CliApp',
  'CliSettingsSource',
  'CliSubCommand',
+ 'CliSuppress',
+ 'CLI_SUPPRESS',
  'CliPositionalArg',
  'CliExplicitFlag',
  'CliImplicitFlag',

pydantic_settings/sources.py

@@ -156,6 +156,8 @@ def error(self, message: str) -> NoReturn:
 _CliBoolFlag = TypeVar('_CliBoolFlag', bound=bool)
 CliImplicitFlag = Annotated[_CliBoolFlag, _CliImplicitFlag]
 CliExplicitFlag = Annotated[_CliBoolFlag, _CliExplicitFlag]
+CLI_SUPPRESS = SUPPRESS
+CliSuppress = Annotated[T, CLI_SUPPRESS]
 
 
 def get_subcommand(
@@ -1647,7 +1649,7 @@ def _add_parser_args(
  )
  is_parser_submodel = sub_models and not is_append_action
  kwargs: dict[str, Any] = {}
- kwargs['default'] = SUPPRESS
+ kwargs['default'] = CLI_SUPPRESS
  kwargs['help'] = self._help_format(field_name, field_info, model_default)
  kwargs['metavar'] = self._metavar_format(field_info.annotation)
  kwargs['required'] = (
@@ -1816,7 +1818,7 @@ def _add_parser_alias_paths(
  else f'{arg_prefix.replace(subcommand_prefix, "", 1)}{name}'
  )
  kwargs: dict[str, Any] = {}
- kwargs['default'] = SUPPRESS
+ kwargs['default'] = CLI_SUPPRESS
  kwargs['help'] = 'pydantic alias path'
  kwargs['dest'] = f'{arg_prefix}{name}'
  if metavar == 'dict' or is_nested_alias_path:
@@ -1883,6 +1885,9 @@ def _metavar_format(self, obj: Any) -> str:
 
  def _help_format(self, field_name: str, field_info: FieldInfo, model_default: Any) -> str:
  _help = field_info.description if field_info.description else ''
+ if _help == CLI_SUPPRESS or CLI_SUPPRESS in field_info.metadata:
+ return CLI_SUPPRESS
+
  if field_info.is_required() and model_default in (PydanticUndefined, None):
  if _CliPositionalArg not in field_info.metadata:
  ifdef = 'ifdef: ' if model_default is None else ''

tests/test_source_cli.py

@@ -30,11 +30,13 @@
  SettingsConfigDict,
 )
 from pydantic_settings.sources import (
+ CLI_SUPPRESS,
  CliExplicitFlag,
  CliImplicitFlag,
  CliPositionalArg,
  CliSettingsSource,
  CliSubCommand,
+ CliSuppress,
  SettingsError,
  get_subcommand,
 )
@@ -1648,10 +1650,10 @@ def test_cli_flag_prefix_char():
  class Cfg(BaseSettings, cli_flag_prefix_char='+'):
  my_var: str = Field(validation_alias=AliasChoices('m', 'my-var'))
 
- cfg = Cfg(_cli_parse_args=['++my-var=hello'])
+ cfg = CliApp.run(Cfg, cli_args=['++my-var=hello'])
  assert cfg.model_dump() == {'my_var': 'hello'}
 
- cfg = Cfg(_cli_parse_args=['+m=hello'])
+ cfg = CliApp.run(Cfg, cli_args=['+m=hello'])
  assert cfg.model_dump() == {'my_var': 'hello'}
 
 
@@ -2017,3 +2019,24 @@ def cli_cmd(self) -> None:
  CliApp.run_subcommand(self)
 
  CliApp.run(Root, cli_args=['child', '--val=hello'])
+
+
+def test_cli_suppress(capsys, monkeypatch):
+ class Settings(BaseSettings, cli_parse_args=True):
+ field_a: CliSuppress[int] = 0
+ field_b: str = Field(default=1, description=CLI_SUPPRESS)
+
+ with monkeypatch.context() as m:
+ m.setattr(sys, 'argv', ['example.py', '--help'])
+
+ with pytest.raises(SystemExit):
+ CliApp.run(Settings)
+
+ assert (
+ capsys.readouterr().out
+ == f"""usage: example.py [-h]
+
+{ARGPARSE_OPTIONS_TEXT}:
+ -h, --help show this help message and exit
+"""
+ )