Add CLI Settings Source

pydantic_settings/__init__.py

@@ -1,5 +1,8 @@
 from .main import BaseSettings, SettingsConfigDict
 from .sources import (
+    CliPositionalArg,
+    CliSettingsSource,
+    CliSubCommand,
     DotEnvSettingsSource,
     EnvSettingsSource,
     InitSettingsSource,
@@ -12,6 +15,9 @@
     'BaseSettings',
     'DotEnvSettingsSource',
     'EnvSettingsSource',
+    'CliSettingsSource',
+    'CliSubCommand',
+    'CliPositionalArg',
     'InitSettingsSource',
     'PydanticBaseSettingsSource',
     'SecretsSettingsSource',

pydantic_settings/main.py

@@ -10,6 +10,7 @@
 
 from .sources import (
     ENV_FILE_SENTINEL,
+    CliSettingsSource,
     DotEnvSettingsSource,
     DotenvType,
     EnvSettingsSource,
@@ -27,6 +28,11 @@ class SettingsConfigDict(ConfigDict, total=False):
     env_ignore_empty: bool
     env_nested_delimiter: str | None
     env_parse_none_str: str | None
+    cli_prog_name: str | None
+    cli_parse_args: bool | list[str] | None
+    cli_hide_none_type: bool
+    cli_avoid_json: bool
+    cli_enforce_required: bool
     secrets_dir: str | Path | None
 
 
@@ -59,6 +65,13 @@ class BaseSettings(BaseModel):
         _env_nested_delimiter: The nested env values delimiter. Defaults to `None`.
         _env_parse_none_str: The env string value that should be parsed (e.g. "null", "void", "None", etc.)
             into `None` type(None). Defaults to `None` type(None), which means no parsing should occur.
+        _cli_prog_name: The CLI program name to display in help text. Defaults to `None` if _cli_parse_args is `None`.
+            Otherwse, defaults to sys.argv[0].
+        _cli_parse_args: The list of CLI arguments to parse. Defaults to None.
+            If set to `True`, defaults to sys.argv[1:].
+        _cli_hide_none_type: Hide NoneType values in CLI help text. Defaults to `False`.
+        _cli_avoid_json: Avoid complex JSON objects in CLI help text. Defaults to `False`.
+        _cli_enforce_required: Enforce required fields at the CLI. Defaults to `False`.
         _secrets_dir: The secret files directory. Defaults to `None`.
     """
 
@@ -71,6 +84,11 @@ def __init__(
         _env_ignore_empty: bool | None = None,
         _env_nested_delimiter: str | None = None,
         _env_parse_none_str: str | None = None,
+        _cli_prog_name: str | None = None,
+        _cli_parse_args: bool | list[str] | None = None,
+        _cli_hide_none_type: bool | None = None,
+        _cli_avoid_json: bool | None = None,
+        _cli_enforce_required: bool | None = None,
         _secrets_dir: str | Path | None = None,
         **values: Any,
     ) -> None:
@@ -85,6 +103,11 @@ def __init__(
                 _env_ignore_empty=_env_ignore_empty,
                 _env_nested_delimiter=_env_nested_delimiter,
                 _env_parse_none_str=_env_parse_none_str,
+                _cli_prog_name=_cli_prog_name,
+                _cli_parse_args=_cli_parse_args,
+                _cli_hide_none_type=_cli_hide_none_type,
+                _cli_avoid_json=_cli_avoid_json,
+                _cli_enforce_required=_cli_enforce_required,
                 _secrets_dir=_secrets_dir,
             )
         )
@@ -123,6 +146,11 @@ def _settings_build_values(
         _env_ignore_empty: bool | None = None,
         _env_nested_delimiter: str | None = None,
         _env_parse_none_str: str | None = None,
+        _cli_prog_name: str | None = None,
+        _cli_parse_args: bool | list[str] | None = None,
+        _cli_hide_none_type: bool | None = None,
+        _cli_avoid_json: bool | None = None,
+        _cli_enforce_required: bool | None = None,
         _secrets_dir: str | Path | None = None,
     ) -> dict[str, Any]:
         # Determine settings config values
@@ -143,10 +171,32 @@ def _settings_build_values(
         env_parse_none_str = (
             _env_parse_none_str if _env_parse_none_str is not None else self.model_config.get('env_parse_none_str')
         )
+
+        cli_prog_name = _cli_prog_name if _cli_prog_name is not None else self.model_config.get('cli_prog_name')
+        cli_parse_args = _cli_parse_args if _cli_parse_args is not None else self.model_config.get('cli_parse_args')
+        cli_hide_none_type = (
+            _cli_hide_none_type if _cli_hide_none_type is not None else self.model_config.get('cli_hide_none_type')
+        )
+        cli_avoid_json = _cli_avoid_json if _cli_avoid_json is not None else self.model_config.get('cli_avoid_json')
+        cli_enforce_required = (
+            _cli_enforce_required
+            if _cli_enforce_required is not None
+            else self.model_config.get('cli_enforce_required')
+        )
+
         secrets_dir = _secrets_dir if _secrets_dir is not None else self.model_config.get('secrets_dir')
 
         # Configure built-in sources
         init_settings = InitSettingsSource(self.__class__, init_kwargs=init_kwargs)
+        cli_settings = CliSettingsSource(
+            self.__class__,
+            cli_prog_name=cli_prog_name,
+            cli_parse_args=cli_parse_args,
+            cli_parse_none_str=env_parse_none_str,
+            cli_hide_none_type=cli_hide_none_type,
+            cli_avoid_json=cli_avoid_json,
+            cli_enforce_required=cli_enforce_required,
+        )
         env_settings = EnvSettingsSource(
             self.__class__,
             case_sensitive=case_sensitive,
@@ -177,6 +227,8 @@ def _settings_build_values(
             dotenv_settings=dotenv_settings,
             file_secret_settings=file_secret_settings,
         )
+        if _cli_parse_args:
+            sources = (cli_settings,) + sources
         if sources:
             return deep_update(*reversed([source() for source in sources]))
         else:
@@ -195,6 +247,11 @@ def _settings_build_values(
         env_ignore_empty=False,
         env_nested_delimiter=None,
         env_parse_none_str=None,
+        cli_prog_name=None,
+        cli_parse_args=None,
+        cli_hide_none_type=False,
+        cli_avoid_json=False,
+        cli_enforce_required=False,
         secrets_dir=None,
         protected_namespaces=('model_', 'settings_'),
     )