# Behavior traces — pydantic/pydantic-settings

> Canonical page: https://codevetter.com/unpack/pydantic-settings/behavior-traces

# Behavior traces — pydantic/pydantic-settings

Scanned commit 5927b441848c330853eac74c82358bc283cd3640 (2026-10-02). Generated by codevetter codevetter 1.15.0 on 2026-10-02.

Source inspection; upstream code and tests were not executed.

The inspected flows cover ordinary construction, CLI command execution, file-backed secrets, cloud-backed secrets, caching, and serialization. Their execution order explains when I/O happens and which state a source can observe. File and cloud paths load configuration into models; the shown flows do not persist model changes back to their input stores. Cache reuse retains validated instances within the process.
- Construction flow: BaseSettings.__init__ → _settings_init_sources → built-in source constructors → settings_customise_sources → _settings_build_values → BaseModel.__init__; sources normally run init, environment, dotenv, flat secrets, defaults. — [pydantic_settings/main.py#L249-L286](https://github.com/pydantic/pydantic-settings/blob/5927b441848c330853eac74c82358bc283cd3640/pydantic_settings/main.py#L249-L286) [pydantic_settings/main.py#L329-L351](https://github.com/pydantic/pydantic-settings/blob/5927b441848c330853eac74c82358bc283cd3640/pydantic_settings/main.py#L329-L351) [pydantic_settings/main.py#L461-L516](https://github.com/pydantic/pydantic-settings/blob/5927b441848c330853eac74c82358bc283cd3640/pydantic_settings/main.py#L461-L516) [pydantic_settings/main.py#L556-L585](https://github.com/pydantic/pydantic-settings/blob/5927b441848c330853eac74c82358bc283cd3640/pydantic_settings/main.py#L556-L585)
- Nested environment flow: EnvSettingsSource._load_env_vars → parse_env_vars → inherited __call__ → get_field_value → prepare_field_value → decode_complex_value/explode_env_vars; nested entries override overlapping decoded JSON keys before model validation. — [pydantic_settings/sources/providers/env.py#L84-L94](https://github.com/pydantic/pydantic-settings/blob/5927b441848c330853eac74c82358bc283cd3640/pydantic_settings/sources/providers/env.py#L84-L94) [pydantic_settings/sources/base.py#L600-L634](https://github.com/pydantic/pydantic-settings/blob/5927b441848c330853eac74c82358bc283cd3640/pydantic_settings/sources/base.py#L600-L634) [pydantic_settings/sources/providers/env.py#L109-L158](https://github.com/pydantic/pydantic-settings/blob/5927b441848c330853eac74c82358bc283cd3640/pydantic_settings/sources/providers/env.py#L109-L158) [pydantic_settings/sources/base.py#L190-L208](https://github.com/pydantic/pydantic-settings/blob/5927b441848c330853eac74c82358bc283cd3640/pydantic_settings/sources/base.py#L190-L208)
- Dotenv flow: DotEnvSettingsSource initialization invokes its _load_env_vars override → _read_env_files → _resolve_config_file → dotenv_values → parse_env_vars; later files replace earlier keys, then __call__ applies field extraction and extra-variable filtering. — [pydantic_settings/sources/providers/dotenv.py#L59-L86](https://github.com/pydantic/pydantic-settings/blob/5927b441848c330853eac74c82358bc283cd3640/pydantic_settings/sources/providers/dotenv.py#L59-L86) [pydantic_settings/sources/providers/dotenv.py#L100-L144](https://github.com/pydantic/pydantic-settings/blob/5927b441848c330853eac74c82358bc283cd3640/pydantic_settings/sources/providers/dotenv.py#L100-L144) [pydantic_settings/sources/utils.py#L81-L97](https://github.com/pydantic/pydantic-settings/blob/5927b441848c330853eac74c82358bc283cd3640/pydantic_settings/sources/utils.py#L81-L97)
- Flat-secret flow: SecretsSettingsSource.__call__ expands configured directories, warns for missing paths, rejects existing non-directories, then inherited field traversal calls get_field_value → find_case_path → UTF-8 read_text().strip(); later directories are searched first. — [pydantic_settings/sources/providers/secrets.py#L56-L104](https://github.com/pydantic/pydantic-settings/blob/5927b441848c330853eac74c82358bc283cd3640/pydantic_settings/sources/providers/secrets.py#L56-L104) [pydantic_settings/sources/providers/secrets.py#L121-L137](https://github.com/pydantic/pydantic-settings/blob/5927b441848c330853eac74c82358bc283cd3640/pydantic_settings/sources/providers/secrets.py#L121-L137) [pydantic_settings/sources/base.py#L600-L634](https://github.com/pydantic/pydantic-settings/blob/5927b441848c330853eac74c82358bc283cd3640/pydantic_settings/sources/base.py#L600-L634)
- CLI flow: CliApp.run checks the model type → _settings_init_sources creates/connects CliSettingsSource → arguments load into env_vars → sources merge and validate → _run_cli_cmd invokes the root handler if present; a handler calling run_subcommand selects the annotated child and requires its handler. — [pydantic_settings/main.py#L857-L903](https://github.com/pydantic/pydantic-settings/blob/5927b441848c330853eac74c82358bc283cd3640/pydantic_settings/main.py#L857-L903) [pydantic_settings/sources/providers/cli.py#L487-L518](https://github.com/pydantic/pydantic-settings/blob/5927b441848c330853eac74c82358bc283cd3640/pydantic_settings/sources/providers/cli.py#L487-L518) [pydantic_settings/main.py#L941-L964](https://github.com/pydantic/pydantic-settings/blob/5927b441848c330853eac74c82358bc283cd3640/pydantic_settings/main.py#L941-L964) [pydantic_settings/sources/base.py#L83-L103](https://github.com/pydantic/pydantic-settings/blob/5927b441848c330853eac74c82358bc283cd3640/pydantic_settings/sources/base.py#L83-L103)
- GCP flow: source construction initially returns an empty environment mapping; the merge loop supplies current_state → source.__call__ → _load_env_vars → _resolve_gcp_project → GoogleSecretManagerMapping → field lookup → access_secret_version, using explicit project, prior-source project, then auth defaults. — [pydantic_settings/main.py#L560-L566](https://github.com/pydantic/pydantic-settings/blob/5927b441848c330853eac74c82358bc283cd3640/pydantic_settings/main.py#L560-L566) [pydantic_settings/sources/providers/gcp.py#L202-L222](https://github.com/pydantic/pydantic-settings/blob/5927b441848c330853eac74c82358bc283cd3640/pydantic_settings/sources/providers/gcp.py#L202-L222) [pydantic_settings/sources/providers/gcp.py#L275-L342](https://github.com/pydantic/pydantic-settings/blob/5927b441848c330853eac74c82358bc283cd3640/pydantic_settings/sources/providers/gcp.py#L275-L342) [pydantic_settings/sources/providers/gcp.py#L113-L148](https://github.com/pydantic/pydantic-settings/blob/5927b441848c330853eac74c82358bc283cd3640/pydantic_settings/sources/providers/gcp.py#L113-L148)
- Cache flow: settings_cached checks the guarded class cache, obtains a per-class lock, double-checks the entry, constructs cls() outside the global guard, and stores it; settings_clear_cache removes only the exact class entry and cannot revoke held or in-flight references. — [pydantic_settings/main.py#L288-L327](https://github.com/pydantic/pydantic-settings/blob/5927b441848c330853eac74c82358bc283cd3640/pydantic_settings/main.py#L288-L327) [tests/test_settings.py#L121-L154](https://github.com/pydantic/pydantic-settings/blob/5927b441848c330853eac74c82358bc283cd3640/tests/test_settings.py#L121-L154)
- Serialization flow: CliApp.serialize builds a CliSettingsSource → _serialized_args walks model fields and parser metadata → _serialize_value converts enums/containers → _flatten_serialized_args orders optional/positional segments, subcommands, and finally verbatim unknown arguments. — [pydantic_settings/main.py#L1008-L1015](https://github.com/pydantic/pydantic-settings/blob/5927b441848c330853eac74c82358bc283cd3640/pydantic_settings/main.py#L1008-L1015) [pydantic_settings/sources/providers/cli.py#L1629-L1674](https://github.com/pydantic/pydantic-settings/blob/5927b441848c330853eac74c82358bc283cd3640/pydantic_settings/sources/providers/cli.py#L1629-L1674) [pydantic_settings/sources/providers/cli.py#L1689-L1728](https://github.com/pydantic/pydantic-settings/blob/5927b441848c330853eac74c82358bc283cd3640/pydantic_settings/sources/providers/cli.py#L1689-L1728)

Every claim links to its cited files at the pinned commit. Citations identify source evidence; they do not establish runtime correctness. Independent CodeVetter scan — not reviewed by upstream maintainers.

## Public product links

- [CodeVetter](https://codevetter.com/)
- [Download](https://codevetter.com/download)
- [Documentation](https://codevetter.com/docs/)
- [Source](https://github.com/Codevetter/codevetter)