pydantic-settings

Pydantic Settings

context7: If the context7 tools are available, resolve and load the full pydantic-settings documentation before adding or modifying any settings:

context7_resolve-library-id: "pydantic-settings"
context7_query-docs: <resolved-id> "your query"

All application configuration is managed through the pydantic-settings library. Settings are defined in a single class and loaded from the environment and .env file.

Key Rules

• One settings class: The main Settings class lives at {{cookiecutter.__package_slug}}/conf/settings.py. Always update this existing class — never create a new settings class.
• Secrets use SecretStr or SecretBytes: Any value that is sensitive (passwords, tokens, API keys) must be wrapped in one of these types.
• Optional settings default to None: Never use empty strings as a sentinel for "not set".
• All fields use Field(): Include a description= for every field so operators know what it does.

Pattern

# {{cookiecutter.__package_slug}}/conf/settings.py
from pydantic import Field, SecretStr
from pydantic_settings import BaseSettings, SettingsConfigDict


class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        extra="ignore",
    )

    # Regular setting with a default
    project_name: str = Field(default="{{ cookiecutter.__package_slug }}", description="Human-readable project name")

    # Optional sensitive setting — defaults to None, not empty string
    api_key: SecretStr | None = Field(
        default=None,
        description="API key for external service. Leave unset to disable.",
    )

    # Optional non-sensitive setting
    max_connections: int = Field(
        default=10,
        description="Maximum number of connections",
    )

Accessing Secrets

SecretStr wraps the value to prevent accidental logging. Access the actual value explicitly when needed: