CS Fundamentals Trainer · Guias

Erros, recursos e testes em Python

A hierarquia de exceções e try/else/finally, encadeamento com from, EAFP contra LBYL (medido), gerenciadores de contexto e ExitStack, e unittest com mocks: substituir onde o nome é usado, spec, independência dos testes, testes instáveis e o que a cobertura significa.

20 min de leitura

Todo programa falha: arquivos somem, redes estouram o tempo limite, usuários digitam bobagens e o código tem bugs. O que separa um programa confiável não é evitar a falha, mas falhar de um jeito que você consiga ver, entender e do qual consiga se recuperar, e achar os bugs antes dos seus usuários. Em Python isso significa três habilidades ligadas entre si: usar bem as exceções, liberar recursos aconteça o que acontecer e escrever testes que falham pelos motivos certos. Este guia cobre as três com scripts rodados no CPython 3.13 (no apêndice). Ele se apoia nos gerenciadores de contexto e geradores de como o Python funciona e de decoradores, geradores e async.

Um limite do que pude rodar: o ambiente tinha o framework padrão unittest, mas não o pytest, então toda execução de testes mostrada aqui é do unittest. A seção sobre pytest o descreve a partir da documentação e não mostra saída própria.

1. Como as exceções funcionam

Uma exceção é um objeto. Quando o código levanta uma, o Python interrompe a função atual, procura um except correspondente em quem a chamou, depois em quem chamou essa, e assim por diante pela pilha; se nenhum corresponde, o programa termina e imprime um traceback, a lista de chamadas que levaram até ali.

A hierarquia

Todas as exceções herdam de BaseException. A maioria das que você encontra herda de Exception, e as padrão são organizadas em famílias: KeyError tem a cadeia KeyError, LookupError, Exception, BaseException, object, então except LookupError captura tanto KeyError quanto IndexError. Três exceções ficam fora de Exception, diretamente sob BaseException: KeyboardInterrupt (Ctrl-C), SystemExit (sys.exit()) e GeneratorExit. Isso é proposital: except Exception não deve impedir o usuário de interromper o programa.

Testei o que um except: sem classe faz com isso. O código que levantou KeyboardInterrupt passou direto por except Exception (correto) e foi engolido por um except: sem classe. Então as regras são:

A instrução try completa

try:
    value = 10 / x
except ZeroDivisionError:
    value = None
else:
    ...        # runs only if the try body did NOT raise
finally:
    ...        # always runs

A ordem dos eventos que registrei: com x = 2 foi try, else, finally; com x = 0 foi try, except, finally. Coloque o mínimo possível no corpo do try, para que um erro sem relação não seja capturado por engano; o código que deve rodar só em caso de sucesso pertence ao else. O finally roda em caso de sucesso, em erros tratados, em erros não tratados e em return, break e continue.

Uma armadilha: return dentro de finally sobrescreve o resultado da função e descarta qualquer exceção em andamento. Uma função com try: return "try" e finally: return "finally" retornou finally. Não use return, break nem continue em um bloco finally.

Encadeamento: mantenha a causa original

Quando você captura um erro e levanta outro, diga como eles se relacionam:

Você escreve__cause____context__O traceback diz
raise AppError(...) from eo ValueError originalo original"The above exception was the direct cause of the following exception"
raise AppError(...) dentro de exceptNoneo ValueError original"During handling of the above exception, another exception occurred"
raise AppError(...) from NoneNoneainda definido, mas oculto (__suppress_context__ é True)apenas a nova exceção

Use from e quando você traduz um erro de baixo nível para o seu (para que a causa continue no log) e from None apenas quando o original é ruído. Um traceback que mostra os dois é muito mais fácil de depurar do que um que mostra só o erro final.

Projete suas próprias exceções

Defina uma pequena hierarquia para a sua aplicação (class AppError(Exception), class ValidationError(AppError)), para que quem chama possa capturar os seus erros sem capturar tudo. Coloque dados na exceção quando o handler precisar deles: meu ValidationError("email", "missing @") carregou field = 'email' e imprimiu email: missing @. Levante exceções para condições excepcionais e deixe os resultados normais serem valores de retorno; não use exceções como forma de devolver um resultado do fundo da lógica normal.

Grupos de exceções (3.11+)

Quando várias coisas falham ao mesmo tempo (tarefas concorrentes, um lote), ExceptionGroup as reúne, e except* trata as partes por tipo. Um grupo de ValueError("a"), TypeError("b") e ValueError("c") deu ValueError part: ['a', 'c'] e TypeError part: ['b']. O asyncio.TaskGroup levanta esses grupos (veja o guia de async). Você não pode usar return, break nem continue dentro de um bloco except*.

