Skip to main content
Technology & EngineeringPython Patterns29 lines

Validate Python App Configuration with pydantic-settings

Declare typed settings, verify source precedence, and catch unsafe or incomplete deployment configuration before app startup.

Quick Summary7 lines
Pin pydantic-settings and Pydantic versions. Inventory values the application requires at startup, their allowed ranges, and which runtime supplies them. Declare settings with a BaseSettings model and choose descriptive names and types. Use SettingsConfigDict for configuration appropriate to the project. Differentiate an optional credential from a value that may never be absent in production. Use default values only when they produce safe and understood behavior.

## Key Points

- [Pydantic settings management](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/)
skilldb get python-patterns-skills/pydantic-settingsFull skill: 29 lines
Paste into your CLAUDE.md or agent config

Validate Python App Configuration with pydantic-settings

Write an explicit configuration model

Pin pydantic-settings and Pydantic versions. Inventory values the application requires at startup, their allowed ranges, and which runtime supplies them. Declare settings with a BaseSettings model and choose descriptive names and types. Use SettingsConfigDict for configuration appropriate to the project. Differentiate an optional credential from a value that may never be absent in production. Use default values only when they produce safe and understood behavior.

Use an environment prefix or supported validation alias to clarify deployment variables. If configuration has nested values, document how nested keys are represented and choose a delimiter that cannot collide with unrelated variables. Add field or model checks for invariants the types cannot enforce, such as a URL being present whenever a backend mode is enabled. Keep credential fields protected and avoid logging the entire settings object.

Verify which source wins

Write down source precedence for the installed version and any custom sources. In the ordinary environment, direct initialization, process environment, dotenv, secrets directory, and defaults can interact. CLI or customization can change order. Test which value actually wins when two configured sources provide the same field. A valid value in a developer's shell can conceal an incorrect deployment file.

Construct settings at a controlled application boundary. Pass the resulting object to features that need it, and make tests able to construct fresh settings. If the application caches settings, define how tests clear or replace the cache. Load local dotenv only where the project intends it, rather than making production silently depend on a checkout file. Prefer the deployment's existing secret source for real credentials.

Exercise clean startup and deliberate failure

Use an isolated environment and a temporary dotenv fixture with synthetic values. Verify a default, a dotenv value, an environment override, an alias, and the absence of a required value. Check invalid type and boundary values, and whether unexpected fields in a dotenv source are accepted or rejected by the configured policy. Make tests set or clear only their own variables, restoring them afterward.

Return diagnostics with the setting name and failure category, without dumping secret values. A safe representation or redaction policy needs a negative test because validation errors can include input. Record tested sources, precedence, setting names and deployment assumptions. If a provider-backed secret source is unavailable locally, keep that staging case separate from passing local model tests.

References

Install this skill directly: skilldb add python-patterns-skills

Get CLI access →