pydantic/pydantic-settings

The user-facing surface is primarily Python APIs plus model-generated command-line behavior. Configuration features cover precedence, aliases, nested values, decoding, files, and secrets. Optional cloud sources adapt remote secret stores to model fields. Reloading, shared caching, diagnostic logging, help generation, and CLI serialization round out the operational APIs.

• SettingsConfigDict and constructor overrides configure case sensitivity, environment prefixes and prefix targets, empty-value filtering, nested delimiters/split limits, null strings, and enum parsing.
  pydantic_settings/main.py#L56-L68pydantic_settings/main.py#L215-L228pydantic_settings/main.py#L388-L415
• Complex environment values support JSON decoding and nested-key overrides; NoDecode, ForceDecode, and enable_decoding control decoding, while nested_model_default_partial_update can contribute model/dataclass default mappings.
  pydantic_settings/sources/providers/env.py#L136-L162pydantic_settings/sources/base.py#L190-L208pydantic_settings/sources/base.py#L279-L295
• Dotenv loading supports multiple files, encoding, bounded parent-directory discovery, and only_existing or match_prefix filtering; explicit _env_file=None disables loading.
  pydantic_settings/main.py#L168-L173pydantic_settings/sources/providers/dotenv.py#L100-L144
• JSON, TOML, and YAML sources accept multiple paths or packaged Traversable resources and optional deep merging; TOML selects tuple-based tables, YAML selects dotted sections, and pyproject defaults to tool.pydantic-settings.
  pydantic_settings/sources/types.py#L36-L43pydantic_settings/sources/base.py#L215-L235pydantic_settings/sources/providers/toml.py#L53-L71pydantic_settings/sources/providers/yaml.py#L41-L79pydantic_settings/sources/providers/pyproject.py#L28-L37
• Flat secrets load field-matched UTF-8 files from ordered directories; nested secrets additionally support directory-shaped nesting, separate prefix/case rules, missing-directory policies, and a default 16 MiB size limit.
  pydantic_settings/sources/providers/secrets.py#L121-L137pydantic_settings/sources/providers/nested_secrets.py#L19-L95
• Cloud integrations include AWS Secrets Manager with optional VersionId, recursive decrypted AWS SSM parameters, Azure enabled-secret lookup and name conversion, and GCP project resolution plus per-field SecretVersion metadata.
  pydantic_settings/sources/providers/aws.py#L76-L89pydantic_settings/sources/providers/aws.py#L132-L149pydantic_settings/sources/providers/azure.py#L60-L97pydantic_settings/sources/providers/gcp.py#L238-L265
• CLI models support subcommands, positional and variadic arguments, dual/toggle/explicit boolean flags, unknown-argument capture, suppression, shortcuts, kebab-case naming, mutually exclusive groups, and customizable parser methods.
  pydantic_settings/sources/providers/cli.py#L302-L313pydantic_settings/sources/providers/cli.py#L368-L394pydantic_settings/sources/providers/cli.py#L961-L976pydantic_settings/sources/providers/cli.py#L1238-L1284
• Operational APIs include settings_cached/settings_clear_cache, documented in-place __init__ reloading, PYDANTIC_SETTINGS_DEBUG source diagnostics, and CliApp run, run_subcommand, serialize, format_help, and print_help.
  pydantic_settings/main.py#L288-L327docs/index.md#L3652-L3684pydantic_settings/main.py#L591-L603pydantic_settings/main.py#L967-L1068