Olhe antes de pular, ou peça perdão

O estilo do Python costuma preferir o EAFP ("é mais fácil pedir perdão do que permissão"): tente a operação e trate a exceção, em vez do LBYL (verificar antes). Dois motivos: costuma ser mais limpo, e a verificação pode estar errada quando você agir com base nela. Criei um arquivo, confirmei que os.path.exists() era True, removi o arquivo como outro processo poderia, e então o abri: FileNotFoundError, embora a verificação tivesse passado. Para arquivos, locks e linhas de banco de dados, tente a operação e trate a falha.

Quanto à velocidade, cronometrei uma busca em dicionário um milhão de vezes de cada jeito:

CasoLBYL (if k in d)EAFP (try: d[k])
chave presente50 ms37 ms
chave ausente37 ms130 ms

Tratar uma exceção é barato quando nada é levantado e caro quando algo é. Então use EAFP quando a falha é o caso raro, e uma verificação (ou dict.get) quando a ausência é comum.

2. Recursos: sempre os libere

Arquivos, sockets, locks, conexões de banco de dados e diretórios temporários precisam ser liberados mesmo quando algo falha. A ferramenta é a instrução with (veja como o Python funciona): a limpeza em __exit__ roda de qualquer jeito que o bloco termine.

Evite também vazamentos de recursos em código de longa duração: feche cursores e conexões de banco de dados, ponha timeouts nas chamadas de rede e limite filas e caches.

Logging, não print

Em uma fronteira em que você captura e continua, registre a falha com o traceback: logging.exception("could not process order %s", order_id) dentro de um bloco except registra a mensagem no nível ERROR junto com o traceback completo. Inclua os identificadores de que você precisa para achar o caso depois, e nunca registre segredos nem dados pessoais (veja observabilidade e segurança de aplicações web). Decida para cada erro uma de quatro respostas: tratar (tentar de novo, usar um plano B), traduzir (levantar o seu com from e), deixar propagar (quem chama sabe melhor) ou encerrar (o programa não pode continuar com segurança). Registrar e depois relançar em todos os níveis produz o mesmo erro dez vezes no log; registre uma vez, onde você o trata.

3. Testes

O que é um teste

Um teste é um programa pequeno que executa o seu código com uma entrada conhecida e verifica a saída. Bons testes são rápidos, independentes, repetíveis e legíveis: quando um falha, o nome e a mensagem devem dizer o que quebrou.

Escrevi um pequeno módulo shop.py (um preço com imposto, uma função que busca uma alíquota pela rede, um total e uma verificação de horário de funcionamento) e o testei com o unittest, que vem com o Python. Rode com python3 -m unittest -v. Todos os 11 testes passaram em 0,3 s. O que os testes demonstram:

Casos em tabela. subTest roda um corpo de teste sobre muitas entradas e relata separadamente cada linha que falha: (10, 0.2, 12.0), (0.1, 0.2, 0.12), (19.99, 0.07, 21.39), (0, 0.5, 0.0). Inclua limites e zero. (O pytest faz isso com @pytest.mark.parametrize.)

Ponto flutuante. 0.1 + 0.2 == 0.3 é False; assertAlmostEqual passou. Nunca compare floats com == (use math.isclose ou o auxiliar do framework), e guarde dinheiro em inteiros ou em decimal.Decimal.

Caminhos de falha. assertRaises verifica que a exceção certa é levantada. Um teste que simula um timeout e espera que TimeoutError se propague fixa um comportamento que, de outro modo, só apareceria em produção.

Limites no tempo. A função de horário de funcionamento recebe a hora como parâmetro, então o teste passa 8, 9, 16 e 17 e confere False, True, True, False sem precisar substituir o relógio. Projetar o código para que as dependências sejam passadas de fora (o relógio, o gerador de números aleatórios, o cliente HTTP) é a melhor forma de torná-lo testável, muito melhor do que substituir depois.

Dublês de teste e mocks

