add tests and docs

Author: pmeier

docs/index.md

@@ -2401,12 +2401,7 @@ Other settings sources are available for common configuration files:
 - `TomlConfigSettingsSource` using `toml_file` argument
 - `YamlConfigSettingsSource` using `yaml_file` and yaml_file_encoding arguments
 
-You can also provide multiple files by providing a list of path:
-```py
-toml_file = ['config.default.toml', 'config.custom.toml']
-```
-To use them, you can use the same mechanism described [here](#customise-settings-sources)
-
+To use them, you can use the same mechanism described [here](#customise-settings-sources).
 
 ```py
 from pydantic import BaseModel
@@ -2448,6 +2443,126 @@ foobar = "Hello"
 nested_field = "world!"
 ```
 
+You can also provide multiple files by providing a list of paths.
+
+```py
+from pydantic_settings import (
+    BaseSettings,
+    PydanticBaseSettingsSource,
+    SettingsConfigDict,
+    TomlConfigSettingsSource,
+)
+
+class Nested(BaseModel):
+    foo: int
+    bar: int = 0
+
+
+class Settings(BaseSettings):
+    hello: str
+    nested: Nested
+    model_config = SettingsConfigDict(toml_file=['config.default.toml', 'config.custom.toml'])
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        return (TomlConfigSettingsSource(settings_cls),)
+```
+
+The following two configuration files
+
+```toml
+# config.default.toml
+hello = "World"
+
+[nested]
+foo = 1
+bar = 2
+```
+
+```toml
+# config.custom.toml
+[nested]
+foo = 3
+```
+
+are equivalent to
+
+```toml
+hello = "world"
+
+[nested]
+foo = 3
+```
+
+The files are merged shallowly in increasing order of priority. To enable deep merging, set `deep_merge=True` on the source directly.
+
+!!! warning
+    The `deep_merge` option is **not available** through the `SettingsConfigDict`.
+
+```py
+from pydantic_settings import (
+    BaseSettings,
+    PydanticBaseSettingsSource,
+    SettingsConfigDict,
+    TomlConfigSettingsSource,
+)
+
+class Nested(BaseModel):
+    foo: int
+    bar: int = 0
+
+
+class Settings(BaseSettings):
+    hello: str
+    nested: Nested
+    model_config = SettingsConfigDict(toml_file=['config.default.toml', 'config.custom.toml'])
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        return (TomlConfigSettingsSource(settings_cls, deep_merge=True),)
+```
+
+With deep merge enabled, the following two configuration files
+
+```toml
+# config.default.toml
+hello = "World"
+
+[nested]
+foo = 1
+bar = 2
+```
+
+```toml
+# config.custom.toml
+[nested]
+foo = 3
+```
+
+are equivalent to
+
+```toml
+hello = "world"
+
+[nested]
+foo = 3
+bar = 2
+```
+
 ### pyproject.toml
 
 "pyproject.toml" is a standardized file for providing configuration values in Python projects.

pydantic_settings/sources/base.py

@@ -198,11 +198,17 @@ def _read_files(self, files: PathType | None, deep_merge: bool = False) -> dict[
         if isinstance(files, (str, os.PathLike)):
             files = [files]
         vars: dict[str, Any] = {}
-        update = deep_update if deep_merge else dict.update
+        update = deep_update if deep_merge else self._shallow_update
         for file in files:
             file_path = Path(file).expanduser()
             if file_path.is_file():
-                update(vars, self._read_file(file_path))
+                vars = update(vars, self._read_file(file_path))
+        return vars
+
+    def _shallow_update(self, vars: dict[str, Any], updating_vars: dict[str, Any]) -> dict[str, Any]:
+        # this mimics the semantics of pydantic._internal._utils.deep_update
+        vars = vars.copy()
+        vars.update(updating_vars)
         return vars
 
     @abstractmethod

tests/test_source_json.py

@@ -5,6 +5,7 @@
 import json
 from pathlib import Path
 
+import pytest
 from pydantic import BaseModel
 
 from pydantic_settings import (
@@ -98,3 +99,36 @@ def settings_customise_sources(
 
     s = Settings()
     assert s.model_dump() == {'json5': 5, 'json6': 6}
+
+
+@pytest.mark.parametrize('deep_merge', [False, True])
+def test_multiple_file_json_merge(tmp_path, deep_merge):
+    p5 = tmp_path / '.env.json5'
+    p6 = tmp_path / '.env.json6'
+
+    with open(p5, 'w') as f5:
+        json.dump({'hello': 'world', 'nested': {'foo': 1, 'bar': 2}}, f5)
+    with open(p6, 'w') as f6:
+        json.dump({'nested': {'foo': 3}}, f6)
+
+    class Nested(BaseModel):
+        foo: int
+        bar: int = 0
+
+    class Settings(BaseSettings):
+        hello: str
+        nested: Nested
+
+        @classmethod
+        def settings_customise_sources(
+            cls,
+            settings_cls: type[BaseSettings],
+            init_settings: PydanticBaseSettingsSource,
+            env_settings: PydanticBaseSettingsSource,
+            dotenv_settings: PydanticBaseSettingsSource,
+            file_secret_settings: PydanticBaseSettingsSource,
+        ) -> tuple[PydanticBaseSettingsSource, ...]:
+            return (JsonConfigSettingsSource(settings_cls, json_file=[p5, p6], deep_merge=deep_merge),)
+
+    s = Settings()
+    assert s.model_dump() == {'hello': 'world', 'nested': {'foo': 3, 'bar': 2 if deep_merge else 0}}

tests/test_source_toml.py

@@ -114,3 +114,47 @@ def settings_customise_sources(
 
     s = Settings()
     assert s.model_dump() == {'toml1': 1, 'toml2': 2}
+
+
+@pytest.mark.skipif(sys.version_info <= (3, 11) and tomli is None, reason='tomli/tomllib is not installed')
+@pytest.mark.parametrize('deep_merge', [False, True])
+def test_multiple_file_toml_merge(tmp_path, deep_merge):
+    p1 = tmp_path / '.env.toml1'
+    p2 = tmp_path / '.env.toml2'
+    p1.write_text(
+        """
+    hello = "world"
+
+    [nested]
+    foo=1
+    bar=2
+    """
+    )
+    p2.write_text(
+        """
+    [nested]
+    foo=3
+    """
+    )
+
+    class Nested(BaseModel):
+        foo: int
+        bar: int = 0
+
+    class Settings(BaseSettings):
+        hello: str
+        nested: Nested
+
+        @classmethod
+        def settings_customise_sources(
+            cls,
+            settings_cls: type[BaseSettings],
+            init_settings: PydanticBaseSettingsSource,
+            env_settings: PydanticBaseSettingsSource,
+            dotenv_settings: PydanticBaseSettingsSource,
+            file_secret_settings: PydanticBaseSettingsSource,
+        ) -> tuple[PydanticBaseSettingsSource, ...]:
+            return (TomlConfigSettingsSource(settings_cls, toml_file=[p1, p2], deep_merge=deep_merge),)
+
+    s = Settings()
+    assert s.model_dump() == {'hello': 'world', 'nested': {'foo': 3, 'bar': 2 if deep_merge else 0}}

tests/test_source_yaml.py

@@ -167,6 +167,50 @@ def settings_customise_sources(
     assert s.model_dump() == {'yaml3': 3, 'yaml4': 4}
 
 
+@pytest.mark.skipif(yaml is None, reason='pyYAML is not installed')
+@pytest.mark.parametrize('deep_merge', [False, True])
+def test_multiple_file_yaml_deep_merge(tmp_path, deep_merge):
+    p3 = tmp_path / '.env.yaml3'
+    p4 = tmp_path / '.env.yaml4'
+    p3.write_text(
+        """
+    hello: world
+
+    nested:
+      foo: 1
+      bar: 2
+    """
+    )
+    p4.write_text(
+        """
+    nested:
+      foo: 3
+    """
+    )
+
+    class Nested(BaseModel):
+        foo: int
+        bar: int = 0
+
+    class Settings(BaseSettings):
+        hello: str
+        nested: Nested
+
+        @classmethod
+        def settings_customise_sources(
+            cls,
+            settings_cls: type[BaseSettings],
+            init_settings: PydanticBaseSettingsSource,
+            env_settings: PydanticBaseSettingsSource,
+            dotenv_settings: PydanticBaseSettingsSource,
+            file_secret_settings: PydanticBaseSettingsSource,
+        ) -> tuple[PydanticBaseSettingsSource, ...]:
+            return (YamlConfigSettingsSource(settings_cls, yaml_file=[p3, p4], deep_merge=deep_merge),)
+
+    s = Settings()
+    assert s.model_dump() == {'hello': 'world', 'nested': {'foo': 3, 'bar': 2 if deep_merge else 0}}
+
+
 @pytest.mark.skipif(yaml is None, reason='pyYAML is not installed')
 def test_yaml_config_section(tmp_path):
     p = tmp_path / '.env'