Configuración y Entorno

Las CLIs de producción superponen la configuración: valores predeterminados, archivo de configuración, variables de entorno y flags de CLI (la mayor precedencia). Pydantic Settings automatiza este patrón.

Receta

from pydantic_settings import BaseSettings
 
class Settings(BaseSettings):
    api_url: str = "http://localhost:8000"
    api_key: str = ""
    debug: bool = False
 
    model_config = {"env_prefix": "MYAPP_"}

Cuándo usar esto:

• Herramientas CLI con múltiples fuentes de configuración
• Aplicaciones que cumplen con la regla 12 del manifiesto de las 12 factorías
• Secretos a través de variables de entorno, valores predeterminados a través de archivos de configuración

Ejemplo de Trabajo

from pathlib import Path
from typing import Optional
import typer
from pydantic_settings import BaseSettings, SettingsConfigDict
 
class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_prefix="INVOICE_",
        env_file=".env",
        env_file_encoding="utf-8",
    )
    api_url: str = "https://api.example.com"
    api_key: str = ""
    timeout: float = 30.0
    output_dir: Path = Path("./output")
 
app = typer.Typer()
 
@app.command()
def sync(
    api_url: Optional[str] = typer.Option(None, help="Sobrescribir URL de la API"),
    debug: bool = typer.Option(False, "--debug"),
):
    settings = Settings()
    if api_url:
        settings = settings.model_copy(update={"api_url": api_url})
    if debug:
        typer.echo(f"Configuración: {settings.model_dump()}", err=True)
    # usar settings.api_url, settings.api_key, etc.
 
if __name__ == "__main__":
    app()

Lo que esto demuestra:

• Pydantic Settings carga desde variables de entorno y archivo .env
• Los flags de CLI sobrescriben la configuración cargada
• env_prefix agrupa las variables en un namespace (INVOICE_API_KEY)
• Tipo Path para la configuración de directorios

Análisis Detallado

Precedencia (de mayor a menor)

1. Flags de CLI
2. Variables de entorno
3. Archivo .env
4. Archivo de configuración (TOML/YAML)
5. Valores predeterminados en el código

Errores Comunes

• Secretos en archivos de configuración subidos a git - credenciales expuestas. Solución: .env en .gitignore; secretos solo en variables de entorno.
• Sin validación en los valores de configuración - errores en tiempo de ejecución profundos en el código. Solución: Los tipos de Pydantic validan en el momento de la carga.
• Flag de CLI para cada configuración - inutilizable. Solución: flags solo para sobrescrituras comunes; el resto en el archivo de configuración.
• Nombres de variables de entorno diferentes por entorno - confusión. Solución: prefijo consistente; documentar en --help.
• Imprimir configuración con secretos - expuestos en los logs. Solución: model_dump(exclude={"api_key"}) para la salida de depuración.

Alternativas

Preguntas Frecuentes

Relacionado

• Typer - Sobrescrituras de flags de CLI
• Conceptos básicos de CLI - Conceptos básicos de variables de entorno
• Pydantic - Validación
• Mejores prácticas de CLI - Convenciones de configuración

Versiones de la pila: Esta página fue escrita para Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.