Gerenciamento de Configuração em Python

Externalize a configuração do código usando variáveis de ambiente e configurações tipadas. Uma configuração bem gerenciada permite que o mesmo código seja executado em qualquer ambiente sem modificação.

Quando Usar Esta Habilidade

• Configurando o sistema de configuração de um novo projeto
• Migrando de valores codificados para variáveis de ambiente
• Implementando pydantic-settings para configuração tipada
• Gerenciando segredos e valores sensíveis
• Criando configurações específicas do ambiente (dev/staging/prod)
• Validando a configuração na inicialização da aplicação

Conceitos Principais

1. Configuração Externalizada

Todos os valores específicos do ambiente (URLs, segredos, flags de recursos) vêm de variáveis de ambiente, não do código.

2. Configurações Tipadas

Analise e valide a configuração em objetos tipados na inicialização, não espalhados pelo código.

3. Falha Rápida

Valide toda a configuração necessária na inicialização da aplicação. Configuração ausente deve falhar imediatamente com uma mensagem clara.

4. Padrões Sensatos

Forneça padrões razoáveis para desenvolvimento local, enquanto exige valores explícitos para configurações sensíveis.

Início Rápido

from pydantic_settings import BaseSettings
from pydantic import Field

class Settings(BaseSettings):
    database_url: str = Field(alias="DATABASE_URL")
    api_key: str = Field(alias="API_KEY")
    debug: bool = Field(default=False, alias="DEBUG")

settings = Settings()  # Loads from environment

Padrões Fundamentais

Padrão 1: Configurações Tipadas com Pydantic

Crie uma classe de configurações central que carrega e valida toda a configuração.

from pydantic_settings import BaseSettings
from pydantic import Field, PostgresDsn, ValidationError
import sys

class Settings(BaseSettings):
    """Application configuration loaded from environment variables."""

    # Database
    db_host: str = Field(alias="DB_HOST")
    db_port: int = Field(default=5432, alias="DB_PORT")
    db_name: str = Field(alias="DB_NAME")
    db_user: str = Field(alias="DB_USER")
    db_password: str = Field(alias="DB_PASSWORD")

    # Redis
    redis_url: str = Field(default="redis://localhost:6379", alias="REDIS_URL")

    # API Keys
    api_secret_key: str = Field(alias="API_SECRET_KEY")

    # Feature flags
    enable_new_feature: bool = Field(default=False, alias="ENABLE_NEW_FEATURE")

    model_config = {
        "env_file": ".env",
        "env_file_encoding": "utf-8",
    }

# Create singleton instance at module load
try:
    settings = Settings()
except ValidationError as e:
    print(f"Configuration error:\n{e}")
    sys.exit(1)

Importe settings em toda a sua aplicação:

from myapp.config import settings

def get_database_connection():
    return connect(
        host=settings.db_host,
        port=settings.db_port,
        database=settings.db_name,
    )

Padrão 2: Falha Rápida em Configuração Ausente

Configurações obrigatórias devem travar a aplicação imediatamente com um erro claro.

from pydantic_settings import BaseSettings
from pydantic import Field, ValidationError
import sys

class Settings(BaseSettings):
    # Required - no default means it must be set
    api_key: str = Field(alias="API_KEY")
    database_url: str = Field(alias="DATABASE_URL")

    # Optional with defaults
    log_level: str = Field(default="INFO", alias="LOG_LEVEL")

try:
    settings = Settings()
except ValidationError as e:
    print("=" * 60)
    print("CONFIGURATION ERROR")
    print("=" * 60)
    for error in e.errors():
        field = error["loc"][0]
        print(f"  - {field}: {error['msg']}")
    print("\nPlease set the required environment variables.")
    sys.exit(1)

Um erro claro na inicialização é melhor do que uma falha None críptica no meio de uma requisição.

Padrão 3: Padrões de Desenvolvimento Local

Forneça padrões sensatos para desenvolvimento local, enquanto exige valores explícitos para segredos.

class Settings(BaseSettings):
    # Has local default, but prod will override
    db_host: str = Field(default="localhost", alias="DB_HOST")
    db_port: int = Field(default=5432, alias="DB_PORT")

    # Always required - no default for secrets
    db_password: str = Field(alias="DB_PASSWORD")
    api_secret_key: str = Field(alias="API_SECRET_KEY")

    # Development convenience
    debug: bool = Field(default=False, alias="DEBUG")

    model_config = {"env_file": ".env"}

Crie um arquivo .env para desenvolvimento local (nunca comite isso):

# .env (adicione ao .gitignore)

…