prompts/docs/skills/pydantic-settings/SKILL.md

name, description, x-personal-mcp

name	description	x-personal-mcp
pydantic-settings	Practical guide for implementing typed application configuration with pydantic-settings. Use when designing BaseSettings models, choosing env naming strategy, configuring dotenv or secrets, and customizing source priority safely.	id version tags capabilities pydantic-settings 1.0.0 python pydantic pydantic-settings configuration env-vars secrets dotenv source-priority resource://skills/pydantic-settings/document

Pydantic Settings Implementation Guide

Use this skill to implement robust, typed application configuration with pydantic-settings in production Python services.

When to Use

• You need a single typed configuration model for app settings.
• You are migrating from ad-hoc os.getenv(...) calls.
• You need predictable precedence across init args, env vars, dotenv files, and secrets.
• You need nested settings models and reliable parsing behavior.
• You need to customize settings sources or source order safely.

Procedure

1. Baseline Model

Create a single settings model for the service boundary:

from pydantic import BaseModel, Field
from pydantic_settings import BaseSettings, SettingsConfigDict


class DatabaseSettings(BaseModel):
  host: str = "localhost"
  port: int = 5432
  user: str
  password: str


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

  debug: bool = False
  log_level: str = "info"
  database: DatabaseSettings
  api_key: str = Field(validation_alias="MY_API_KEY")

Quality gate:

1. Required fields fail fast when missing.
2. Defaults are intentional and safe.

2. Pick Env Naming Rules

1. Choose one prefix and apply it consistently.
2. Use aliases only for compatibility or external contracts.
3. Document whether env names are case-sensitive.

Quality gate:

1. Team can derive env variable names without guessing.
2. Legacy names are supported only where needed.

3. Decide Nested Parsing

For nested models via env vars, configure delimiters intentionally:

model_config = SettingsConfigDict(
  env_prefix="APP_",
  env_nested_delimiter="__",
  env_nested_max_split=1,
)

Typical vars:

1. APP_DATABASE={"host": "db", "port": 5432, "user": "svc", "password": "pw"}
2. APP_DATABASE__HOST=db.internal

Quality gate:

1. Nested overrides behave as expected.
2. Delimiter choice does not collide with field names.

4. Confirm Source Priority

Default priority (higher first):

1. CLI args (if enabled)
2. init kwargs
3. env vars
4. dotenv
5. secrets dir
6. defaults

Only customize when required:

from pydantic_settings import PydanticBaseSettingsSource


@classmethod
def settings_customise_sources(
  cls,
  settings_cls: type[BaseSettings],
  init_settings: PydanticBaseSettingsSource,
  env_settings: PydanticBaseSettingsSource,
  dotenv_settings: PydanticBaseSettingsSource,
  file_secret_settings: PydanticBaseSettingsSource,
) -> tuple[PydanticBaseSettingsSource, ...]:
  return (init_settings, env_settings, dotenv_settings, file_secret_settings)

Quality gate:

1. Priority order is explicit in code.
2. Tests verify conflict resolution.

5. Add Secrets Strategy

1. In local development, dotenv is acceptable for non-production values.
2. In deployed environments, prefer env vars or secret managers.
3. For file-mounted secrets, use secrets_dir.

Example:

model_config = SettingsConfigDict(
  env_prefix="APP_",
  env_file=".env",
  secrets_dir="/run/secrets",
)

Quality gate:

1. No secret literals in repository code.
2. Missing secrets behavior is understood per environment.

6. Add ContextVar-Scoped Constructors And Accessors

When configuration and database resources should be request- or context-scoped, use ContextVar backed constructor and accessor methods.

Example pattern:

from contextlib import contextmanager
from contextvars import ContextVar
from functools import cache

from pydantic import SecretStr
from pydantic_settings import BaseSettings
from sqlmodel import Session, create_engine
from sqlalchemy import Engine


class DbSettings(BaseSettings):
  model_config = {
    "env_prefix": "DB_",
    "extra": "ignore",
  }

  host: str = "localhost"
  port: int = 5432
  username: str
  password: SecretStr

  @property
  def dsn(self) -> str:
    return (
      "postgresql://"
      f"{self.username}:{self.password.get_secret_value()}"
      f"@{self.host}:{self.port}/mydatabase"
    )


_db_settings: ContextVar[DbSettings | None] = ContextVar("db_settings", default=None)
_db_conn: ContextVar[Engine | None] = ContextVar("db_conn", default=None)


def get_db_settings(**kwargs) -> DbSettings:
  settings = _db_settings.get()
  if settings is None:
    settings = DbSettings(**kwargs)
    _db_settings.set(settings)
    cleanup_engine()
  return settings


@cache
def get_db_engine() -> Engine:
  engine = _db_conn.get()
  if engine is None:
    engine = create_engine(get_db_settings().dsn)
    _db_conn.set(engine)
  return engine


def cleanup_engine() -> None:
  engine = _db_conn.get()
  if engine is not None:
    engine.dispose()
    _db_conn.set(None)
    get_db_engine.cache_clear()


@contextmanager
def get_session():
  with Session(get_db_engine()) as session:
    yield session

Design notes:

1. get_db_settings is the constructor/accessor for settings and can accept explicit overrides in tests.
2. get_db_engine is the constructor/accessor for the engine and reuses context-local state.
3. cleanup_engine must run when settings change so stale DSNs do not leak across contexts.
4. get_session centralizes session creation so call sites never build engines directly.

Quality gate:

1. Overriding settings triggers engine cleanup and cache invalidation.
2. No module-level global engine is created outside accessors.
3. Session creation always goes through get_session().

7. Add Focused Resource-Lifecycle Test

Do not add tests that re-validate baseline pydantic-settings functionality (for example env parsing, alias semantics, or source precedence) unless you have custom behavior layered on top.

Minimum test to add (only when an engine accessor exists):

1. assert the database engine is not instantiated more than once for repeated accessor calls in the same lifecycle/context

If the project has no database engine accessor, skip this section.

Suggested invocation:

1. uv run pytest -q

Completion Checks

1. A single typed settings model exists for the service boundary.
2. Source precedence is documented and tested.
3. Env naming conventions and aliases are explicit and stable.
4. Nested parsing behavior is tested when custom parsing behavior is added.
5. Secrets and dotenv usage are environment-appropriate and do not leak sensitive defaults.
6. Validation errors are actionable and fail fast for required values.
7. If an engine accessor exists, engine construction occurs at most once per lifecycle/context.

Output Contract

When this skill is applied, return:

1. Which references were consulted.
2. The chosen source-precedence model and why.
3. The exact parsing and alias decisions made.
4. Any deferred choices and their risk.
5. The validation commands or tests run to confirm behavior.

Use these upstream docs when implementing or reviewing pydantic-settings behavior.

Source Docs

Primary

• Settings Management
• pydantic-settings package repository

Core Concepts

• Field aliases
• Alias choices
• Validation default behavior
• ImportString type

Priority And Sources

• Field value priority
• Customise settings sources
• Other settings source types

Environment And Parsing

• Environment variable names and prefix behavior
• Case sensitivity behavior
• Parsing environment variable values
• Nested model default partial updates

Dotenv And Secrets

• Dotenv support
• Secrets
• Nested secrets