Warnings & Deprecations

O módulo warnings sinaliza problemas recuperáveis e deprecações de API sem levantar exceções. Configure filtros para exibir, ignorar ou escalar avisos - bibliotecas usam DeprecationWarning para remoções agendadas.

Receita

import warnings
 
warnings.warn("old_api está depreciado; use new_api", DeprecationWarning, stacklevel=2)

Quando usar isso:

• Depreciar funções/classes antes da remoção
• Avisos em tempo de execução sobre uso subótimo (não erros)
• Mantenedores de bibliotecas avisam sem quebrar chamadores imediatamente
• CI -W error transforma avisos em falhas de teste
• Distinguir código do usuário (UserWarning) de código interno (DeprecationWarning)

Exemplo Funcional

import warnings
 
warnings.simplefilter("default", DeprecationWarning)
 
def old_price(amount: float) -> float:
    warnings.warn(
        "old_price depreciado; use compute_price",
        DeprecationWarning,
        stacklevel=2,
    )
    return amount * 1.1
 
def compute_price(amount: float) -> float:
    return amount * 1.1
 
warnings.filterwarnings("once", category=UserWarning, module=__name__)
 
def maybe_risky(flag: bool) -> None:
    if flag:
        warnings.warn("caminho experimental habilitado", UserWarning, stacklevel=2)
 
old_price(10)
maybe_risky(True)
maybe_risky(True)  # o filtro "once" suprime duplicatas

O que isso demonstra:

• stacklevel=2 aponta o aviso para o chamador, não para o wrapper
• Categoria DeprecationWarning para encerramento de API
• filterwarnings("once") evita spam no log
• Filtros com escopo por categoria e módulo

Mergulho Profundo

Como Funciona

• warnings.warn(message, category, stacklevel) emite WarningMessage
• Padrão: exibe cada aviso uma vez por local para stderr
• warnings.filterwarnings(action, category, ...) controla o comportamento
• pytest.warns afirma avisos em testes
• Decorador @warnings.deprecated (3.13+) para funções

Categorias Comuns

Armadilhas

• Stacklevel incorreto - o aviso culpa a linha da biblioteca. Correção: incremente o stacklevel para cada camada de wrapper.
• DeprecationWarning invisível no REPL - filtros padrão ocultam de não-main. Correção: documente warnings.simplefilter para a entrada do aplicativo ou execute testes com -W default::DeprecationWarning.
• Usar avisos para fluxo de controle - não são exceções, fáceis de perder. Correção: avisos apenas para deprecações, não para lógica de negócios.
• Quebrar CI sem política - -W error falha em qualquer aviso. Correção: trate deprecações como erros, permita temporariamente ruído de terceiros.
• Sem cronograma de remoção na mensagem - os usuários não podem planejar. Correção: inclua a versão de remoção alvo no texto do aviso.

Alternativas

FAQs

Relacionado

• O Módulo Logging - integração com captureWarnings
• Hierarquias de Exceção Personalizadas - quebras drásticas vs avisos suaves
• Melhores Práticas de Erros e Logging - política de deprecação
• Levantando e Encadeando - quando levantar em vez de avisar

Versões de Stack: Esta página foi escrita para Python 3.14.0 (3.14 estável, 3.13 de manutenção), 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+.