Configuração & Ambiente

CLIs de produção utilizam camadas de configuração: padrões, arquivo de configuração, variáveis de ambiente e flags de CLI (com a maior precedência). Pydantic Settings automatiza esse padrão.

Receita

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_"}

Quando usar isso:

• Ferramentas CLI com múltiplas fontes de configuração
• Aplicações compatíveis com 12-factor
• Segredos via variáveis de ambiente, padrões via arquivo de configuração

Exemplo de Trabalho

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="Substituir URL da 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"Configuração: {settings.model_dump()}", err=True)
    # usar settings.api_url, settings.api_key, etc.
 
if __name__ == "__main__":
    app()

O que isso demonstra:

• Pydantic Settings carrega de variáveis de ambiente e arquivo .env
• Flags de CLI substituem as configurações carregadas
• env_prefix agrupa variáveis (INVOICE_API_KEY)
• Tipo Path para configuração de diretório

Mergulho Profundo

Precedência (alta para baixa)

1. Flags de CLI
2. Variáveis de ambiente
3. Arquivo .env
4. Arquivo de configuração (TOML/YAML)
5. Padrões de código

Armadilhas

• Segredos em arquivos de configuração enviados para o git - credenciais vazadas. Correção: .env em .gitignore; segredos apenas em variáveis de ambiente.
• Nenhuma validação nos valores de configuração - erros em tempo de execução profundos no código. Correção: Tipos Pydantic validam no momento do carregamento.
• Flag de CLI para cada configuração - inutilizável. Correção: flags apenas para substituições comuns; o restante no arquivo de configuração.
• Nomes de variáveis de ambiente diferentes por ambiente - confusão. Correção: prefixo consistente; documentar em --help.
• Imprimir configuração com segredos - vazados em logs. Correção: model_dump(exclude={"api_key"}) para saída de depuração.

Alternativas

FAQs

Relacionados

• Typer - Substituições de flags de CLI
• Noções Básicas de CLI - Noções básicas de variáveis de ambiente
• Pydantic - validação
• Melhores Práticas de CLI - convenções de configuração

Versões da Stack: Esta página foi 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+, e uv 0.6+.