pydantic/pydantic-settings v2.16.2

on GitHub

Highlights

This patch release fixes env decoding of nested dictionary values, CliApp handling of AliasPath, nested secrets directory precedence and discriminated union defaults with nested_model_default_partial_update.

Behavior changes

• An explicit secrets_dir on NestedSecretsSettingsSource now takes precedence (#1093). Previously it was ignored when the wrapped SecretsSettingsSource inherited a directory from model config, and an explicit empty list was masked too. The order is now: the wrapper's secrets_dir argument, then the wrapped source's directory, then model config. If you pass both Settings(_secrets_dir=...) and NestedSecretsSettingsSource(..., secrets_dir=...), the wrapper's argument now wins.

Bug fixes

Env and dotenv sources

• Dictionary values typed as a union, such as dict[str, list[str] | str] or dict[str, list[str] | None], now JSON-decode values set through env_nested_delimiter (#1089, #1097). Only JSON arrays and objects are decoded, so plain values like 123, true or "quoted" are kept as strings. Decoding follows enable_decoding and the NoDecode/ForceDecode of the field that holds the dict, and type aliases and Annotated value types are resolved.
• Nested dictionary values such as dict[str, list[dict[str, str]]] are decoded at the right level again (#1109), so APP_VALUES__X='[{"k":"v"}]' no longer reaches validation as a string.

CLI

• CliApp.run now rebuilds AliasPath inputs for BaseModel and pydantic dataclass commands (#1096). A supplied path used to be reduced to the field name, which failed validation. AliasChoices priority is respected and unsupplied path defaults are left to the model.

Discriminated union defaults

• With nested_model_default_partial_update=True, inner discriminated unions written as Annotated[..., Field(discriminator='...')] are now detected (#1076). When the incoming tag selects another member, the default's fields are no longer merged into it.
• A stdlib dataclass default on a discriminated union field no longer raises NameError when another field of the dataclass has a string annotation naming a local class (#1077). Only the discriminator's own annotation is resolved now.