Um teste não deve chamar a rede de verdade, enviar e-mail de verdade nem depender da data de hoje. Substitua essas peças por dublês de teste. unittest.mock.patch("shop.fetch_rate", return_value=0.1) substituiu a chamada de rede, o total saiu no esperado 33.0, e assert_called_once_with("BR") verificou como a função foi chamada. Três armadilhas, duas das quais reproduzi:

  1. Substitua o nome onde ele é usado, não onde é definido. O shop.py faz from time import sleep, então shop guarda sua própria referência chamada sleep. Substituir time.sleep não mudou nada: a chamada ainda levou 0,30 s. Substituir shop.sleep a tornou instantânea (0,0006 s). Se uma substituição parece não fazer nada, quase sempre é por isso.
  2. Um Mock simples aceita qualquer coisa. m.no_such_method(1, 2) não levantou nada, então um erro de digitação em um teste pode passar em silêncio. Mock(spec=shop) (ou autospec=True) levanta AttributeError para nomes que o objeto real não tem.
  3. Excesso de mocks testa o mock. Se você substitui tudo em volta do código, o teste verifica as suas suposições sobre essas partes, não o comportamento real. Faça mock das bordas lentas e não determinísticas (rede, relógio, aleatoriedade); use objetos reais, ou falsos rápidos como um banco de dados em memória, para o resto. Acrescente um pequeno número de testes de integração contra a coisa real.

Independência e ordem

Os testes não devem depender uns dos outros. Fiz uma classe em que test_a e test_b acrescentam a uma lista compartilhada no nível da classe e um terceiro teste afirma que a lista tem dois itens. Na execução completa ele passou, só por causa da ordem de execução (alfabética); rodado sozinho, falhou com AssertionError: 0 != 2. Crie o estado por teste em setUp (ou em fixtures), nunca compartilhe estado mutável por variáveis de classe ou de módulo, e rode os testes em ordem aleatória na CI para expor dependências acidentais. Do mesmo modo, dê aos testes seus próprios arquivos temporários e linhas de banco de dados e limpe-os depois.

O que testar e quanto

pytest

A maioria dos projetos Python usa o pytest em vez do unittest; ele não estava disponível onde rodei estes scripts, então isto vem da documentação e não de uma execução. Ele encontra funções chamadas test_*, usa instruções assert simples e as reescreve para mostrar os valores envolvidos quando falham, oferece fixtures (funções que criam e limpam o estado do teste, injetadas por nome nos testes que precisam delas) e @pytest.mark.parametrize para tabelas. Também consegue rodar testes do unittest, então a migração pode ser gradual. Tudo nesta seção (injetar dependências, fazer mock nas bordas, independência, comportamento acima de implementação) vale igualmente.

4. Erros comuns

5. Perguntas que os entrevistadores gostam de fazer

"Qual é a diferença entre except Exception e um except sem classe?"

Um except sem classe captura também subclasses de BaseException, como KeyboardInterrupt e SystemExit, o que dificulta parar o programa. O except Exception captura apenas erros comuns. Prefira uma classe específica.

"Quando o finally roda, e o que pode dar errado?"

Sempre que o bloco try é deixado: normalmente, por exceção ou por return, break ou continue. Um return dentro do finally substitui o valor de retorno original e engole qualquer exceção.

"O que faz o raise ... from e?"

Define __cause__ para que o traceback mostre o erro original como causa direta. from None esconde o original; sem from, o original é mostrado apenas como contexto.

"EAFP ou LBYL?"

O EAFP (tentar e tratar) costuma ser mais limpo e evita corridas entre a verificação e o uso, mas uma exceção levantada é mais lenta que uma verificação, então para um caso de falha comum uma verificação ou dict.get é melhor.

"Como você testaria uma função que chama uma API externa?"

Passe o cliente de fora (ou substitua o nome que a função realmente usa), devolva respostas controladas, teste os caminhos de sucesso, erro e timeout, e acrescente alguns testes de integração contra um sandbox. Use spec ou autospec para que um erro de digitação no mock falhe.

"O que torna um teste instável, e o que fazer?"

Estado compartilhado, dependência de ordem, tempo ou rede reais, aleatoriedade, condições de corrida. Isole o estado por teste, injete o relógio e a semente aleatória, substitua a rede por um dublê, e corrija ou apague o teste em vez de rodá-lo de novo.

"100% de cobertura basta?"

Não. Ela mostra que as linhas foram executadas, não que os resultados foram verificados nem que os casos extremos foram cobertos.

6. Coisas a mencionar em uma entrevista

Resumo rápido

Apêndice: o código dos experimentos

Python 3.13 (CPython), apenas biblioteca padrão (ExceptionGroup e except* exigem 3.11 ou posterior). Rode python3 errors.py para os experimentos de exceções. Para os testes, ponha shop.py e test_shop.py em uma pasta e rode python3 -m unittest -v test_shop; rode python3 -m unittest test_shop.Isolation.test_z_depends_on_the_others sozinho para ver o teste dependente de ordem falhar. O arquivo de testes nunca toca a rede real: a única função que tocaria é sempre substituída. Os tempos variam conforme a máquina.

