nested_model_default_partial_update documentation isn't clear

[slingshotvfx]

The example given here doesn't actually change if you set nested_model_default_partial_update to False, so it's not clear to me what that flag actually does.

Playing around with it, it seems nested_model_default_partial_update only applies when a nested model has already been instantiated with non-default arguments. The documentation could be made clearer that when False, a new default instance of SubModel is created using only environment variables but when true, the existing SubModel instance is updated from the environment.

The code could be updated to, for example:

class SubModel(BaseModel):
    val: int = 0
    flag: bool = False


class Settings(BaseSettings):
    model_config = SettingsConfigDict(env_nested_delimiter="__", nested_model_default_partial_update=True)

    nested_model: SubModel = SubModel(val=1)


class SettingsFalse(BaseSettings):
    model_config = SettingsConfigDict(env_nested_delimiter="__", nested_model_default_partial_update=False)

    nested_model: SubModel = SubModel(val=1)


# Apply a partial update to the default object using environment variables
os.environ["NESTED_MODEL__FLAG"] = "True"

print(Settings().model_dump())
print(SettingsFalse().model_dump())

output:

{'nested_model': {'val': 1, 'flag': True}}
{'nested_model': {'val': 0, 'flag': True}}

[hramezani]

@kschwab Do you have time to check this issue?

[kschwab]

Good catch @slingshotvfx, thanks for the issue. I've opened #433 to resolve.