Python Exceções Embutidas

Quando algo dá errado, o Python para o programa e mostra o nome de uma exceção (exception, "exceção": um erro que acontece com o programa já rodando), como ValueError ou KeyError, seguido de uma mensagem. Esta página é o dicionário desses nomes: a árvore de famílias, a mensagem real que cada uma mostra no Python 3.14 e quando ela acontece. Para aprender a ler a mensagem inteira, veja a aula Lendo uma Mensagem de Erro; para tratar o erro, try e except.

Onde fica o nome da exceção

Um programa que usa uma variável que não existe:

$ python3 erro_nome.py
Traceback (most recent call last):
  File "/home/ana/erro_nome.py", line 2, in <module>
    print(nome)
          ^^^^
NameError: name 'nome' is not defined. Did you mean: 'nomes'?

Traceback (most recent call last):

"Rastro (a chamada mais recente por último)": o Python vai mostrar o caminho até o erro.

File "…", line 2

O arquivo e a linha onde o erro aconteceu.

^^^^

Os acentos marcam o pedaço exato da linha que deu problema.

NameError

O nome da exceção: é ele que você procura nesta página e é ele que vai no except.

name 'nome' is not defined. Did you mean: 'nomes'?

A explicação: "o nome 'nome' não está definido. Você quis dizer 'nomes'?". O Python 3.14 dá essas dicas quando acha um nome parecido.

A árvore de exceções

As exceções são classes organizadas em famílias, como uma árvore genealógica. Cada uma "é filha" de outra mais geral. Isso importa por um motivo prático: um except pega a exceção que você escreveu e todas as filhas dela. except LookupError pega IndexError e KeyError; except OSError pega todos os erros de arquivo.

Esta é a árvore das exceções embutidas do Python 3.14.4, montada pelo próprio Python no computador da Ana (cada nível de recuo é uma geração):

BaseException                   « a mãe de todas
├── BaseExceptionGroup
├── GeneratorExit
├── KeyboardInterrupt           « Ctrl-C
├── SystemExit                  « sys.exit()
└── Exception                   « a mãe dos erros "normais"
    ├── ArithmeticError         « contas
    │   ├── FloatingPointError
    │   ├── OverflowError
    │   └── ZeroDivisionError
    ├── AssertionError
    ├── AttributeError
    ├── BufferError
    ├── EOFError
    ├── ExceptionGroup          « filha de BaseExceptionGroup também
    ├── ImportError
    │   └── ModuleNotFoundError
    ├── LookupError             « procurar em listas e dicionários
    │   ├── IndexError
    │   └── KeyError
    ├── MemoryError
    ├── NameError
    │   └── UnboundLocalError
    ├── OSError                 « arquivos, pastas, sistema, rede
    │   ├── BlockingIOError
    │   ├── ChildProcessError
    │   ├── ConnectionError
    │   │   ├── BrokenPipeError
    │   │   ├── ConnectionAbortedError
    │   │   ├── ConnectionRefusedError
    │   │   └── ConnectionResetError
    │   ├── FileExistsError
    │   ├── FileNotFoundError
    │   ├── InterruptedError
    │   ├── IsADirectoryError
    │   ├── NotADirectoryError
    │   ├── PermissionError
    │   ├── ProcessLookupError
    │   └── TimeoutError
    ├── ReferenceError
    ├── RuntimeError
    │   ├── NotImplementedError
    │   ├── PythonFinalizationError
    │   └── RecursionError
    ├── StopAsyncIteration
    ├── StopIteration
    ├── SyntaxError
    │   └── IndentationError
    │       └── TabError
    ├── SystemError
    ├── TypeError
    ├── ValueError
    │   └── UnicodeError
    │       ├── UnicodeDecodeError
    │       ├── UnicodeEncodeError
    │       └── UnicodeTranslateError
    └── Warning                 « avisos (veja no fim da página)
        ├── BytesWarning
        ├── DeprecationWarning
        ├── EncodingWarning
        ├── FutureWarning
        ├── ImportWarning
        ├── PendingDeprecationWarning
        ├── ResourceWarning
        ├── RuntimeWarning
        ├── SyntaxWarning
        ├── UnicodeWarning
        └── UserWarning

Você pode perguntar ao Python a "linha da família" de qualquer exceção com __mro__ (a ordem dos ancestrais) ou conferir um parentesco com issubclass ("é subclasse de?"):

print(ZeroDivisionError.__mro__)
print(FileNotFoundError.__mro__)
print(issubclass(KeyError, LookupError))
print(issubclass(KeyboardInterrupt, Exception))

$ python3 familia.py
(<class 'ZeroDivisionError'>, <class 'ArithmeticError'>, <class 'Exception'>, <class 'BaseException'>, <class 'object'>)
(<class 'FileNotFoundError'>, <class 'OSError'>, <class 'Exception'>, <class 'BaseException'>, <class 'object'>)
True
False

