Noções Básicas de Exceções

9 exemplos para você começar com Exceções - 6 básicos e 3 intermediários.

Pré-requisitos

• Python 3.14.0 instalado.
• Exceções herdam de BaseException; capture Exception em código de aplicação, não BaseException.

Exemplos Básicos

1. try/except Tipo Específico

Capture apenas a falha que você pode tratar.

def parse_port(text: str) -> int:
    try:
        port = int(text)
    except ValueError:
        raise ValueError(f"porta inválida: {text!r}") from None
    return port

• Capture o tipo de exceção mais restrito que se encaixa.
• Re-lance com contexto ao traduzir erros para chamadores.
• from None suprime a cadeia original quando ela adiciona ruído.

Relacionado: Levantando & Encadeando - preserve tracebacks

2. Cláusula else

Execute código apenas quando nenhuma exceção ocorreu em try.

def load_config(path: str) -> dict:
    try:
        f = open(path, encoding="utf-8")
    except FileNotFoundError:
        return {}
    else:
        with f:
            import json
            return json.load(f)

• else evita executar código que só funciona em caso de sucesso dentro de try (que também capturaria suas exceções).
• Mantém except focado no modo de falha de abertura.
• Emparelhe com with quando o recurso deve ser fechado no caminho de sucesso.

Relacionado: O Módulo logging - registre caminhos de configuração ausentes

3. finally Sempre Executa

A limpeza é executada independentemente de uma exceção ter ocorrido ou não.

lock_acquired = False
try:
    lock_acquired = True  # simula aquisição
    print("seção crítica")
finally:
    if lock_acquired:
        print("libera lock")

• finally é para garantias de liberação/limpeza.
• Não retorne valores de finally - ele substitui os retornos de try/except.
• Prefira with quando o objeto suporta gerenciamento de contexto.

Relacionado: Context Managers como um Padrão - limpeza estruturada

4. Hierarquia de Exceções

Capture uma classe base para tratar uma família de erros.

try:
    int("não-é-um-número")
except (ValueError, TypeError) as exc:
    print(type(exc).__name__, exc)

• A hierarquia embutida agrupa falhas relacionadas (subclasses de OSError).
• Tupla em except captura múltiplos tipos.
• Ordene os manipuladores do específico para o geral ao encadear blocos except.

Relacionado: Hierarquias de Exceções Personalizadas - bases de domínio

5. Re-lance com raise nu

Preserve o traceback original dentro de um bloco except.

def process():
    try:
        risky()
    except ValueError:
        log("valor ruim")  # simula log
        raise

• raise nu re-propaga a exceção ativa com a pilha intacta.
• Use ao registrar ou enriquecer o contexto antes que a falha saia.
• Não use raise exc com uma variável armazenada, a menos que você entenda o encadeamento de traceback.

Relacionado: Levantando & Encadeando - raise ... from

6. Atributos de Exceção

Muitas exceções carregam campos estruturados.

try:
    open("/no/such/file.txt")
except FileNotFoundError as exc:
    print(exc.errno, exc.filename)

• Subclasses de OSError expõem .errno, .filename, .strerror.
• Leia atributos para mensagens voltadas ao usuário e rótulos de métricas.
• Exceções de domínio devem seguir o mesmo padrão com campos personalizados.

Relacionado: Hierarquias de Exceções Personalizadas - projetar campos

Exemplos Intermediários

7. Context Manager Suprime na Saída

Retornar True de __exit__ suprime exceções (raro - use deliberadamente).

from contextlib import suppress
 
with suppress(FileNotFoundError):
    print(open("optional.txt").read())
 
print("continua")

• contextlib.suppress documenta o engolimento intencional.
• Nunca use except: pass nu em código de aplicação.
• Registre erros suprimidos quando eles indicarem problemas de dados, não arquivos opcionais.

Relacionado: Melhores Práticas de Erros & Logging - nunca engula silenciosamente

8. Visão Geral de Grupos de Exceções

Múltiplos erros podem aparecer como um único ExceptionGroup (3.11+).

def failing_tasks():
    raise ExceptionGroup(
        "lote falhou",
        [ValueError("a"), TypeError("b")],
    )
 
try:
    failing_tasks()
except* ValueError as eg:
    print("erros de valor:", len(eg.exceptions))

• except* trata sub-exceções correspondentes dentro de um grupo.
• Grupos de tarefas e código concorrente podem levantar grupos.
• Veja a página dedicada para a semântica completa de except*.

Relacionado: Grupos de Exceções & except* - guia completo

9. Padrão de Registrar e Levantar

Registre o contexto, então falhe - não engula.

import logging
 
log = logging.getLogger(__name__)
 
def charge(amount: float) -> None:
    if amount < 0:
        log.error("valor de cobrança inválido=%s", amount)
        raise ValueError("o valor deve ser não negativo")

• Registre no nível apropriado antes de levantar para operabilidade.
• Inclua campos estruturados (amount=%s) em vez de f-strings nas chamadas de log.
• Chamadores ainda recebem a exceção para controle de fluxo.

Relacionado: Logging Estruturado & Contextual - campos JSON

Versões da Stack: 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+.