Add env_nested_depth option

Author: gsakkis

pydantic_settings/main.py

@@ -38,6 +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_parse_none_str: str | None
     env_parse_enums: bool | None
     cli_prog_name: str | None
@@ -112,6 +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_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.
@@ -148,6 +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_parse_none_str: str | None = None,
         _env_parse_enums: bool | None = None,
         _cli_prog_name: str | None = None,
@@ -178,6 +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_parse_none_str=_env_parse_none_str,
                 _env_parse_enums=_env_parse_enums,
                 _cli_prog_name=_cli_prog_name,
@@ -232,6 +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_parse_none_str: str | None = None,
         _env_parse_enums: bool | None = None,
         _cli_prog_name: str | None = None,
@@ -270,6 +275,9 @@ 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_parse_none_str = (
             _env_parse_none_str if _env_parse_none_str is not None else self.model_config.get('env_parse_none_str')
         )
@@ -333,6 +341,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_ignore_empty=env_ignore_empty,
             env_parse_none_str=env_parse_none_str,
             env_parse_enums=env_parse_enums,
@@ -344,6 +353,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_ignore_empty=env_ignore_empty,
             env_parse_none_str=env_parse_none_str,
             env_parse_enums=env_parse_enums,
@@ -412,6 +422,7 @@ def _settings_build_values(
         env_file_encoding=None,
         env_ignore_empty=False,
         env_nested_delimiter=None,
+        env_nested_depth=-1,
         env_parse_none_str=None,
         env_parse_enums=None,
         cli_prog_name=None,

pydantic_settings/sources.py

@@ -735,6 +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_ignore_empty: bool | None = None,
         env_parse_none_str: str | None = None,
         env_parse_enums: bool | None = None,
@@ -745,6 +746,9 @@ 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_prefix_len = len(self.env_prefix)
 
         self.env_vars = self._load_env_vars()
@@ -914,7 +918,7 @@ def explode_env_vars(self, field_name: str, field: FieldInfo, env_vars: Mapping[
                 continue
             # we remove the prefix before splitting in case the prefix has characters in common with the delimiter
             env_name_without_prefix = env_name[self.env_prefix_len :]
-            _, *keys, last_key = env_name_without_prefix.split(self.env_nested_delimiter)
+            _, *keys, last_key = env_name_without_prefix.split(self.env_nested_delimiter, self.env_nested_depth)
             env_var = result
             target_field: FieldInfo | None = field
             for key in keys:
@@ -947,7 +951,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_prefix_len={self.env_prefix_len!r})'
+            f'env_nested_depth={self.env_nested_depth}, env_prefix_len={self.env_prefix_len!r})'
         )
 
 
@@ -964,6 +968,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_ignore_empty: bool | None = None,
         env_parse_none_str: str | None = None,
         env_parse_enums: bool | None = None,
@@ -977,6 +982,7 @@ def __init__(
             case_sensitive,
             env_prefix,
             env_nested_delimiter,
+            env_nested_depth,
             env_ignore_empty,
             env_parse_none_str,
             env_parse_enums,
@@ -1063,7 +1069,8 @@ 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_prefix_len={self.env_prefix_len!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})'
         )
 
 

tests/test_settings.py

@@ -4,7 +4,7 @@
 import pathlib
 import sys
 import uuid
-from datetime import datetime, timezone
+from datetime import date, datetime, timezone
 from enum import IntEnum
 from pathlib import Path
 from typing import Any, Callable, Dict, Generic, Hashable, List, Optional, Set, Tuple, Type, TypeVar, Union
@@ -398,6 +398,30 @@ class Cfg(BaseSettings):
     assert Cfg().model_dump() == {'sub_model': {'v1': '-1-', 'v2': '-2-'}}
 
 
+@pytest.mark.parametrize('env_prefix', [None, 'prefix_', 'prefix__'])
+def test_nested_env_depth(env, env_prefix):
+    class Person(BaseModel):
+        sex: Literal['M', 'F']
+        first_name: str
+        date_of_birth: date
+
+    class Cfg(BaseSettings):
+        caregiver: Person
+
+        model_config = SettingsConfigDict(env_nested_delimiter='_', env_nested_depth=1)
+        if env_prefix is not None:
+            model_config['env_prefix'] = env_prefix
+
+    env_prefix = env_prefix or ''
+    env.set(env_prefix + 'caregiver_sex', 'M')
+    env.set(env_prefix + 'caregiver_first_name', 'Joe')
+    env.set(env_prefix + 'caregiver_date_of_birth', '1975-09-12')
+
+    assert Cfg().model_dump() == {
+        'caregiver': {'sex': 'M', 'first_name': 'Joe', 'date_of_birth': date(1975, 9, 12)},
+    }
+
+
 class DateModel(BaseModel):
     pips: bool = False
 
@@ -1823,11 +1847,11 @@ def test_builtins_settings_source_repr():
     )
     assert (
         repr(EnvSettingsSource(BaseSettings, env_nested_delimiter='__'))
-        == "EnvSettingsSource(env_nested_delimiter='__', env_prefix_len=0)"
+        == "EnvSettingsSource(env_nested_delimiter='__', env_nested_depth=-1, 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_prefix_len=0)'
+        'env_nested_delimiter=None, env_nested_depth=-1, env_prefix_len=0)'
     )
     assert (
         repr(SecretsSettingsSource(BaseSettings, secrets_dir='/secrets'))