Raising & Chaining

Traduza falhas de baixo nível em erros de domínio sem perder contexto. Use raise ... from, raise sem argumentos e from None intencionalmente para que os tracebacks contem a história completa.

Receita

def load_user(user_id: str) -> dict:
    try:
        return fetch_row(user_id)
    except KeyError as exc:
        raise UserNotFoundError(user_id) from exc

Quando usar isso:

• Envolver exceções de terceiros nos limites da API
• Adicionar contexto de negócio preservando a causa raiz
• Suprimir tracebacks intermediários ruidosos (from None)
• Registrar e depois relançar com raise sem argumentos
• Encadear erros de validação em arquiteturas em camadas

Exemplo de Trabalho

class UserNotFoundError(LookupError):
    def __init__(self, user_id: str) -> None:
        self.user_id = user_id
        super().__init__(f"usuário não encontrado: {user_id}")
 
_DB: dict[str, dict] = {"1": {"name": "Ada"}}
 
def fetch_row(user_id: str) -> dict:
    return _DB[user_id]
 
def get_user(user_id: str) -> dict:
    try:
        return fetch_row(user_id)
    except KeyError as exc:
        raise UserNotFoundError(user_id) from exc
 
def parse_id(raw: str) -> str:
    try:
        value = int(raw)
    except ValueError:
        raise ValueError(f"id inválido: {raw!r}") from None
    if value < 1:
        raise ValueError("id deve ser positivo")
    return str(value)
 
try:
    get_user("999")
except UserNotFoundError as exc:
    print(exc)
    print(exc.__cause__)

O que isso demonstra:

• from exc define __cause__ para depuração de cadeias
• from None oculta os detalhes internos do parser dos consumidores da API
• Exceções de domínio carregam identificadores para manipuladores e logs
• Lançamentos de validação sem argumentos ainda produzem mensagens claras

Mergulho Profundo

Como Funciona

• raise NewError() inicia uma nova exceção no ponto atual do traceback
• raise NewError() from exc vincula exc como __cause__
• raise sem argumentos dentro de except relança a exceção capturada em trânsito
• raise exc de uma variável armazenada pode redefinir o contexto do traceback - prefira raise sem argumentos
• Exception.__context__ pode diferir de __cause__ quando ocorre encadeamento implícito

Escolhas de Encadeamento

Armadilhas

• Perder a causa com raise New() sem from - o contexto implícito ainda pode aparecer, mas é ambíguo. Correção: sempre use from exc ao envolver.
• Engolir com from None em todos os lugares - oculta as causas raiz em operações. Correção: reserve from None para limites de análise de entrada do usuário.
• raise exc após o término do bloco except - o traceback aponta para o local do relançamento. Correção: raise sem argumentos apenas dentro de except ativo.
• Loops de encadeamento - A de B de A em wrappers recursivos. Correção: lance o erro de domínio uma vez no limite.
• Registrar exc_info e depois lançar um tipo diferente sem from - os logs e o traceback discordam. Correção: encadeie ou registre dentro do manipulador que relança sem argumentos.

Alternativas

FAQs

Relacionados

• Hierarquias de Exceção Personalizadas - tipos de domínio
• Noções Básicas de Exceções - estrutura try/except
• Retentativas e Backoff - lançar após retentativas
• Melhores Práticas de Erros e Logging - regras operacionais

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