A família ajuda a tratar vários erros parecidos de uma vez. O estoque da Ana tem um dicionário e uma lista; procurar algo que não existe dá KeyError num e IndexError na outra, e um único except LookupError pega os dois:

estoque = {"pão": 30, "leite": 12}
prateleira = ["pão", "leite"]

for tentativa in ["café", 5]:
    try:
        if isinstance(tentativa, str):
            print(estoque[tentativa])
        else:
            print(prateleira[tentativa])
    except LookupError as erro:
        print(f"{type(erro).__name__}: {erro}")

$ python3 estoque.py
KeyError: 'café'
IndexError: list index out of range

Os erros do dia a dia

Estas são as exceções que um iniciante encontra quase todo dia.

Erros de escrita (antes de o programa rodar)

SyntaxError ("erro de sintaxe") e suas filhas são diferentes de todas as outras: o Python os encontra lendo o arquivo, antes de rodar a primeira linha. Por isso um try no mesmo arquivo não os pega: o programa nem começa. Cada mensagem abaixo vem com a linha e os ^ que o Python mostrou (arquivo teste.py).

Arquivos, pastas e sistema (família OSError)

Todos estes são filhos de OSError ("erro do sistema operacional"). A mensagem traz um número entre colchetes, o Errno (número do erro no sistema), e o caminho do arquivo.

Os outros erros

Um ExceptionGroup tem um traceback com cara própria, em forma de árvore, um ramo para cada erro do grupo:

$ python3 grupo.py
  + Exception Group Traceback (most recent call last):
  |   File "/home/ana/grupo.py", line 1, in <module>
  |     raise ExceptionGroup("dois erros", [ValueError("nota inválida"), KeyError("café")])
  | ExceptionGroup: dois erros (2 sub-exceptions)
  +-+---------------- 1 ----------------
    | ValueError: nota inválida
    +---------------- 2 ----------------
    | KeyError: 'café'
    +------------------------------------

Os pedidos para parar (fora de Exception)

Avisos (Warning)

Os avisos são da família Warning: em vez de parar o programa, o Python escreve uma linha na saída de erros e continua. Eles servem para dizer "isso funciona, mas cuidado".

$ python3 -c 'import warnings; warnings.warn("cuidado com isso")'
<string>:1: UserWarning: cuidado com isso

Qual nome pôr no except

Experimente

testes = [
    "10 / 0",
    "int('dez')",
    "['pão', 'leite'][5]",
    "{'pão': 4.5}['café']",
    "'Idade: ' + 30",
    "'ana'.upercase()",
    "open('notas.txt')",
]

for codigo in testes:
    try:
        eval(codigo)
    except Exception as erro:
        familia = " → ".join(c.__name__ for c in type(erro).__mro__[:-1])
        print(f"{codigo:24} {familia}")

No computador da Ana (com mais uma linha, import requets, rodada com exec), a saída foi:

$ python3 livre.py
10 / 0                   ZeroDivisionError → ArithmeticError → Exception → BaseException
int('dez')               ValueError → Exception → BaseException
['pão', 'leite'][5]      IndexError → LookupError → Exception → BaseException
{'pão': 4.5}['café']     KeyError → LookupError → Exception → BaseException
'Idade: ' + 30           TypeError → Exception → BaseException
'ana'.upercase()         AttributeError → Exception → BaseException
open('notas.txt')        FileNotFoundError → OSError → Exception → BaseException
import requets           ModuleNotFoundError → ImportError → Exception → BaseException

texto = "dez"
try:
    idade = int(texto)
    print("Daqui a 1 ano:", idade + 1)
except ZeroDivisionError:
    print("Não é um número:", texto)

$ python3 idade.py
Traceback (most recent call last):
  File "/home/ana/idade.py", line 3, in <module>
    idade = int(texto)
ValueError: invalid literal for int() with base 10: 'dez'

texto = "dez"
try:
    idade = int(texto)
    print("Daqui a 1 ano:", idade + 1)
except ZeroDivisionError:
    print("Não é um número:", texto)

texto = "dez"
try:
    idade = int(texto)
    print("Daqui a 1 ano:", idade + 1)
except ValueError:
    print("Não é um número:", texto)

Resumo

• O nome da exceção está no começo da última linha do traceback: NomeDaExceção: explicação.
• As exceções formam uma árvore. except Mãe pega a mãe e todas as filhas: LookupError pega IndexError e KeyError; OSError pega os erros de arquivo; ArithmeticError pega ZeroDivisionError.
• KeyboardInterrupt e SystemExit ficam fora de Exception: por isso o "pega tudo" certo é except Exception, nunca except: sozinho.
• TypeError = tipo errado; ValueError = tipo certo, valor ruim.
• SyntaxError e IndentationError aparecem antes de o programa rodar; um try no mesmo arquivo não os pega.
• Avisos (Warning) não param o programa.