errors.py: a hierarquia de exceções, try/else/finally, encadeamento, grupos, auxiliares de recursos e os tempos de EAFP:

import timeit, traceback, contextlib, os, tempfile

# 1. hierarchy
print("KeyError mro:", [c.__name__ for c in KeyError.__mro__])
print("KeyboardInterrupt is Exception:", issubclass(KeyboardInterrupt, Exception), "| BaseException:", issubclass(KeyboardInterrupt, BaseException))

# 2. try / except / else / finally order
def flow(x):
    log = []
    try:
        log.append("try"); v = 10 / x
    except ZeroDivisionError:
        log.append("except"); v = None
    else:
        log.append("else")
    finally:
        log.append("finally")
    return log
print(flow(2), flow(0))

# 3. finally runs even on return, and can override it
def f1():
    try: return "try"
    finally: print("  finally ran before returning")
def f2():
    try: return "try"
    finally: return "finally"      # swallows the original return (and any exception)
print(f1(), f2())

# 4. except order: first match wins
try:
    {}["k"]
except LookupError: print("caught as LookupError (parent listed first)")
except KeyError: print("never reached")

# 5. chaining
class AppError(Exception): pass
def load():
    try: int("abc")
    except ValueError as e: raise AppError("bad config") from e
try: load()
except AppError as e: print("cause:", repr(e.__cause__))
def load2():
    try: int("abc")
    except ValueError: raise AppError("bad config")      # implicit chaining
try: load2()
except AppError as e: print("context:", repr(e.__context__), "| cause:", e.__cause__)
def load3():
    try: int("abc")
    except ValueError: raise AppError("bad config") from None
try: load3()
except AppError as e: print("from None -> suppressed:", e.__suppress_context__)

# 6. bare except swallows too much
def risky():
    raise KeyboardInterrupt
try:
    try: risky()
    except Exception: print("except Exception did not catch it")
except KeyboardInterrupt: print("KeyboardInterrupt passed through `except Exception`")
try:
    try: risky()
    except: print("bare except swallowed KeyboardInterrupt")
except KeyboardInterrupt: print("(not reached)")

# 7. custom exception with data
class ValidationError(Exception):
    def __init__(self, field, msg): super().__init__(f"{field}: {msg}"); self.field = field
try: raise ValidationError("email", "missing @")
except ValidationError as e: print(e, "| field:", e.field)

# 8. exception groups
try:
    raise ExceptionGroup("batch", [ValueError("a"), TypeError("b"), ValueError("c")])
except* ValueError as eg: print("ValueError part:", [str(e) for e in eg.exceptions])
except* TypeError as eg: print("TypeError part:", [str(e) for e in eg.exceptions])

# 9. cleanup with ExitStack and suppress
with contextlib.suppress(FileNotFoundError): os.remove("/nonexistent/file"); print("(not printed)")
print("suppress ok")
d = tempfile.mkdtemp(); paths = [os.path.join(d, f"f{i}") for i in range(3)]
with contextlib.ExitStack() as st:
    files = [st.enter_context(open(p, "w")) for p in paths]
    for f in files: f.write("x")
print("all closed:", all(f.closed for f in files))

# 10. EAFP vs LBYL cost
d = {"a": 1}
def lbyl_hit():  return d["a"] if "a" in d else None
def eafp_hit():
    try: return d["a"]
    except KeyError: return None
def lbyl_miss(): return d["z"] if "z" in d else None
def eafp_miss():
    try: return d["z"]
    except KeyError: return None
n = 1_000_000
for name, fn in (("LBYL key present", lbyl_hit), ("EAFP key present", eafp_hit), ("LBYL key missing", lbyl_miss), ("EAFP key missing", eafp_miss)):
    print(f"{name}: {timeit.timeit(fn, number=n)*1e3:.0f} ms per 1M")
# 11. TOCTOU: the check and the use are separate steps
tmp = os.path.join(tempfile.mkdtemp(), "x"); open(tmp, "w").close()
if os.path.exists(tmp):          # check passes ...
    os.remove(tmp)               # ... then something else removes the file
    try: open(tmp)
    except FileNotFoundError: print("exists() was True, open() still failed: FileNotFoundError")
# 12. traceback
try: load2()
except AppError: print(traceback.format_exc().count("During handling of the above exception"), "chained section in traceback")

