Rename env_nested_depth to env_nested_max_split, default to None

Author: gsakkis

docs/index.md

@@ -325,7 +325,7 @@ print(Settings().model_dump())
 `_env_nested_delimiter` keyword argument on instantiation.
 
 By default environment variables are split by `env_nested_delimiter` into arbitrarily deep nested fields. You can limit
-the depth of the nested fields with the `env_nested_depth` config setting. A common use case this is particularly useful
+the depth of the nested fields with the `env_nested_max_split` config setting. A common use case this is particularly useful
 is for two-level deep settings, where the `env_nested_delimiter` (usually a single `_`) may be a substring of model
 field names. For example:
 
@@ -353,7 +353,7 @@ class LLMConfig(BaseModel):
 
 class GenerationConfig(BaseSettings):
     model_config = SettingsConfigDict(
-        env_nested_delimiter='_', env_nested_depth=1, env_prefix='GENERATION_'
+        env_nested_delimiter='_', env_nested_max_split=1, env_prefix='GENERATION_'
     )
 
     llm: LLMConfig
@@ -373,7 +373,7 @@ print(GenerationConfig().model_dump())
 """
 ```
 
-Without `env_nested_depth=1` set, `GENERATION_LLM_API_KEY` would be parsed as `llm.api.key` instead of `llm.api_key`
+Without `env_nested_max_split=1` set, `GENERATION_LLM_API_KEY` would be parsed as `llm.api.key` instead of `llm.api_key`
 and it would raise a `ValidationError`.
 
 Nested environment variables take precedence over the top-level environment variable JSON

pydantic_settings/main.py

@@ -38,7 +38,7 @@ class SettingsConfigDict(ConfigDict, total=False):
     env_file_encoding: str | None
     env_ignore_empty: bool
     env_nested_delimiter: str | None
-    env_nested_depth: int
+    env_nested_max_split: int | None
     env_parse_none_str: str | None
     env_parse_enums: bool | None
     cli_prog_name: str | None
@@ -113,7 +113,7 @@ class BaseSettings(BaseModel):
         _env_file_encoding: The env file encoding, e.g. `'latin-1'`. Defaults to `None`.
         _env_ignore_empty: Ignore environment variables where the value is an empty string. Default to `False`.
         _env_nested_delimiter: The nested env values delimiter. Defaults to `None`.
-        _env_nested_depth: The nested env values maximum nesting. Defaults to `-1`, which means no limit.
+        _env_nested_max_split: The nested env values maximum nesting. Defaults to `None`, which means no limit.
         _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.
         _env_parse_enums: Parse enum field names to values. Defaults to `None.`, which means no parsing should occur.
@@ -150,7 +150,7 @@ def __init__(
         _env_file_encoding: str | None = None,
         _env_ignore_empty: bool | None = None,
         _env_nested_delimiter: str | None = None,
-        _env_nested_depth: int | None = None,
+        _env_nested_max_split: int | None = None,
         _env_parse_none_str: str | None = None,
         _env_parse_enums: bool | None = None,
         _cli_prog_name: str | None = None,
@@ -181,7 +181,7 @@ def __init__(
                 _env_file_encoding=_env_file_encoding,
                 _env_ignore_empty=_env_ignore_empty,
                 _env_nested_delimiter=_env_nested_delimiter,
-                _env_nested_depth=_env_nested_depth,
+                _env_nested_max_split=_env_nested_max_split,
                 _env_parse_none_str=_env_parse_none_str,
                 _env_parse_enums=_env_parse_enums,
                 _cli_prog_name=_cli_prog_name,
@@ -236,7 +236,7 @@ def _settings_build_values(
         _env_file_encoding: str | None = None,
         _env_ignore_empty: bool | None = None,
         _env_nested_delimiter: str | None = None,
-        _env_nested_depth: int | None = None,
+        _env_nested_max_split: int | None = None,
         _env_parse_none_str: str | None = None,
         _env_parse_enums: bool | None = None,
         _cli_prog_name: str | None = None,
@@ -275,8 +275,10 @@ def _settings_build_values(
             if _env_nested_delimiter is not None
             else self.model_config.get('env_nested_delimiter')
         )
-        env_nested_depth = (
-            _env_nested_depth if _env_nested_depth is not None else self.model_config.get('env_nested_depth')
+        env_nested_max_split = (
+            _env_nested_max_split
+            if _env_nested_max_split is not None
+            else self.model_config.get('env_nested_max_split')
         )
         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')
@@ -341,7 +343,7 @@ def _settings_build_values(
             case_sensitive=case_sensitive,
             env_prefix=env_prefix,
             env_nested_delimiter=env_nested_delimiter,
-            env_nested_depth=env_nested_depth,
+            env_nested_max_split=env_nested_max_split,
             env_ignore_empty=env_ignore_empty,
             env_parse_none_str=env_parse_none_str,
             env_parse_enums=env_parse_enums,
@@ -353,7 +355,7 @@ def _settings_build_values(
             case_sensitive=case_sensitive,
             env_prefix=env_prefix,
             env_nested_delimiter=env_nested_delimiter,
-            env_nested_depth=env_nested_depth,
+            env_nested_max_split=env_nested_max_split,
             env_ignore_empty=env_ignore_empty,
             env_parse_none_str=env_parse_none_str,
             env_parse_enums=env_parse_enums,
@@ -422,7 +424,7 @@ def _settings_build_values(
         env_file_encoding=None,
         env_ignore_empty=False,
         env_nested_delimiter=None,
-        env_nested_depth=-1,
+        env_nested_max_split=None,
         env_parse_none_str=None,
         env_parse_enums=None,
         cli_prog_name=None,

pydantic_settings/sources.py

@@ -735,7 +735,7 @@ def __init__(
         case_sensitive: bool | None = None,
         env_prefix: str | None = None,
         env_nested_delimiter: str | None = None,
-        env_nested_depth: int | None = None,
+        env_nested_max_split: int | None = None,
         env_ignore_empty: bool | None = None,
         env_parse_none_str: str | None = None,
         env_parse_enums: bool | None = None,
@@ -746,10 +746,10 @@ def __init__(
         self.env_nested_delimiter = (
             env_nested_delimiter if env_nested_delimiter is not None else self.config.get('env_nested_delimiter')
         )
-        self.env_nested_depth = (
-            env_nested_depth if env_nested_depth is not None else self.config.get('env_nested_depth', -1)
+        self.env_nested_max_split = (
+            env_nested_max_split if env_nested_max_split is not None else self.config.get('env_nested_max_split')
         )
-        self.maxsplit = self.env_nested_depth - 1 if self.env_nested_depth > 0 else self.env_nested_depth
+        self.maxsplit = (self.env_nested_max_split or 0) - 1
         self.env_prefix_len = len(self.env_prefix)
 
         self.env_vars = self._load_env_vars()
@@ -954,7 +954,7 @@ def explode_env_vars(self, field_name: str, field: FieldInfo, env_vars: Mapping[
     def __repr__(self) -> str:
         return (
             f'{self.__class__.__name__}(env_nested_delimiter={self.env_nested_delimiter!r}, '
-            f'env_nested_depth={self.env_nested_depth}, env_prefix_len={self.env_prefix_len!r})'
+            f'env_prefix_len={self.env_prefix_len!r})'
         )
 
 
@@ -971,7 +971,7 @@ def __init__(
         case_sensitive: bool | None = None,
         env_prefix: str | None = None,
         env_nested_delimiter: str | None = None,
-        env_nested_depth: int | None = None,
+        env_nested_max_split: int | None = None,
         env_ignore_empty: bool | None = None,
         env_parse_none_str: str | None = None,
         env_parse_enums: bool | None = None,
@@ -985,7 +985,7 @@ def __init__(
             case_sensitive,
             env_prefix,
             env_nested_delimiter,
-            env_nested_depth,
+            env_nested_max_split,
             env_ignore_empty,
             env_parse_none_str,
             env_parse_enums,
@@ -1072,8 +1072,7 @@ def __call__(self) -> dict[str, Any]:
     def __repr__(self) -> str:
         return (
             f'{self.__class__.__name__}(env_file={self.env_file!r}, env_file_encoding={self.env_file_encoding!r}, '
-            f'env_nested_delimiter={self.env_nested_delimiter!r}, env_nested_depth={self.env_nested_depth}, '
-            f'env_prefix_len={self.env_prefix_len!r})'
+            f'env_nested_delimiter={self.env_nested_delimiter!r}, env_prefix_len={self.env_prefix_len!r})'
         )
 
 

tests/conftest.py

@@ -79,7 +79,7 @@ def docs_test_env():
     setenv.set('SUB_MODEL__V3', '3')
     setenv.set('SUB_MODEL__DEEP__V4', 'v4')
 
-    # envs for parsing environment variable values example with env_nested_depth=1
+    # envs for parsing environment variable values example with env_nested_max_split=1
     setenv.set('GENERATION_LLM_PROVIDER', 'anthropic')
     setenv.set('GENERATION_LLM_API_KEY', 'your-api-key')
     setenv.set('GENERATION_LLM_API_VERSION', '2024-03-15')

tests/test_settings.py

@@ -399,7 +399,7 @@ class Cfg(BaseSettings):
 
 
 @pytest.mark.parametrize('env_prefix', [None, 'prefix_', 'prefix__'])
-def test_nested_env_depth(env, env_prefix):
+def test_nested_env_max_split(env, env_prefix):
     class Person(BaseModel):
         sex: Literal['M', 'F']
         first_name: str
@@ -410,7 +410,7 @@ class Cfg(BaseSettings):
         significant_other: Optional[Person] = None
         next_of_kin: Optional[Person] = None
 
-        model_config = SettingsConfigDict(env_nested_delimiter='_', env_nested_depth=1)
+        model_config = SettingsConfigDict(env_nested_delimiter='_', env_nested_max_split=1)
         if env_prefix is not None:
             model_config['env_prefix'] = env_prefix
 
@@ -1857,11 +1857,11 @@ def test_builtins_settings_source_repr():
     )
     assert (
         repr(EnvSettingsSource(BaseSettings, env_nested_delimiter='__'))
-        == "EnvSettingsSource(env_nested_delimiter='__', env_nested_depth=-1, env_prefix_len=0)"
+        == "EnvSettingsSource(env_nested_delimiter='__', env_prefix_len=0)"
     )
     assert repr(DotEnvSettingsSource(BaseSettings, env_file='.env', env_file_encoding='utf-8')) == (
         "DotEnvSettingsSource(env_file='.env', env_file_encoding='utf-8', "
-        'env_nested_delimiter=None, env_nested_depth=-1, env_prefix_len=0)'
+        'env_nested_delimiter=None, env_prefix_len=0)'
     )
     assert (
         repr(SecretsSettingsSource(BaseSettings, secrets_dir='/secrets'))