t/shop.py: o pequeno módulo sob teste:

import json, urllib.request, time
from time import sleep

def price_with_tax(price, rate=0.2):
    return round(price * (1 + rate), 2)

def fetch_rate(country):
    with urllib.request.urlopen(f"https://rates.example/{country}") as r:
        return json.load(r)["rate"]

def total(items, country):
    rate = fetch_rate(country)
    return round(sum(price_with_tax(p, rate) for p in items), 2)

def is_open(now=None):
    now = now if now is not None else time.localtime()
    return 9 <= now.tm_hour < 17

def pause():
    sleep(0.3)            # imported name: it lives in this module's namespace as shop.sleep

t/test_shop.py: os testes, com casos em tabela, mocks e a demonstração de independência:

import time
import unittest
from unittest import mock
import shop

class PriceTests(unittest.TestCase):
    def test_default_rate(self):
        self.assertEqual(shop.price_with_tax(100), 120.0)

    def test_rounding_table(self):
        for price, rate, expected in [(10, 0.2, 12.0), (0.1, 0.2, 0.12), (19.99, 0.07, 21.39), (0, 0.5, 0.0)]:
            with self.subTest(price=price, rate=rate):
                self.assertEqual(shop.price_with_tax(price, rate), expected)

    def test_float_comparison(self):
        self.assertNotEqual(0.1 + 0.2, 0.3)
        self.assertAlmostEqual(0.1 + 0.2, 0.3)

class TotalTests(unittest.TestCase):
    def test_total_with_fake_rate(self):
        with mock.patch("shop.fetch_rate", return_value=0.1) as fake:     # patch where it is USED
            self.assertEqual(shop.total([10, 20], "BR"), 33.0)
            fake.assert_called_once_with("BR")

    def test_network_failure_propagates(self):
        with mock.patch("shop.fetch_rate", side_effect=TimeoutError("slow")):
            with self.assertRaises(TimeoutError):
                shop.total([1], "BR")

class OpeningHoursTests(unittest.TestCase):
    def test_boundaries(self):
        T = lambda h: mock.Mock(tm_hour=h)          # pass the time in; no clock patching needed
        self.assertFalse(shop.is_open(T(8)))
        self.assertTrue(shop.is_open(T(9)))
        self.assertTrue(shop.is_open(T(16)))
        self.assertFalse(shop.is_open(T(17)))

class Isolation(unittest.TestCase):
    shared = []
    def setUp(self): self.local = []
    def test_a(self): self.shared.append(1); self.local.append(1); self.assertEqual(len(self.local), 1)
    def test_b(self): self.shared.append(2); self.local.append(2); self.assertEqual(len(self.local), 1)
    def test_z_depends_on_the_others(self): self.assertEqual(len(self.shared), 2)   # passes only after test_a and test_b

class MockTrap(unittest.TestCase):
    def test_patch_where_it_is_used(self):
        t = time.perf_counter()
        with mock.patch("time.sleep"):              # patches the time module, but shop already holds its own name
            shop.pause()
        slow = time.perf_counter() - t
        t = time.perf_counter()
        with mock.patch("shop.sleep"):              # patches the name shop actually calls
            shop.pause()
        fast = time.perf_counter() - t
        print(f"\n  patch('time.sleep'): {slow:.2f} s | patch('shop.sleep'): {fast:.4f} s")
        self.assertGreater(slow, 0.25); self.assertLess(fast, 0.05)

    def test_mock_accepts_anything(self):
        m = mock.Mock()
        m.no_such_method(1, 2)                      # a plain Mock never complains
        spec = mock.Mock(spec=shop)
        with self.assertRaises(AttributeError):
            spec.no_such_function()                 # spec turns typos into errors

if __name__ == "__main__":
    unittest.main(verbosity=2)

Fontes

  1. Documentação do Python, Errors and Exceptions, Built-in Exceptions (hierarquia, grupos de exceções) e The try statement.
  2. Documentação do Python, contextlib (suppress, ExitStack, contextmanager) e logging (Logger.exception).
  3. Documentação do Python, unittest e unittest.mock, incluindo where to patch.
  4. Python Enhancement Proposals, PEP 3134: Exception Chaining and Embedded Tracebacks e PEP 654: Exception Groups and except*.
  5. Documentação do pytest, Get started, fixtures e parametrize.
  6. Martin Fowler, Mocks Aren't Stubs (2007), sobre dublês de teste.

Pratique este tema: Python

Mais guias