Erros comuns em Python e como identificá-los e corrigi-los

Python gera muitos tipos de exceções e mensagens de erro. Mesmo desenvolvedores experientes ainda encontram erros comuns que podem interromper o fluxo de trabalho ou produzir resultados incorretos. Este guia foca cinco erros recorrentes: o que significam, por que ocorrem, como repará‑los e como prevenir recaídas.

Importante: definições rápidas

• Erro (error): problema detectado pelo interpretador que impede a execução. Alguns são fatals (não deixam o programa começar).
• Exceção (exception): sinalização de uma condição fora do esperado; pode ser capturada com try/except.

5 IndentationError

O IndentationError aparece quando a indentação do código não está correta. Em Python, blocos lógicos (funções, loops, condicionais) dependem de indentação consistente em vez de chaves.

Por que acontece

• Copiar e colar código entre editores que tratam tabs e espaços de modo diferente.
• Mistura de tabs e espaços na mesma seção do código.
• Falta de indentação após uma linha que exige bloco (por exemplo, for, if, def).

Exemplo comum (erro):

for i in range(5):  
print(i)  

Esse trecho gerará IndentationError porque a linha print(i) não está indentada como parte do bloco do for.

Imagem de exemplo:

Correção:

for i in range(5):
    print(i)

Dicas práticas

• Configure seu editor para mostrar caracteres invisíveis (tabs/espaces).
• Ative a opção “convert tabs to spaces” ou padronize indentação em espaços (PEP 8 recomenda 4 espaços).
• Use linting (flake8, pylint) que aponta misturas de tabs/espaços.

Quando essa solução falha

• Se o arquivo contém caracteres invisíveis não-ASCII (copiados de PDFs), a limpeza automática pode não bastar; reescreva as linhas afetadas.
• Em projetos com arquivos gerados automaticamente, corrija o gerador para emitir indentação consistente.

Heurística rápida

• Se o interpretador aponta uma linha com erro logo após uma declaração : (do/if/for/def/class), verifique a linha seguinte e as que pertencem ao mesmo bloco.

4 SyntaxError

SyntaxError indica que o código viola as regras da linguagem — o interpretador não entende a instrução.

Causas comuns

• Esquecer dois-pontos : em uma declaração que abre bloco (if, for, def, class).
• Parênteses ou aspas não fechados.
• Palavras-chave erradas (por exemplo, esle em vez de else).
• Uso indevido de operadores (ex.: = em vez de ==).
• Nomes de variáveis que colidem com palavras reservadas.

Exemplo visual:

Dicas de depuração

• Leia a mensagem de erro — ela geralmente indica a linha e a posição aproximada.
• Verifique a linha anterior quando o erro aponta para a próxima linha (erros de parênteses/aspas não fechados costumam aparecer na linha seguinte).
• Use um IDE que destaque erros de sintaxe em tempo real.

Exemplo de erro por falta de ::

if x > 0
    print('positivo')

Correção:

if x > 0:
    print('positivo')

Alternativa quando não encontra o erro

• Copie o bloco problemático para um REPL ou executor interativo e vá comentando linhas para isolar a instrução com sintaxe inválida.

3 IndexError

IndexError ocorre quando você tenta acessar uma posição inválida em uma sequência (lista, tupla, string). Em Python os índices começam em zero, então o último índice é len(seq)-1.

Exemplo:

numbers = [1, 2, 3]
print(numbers[1]) # imprime 2
print(numbers[3]) # IndexError: list index out of range

Imagem de exemplo:

Causas frequentes

• Off-by-one (erro de contagem que tenta acessar len(seq)).
• Modificar a lista (inserir/remover) enquanto itera sobre ela.
• Esperar uma lista mais longa do que realmente existe (dados de entrada insuficientes).

Como evitar

• Use for item in seq: em vez de indexação manual, quando possível.
• Cheque if 0 <= index < len(seq): antes de acessar por índice.
• Para remoções durante iteração, itere sobre uma cópia (for x in lista[:]) ou acumule índices para remover depois.

Exemplo seguro:

index = 3
if 0 <= index < len(numbers):
    print(numbers[index])
else:
    print('Índice fora do intervalo')

Quando esse método falha

• Ao trabalhar com estruturas aninhadas (lista de listas), índices errados em um nível interno podem passar despercebidos; verifique cada dimensão.

2 ValueError

ValueError é levantado quando uma função recebe um argumento do tipo certo, mas com valor inadequado.

Exemplo clássico:

int('10')   # retorna 10
int('ten')  # ValueError: invalid literal for int() with base 10: 'ten'

Outro exemplo (operações matemáticas impróprias):

import math
math.sqrt(-5)  # ValueError: math domain error

Imagem de exemplo:

Como tratar

• Valide valores de entrada antes de passar para funções.
• Use try/except ValueError ao converter dados vindos do usuário ou de fontes externas.

Exemplo com tratamento:

try:
    num = input('Digite um número: ')
    num_int = int(num)
except ValueError as e:
    print(f'Entrada inválida: {e}')

Boas práticas

• Normalize entradas (trim, remover separadores de milhar, lidar com vírgula vs ponto em números).
• Em APIs, devolva mensagens claras de validação ao invés de stack traces.

1 AttributeError

AttributeError acontece quando se tenta acessar um atributo ou método que não existe no objeto.

Exemplos:

text = 'hello world'
print(text.push())  # AttributeError: 'str' object has no attribute 'push'

user = None
print(user.name)    # AttributeError: 'NoneType' object has no attribute 'name'

Imagem de exemplo:

Como diagnosticar

• Verifique o tipo do objeto com type(obj) ou isinstance(obj, ClasseEsperada).
• Use dir(obj) para listar atributos e métodos disponíveis.

Prevenção e correção

• Garanta que variáveis não sejam None quando esperado um objeto (inicialize corretamente).
• Evite nomes de variáveis que sobrescrevam classes padrão (ex.: list = ...).
• Documente contratos e tipos (type hints) para reduzir confusões.

Exemplo seguro com verificação:

if user is not None and hasattr(user, 'name'):
    print(user.name)
else:
    print('Usuário sem nome disponível')

Estratégias gerais de depuração

• Leia a mensagem de erro inteira — ela normalmente contém o tipo da exceção, a linha e o traceback.
• Reproduza o erro com um caso mínimo (minimal reproducible example).
• Use prints ou logging para inspecionar valores antes da linha que falha.
• Ferramentas: pdb (depurador), ipdb (depurador interativo), IDEs com breakpoints.

Mini‑metodologia para resolver erros (passos rápidos)

1. Reproduzir: garanta que você pode reproduzir o erro de forma determinística.
2. Isolar: crie um exemplo mínimo que causa o erro.
3. Inspecionar: verifique tipos, valores e estruturas envolvidas.
4. Corrigir: aplique a correção mais simples e testável.
5. Testar: escreva um teste unitário que evite regressão.

Fluxo de decisão rápido (Mermaid)

flowchart TD
  A[Recebeu erro em execução] --> B{O interpretador aponta tipo?}
  B -->|Sim| C{É SyntaxError?}
  B -->|Não| D{Traceback tem linha?}
  C -->|Sim| E[Verificar : parênteses/aspas/palavras-chave]
  C -->|Não| F{IndentationError?}
  F -->|Sim| G[Verificar tabs vs espaços e indentação]
  F -->|Não| H{Index/Attribute/Value?}
  H -->|Index| I[Verificar limites de índices e len'seq']
  H -->|Attribute| J[Verificar tipo, usar dir'' e hasattr'']
  H -->|Value| K[Validar entrada e usar try/except]
  D --> L[Usar prints/logs/pdb para inspecionar variáveis]

Checklists por papel

Checklist — Iniciante

• Verificar se faltam : após if/for/def.
• Conferir indentação (usar 4 espaços).
• Não misturar tabs e espaços.
• Testar pequenos exemplos no REPL.

Checklist — Intermediário

• Usar linter (flake8/pylint) e formatador (black).
• Adicionar type hints básicos e usar mypy quando possível.
• Envolver conversões de tipo com try/except.

Checklist — Avançado

• Escrever testes unitários que cubram casos de borda (valores inválidos, listas vazias, None).
• Automatizar análise estática no CI.
• Padronizar estilo de código no projeto inteiro.

Casos em que as soluções podem falhar

• Dados externos malformados (CSV com encoding inesperado) podem causar exceções não previstas; valide e sanitize entradas.
• Código gerado dinamicamente pode fugir das regras de linting e provocar erros sutis; prefira geradores testados.
• Em aplicações concorrentes, condições de corrida podem produzir estados inesperados que levam a AttributeError ou IndexError intermitentes.

Galeria de casos extremos

• Arquivos com mistura de EOLs (Windows vs Unix) podem confundir ferramentas que fazem parsing; normalizar EOLs no repositório.
• Strings com caracteres invisíveis (zero‑width) que quebram parsing; limpe com normalização Unicode.
• JSON com tipos inesperados (numero vs string) causando ValueError em conversões; use validação de esquema (pydantic, jsonschema).

Glossário (1 linha cada)

• Indentação: espaços/tabs que definem blocos de código em Python.
• Sintaxe: regras que formam um programa válido.
• Índice: posição de um elemento numa sequência, começando em zero.
• Valor inválido: dado com tipo correto, mas inaceitável para a operação.
• Atributo: propriedade ou método disponível em um objeto.

Boas práticas finais

• Integre linting e formatação automática ao commit (pre-commit hooks).
• Adote testes unitários e casos de borda para entradas e estruturas de dados.
• Documente tipos e expectativas de funções (docstrings + type hints).

Resumo

• IndentationError: verifique indentação e tabs vs espaços.
• SyntaxError: procure por :, aspas/parênteses não fechados e palavras-chave erradas.
• IndexError: confirme limites com len() e evite modificar sequências durante iteração.
• ValueError: valide entradas antes de converter; trate com try/except.
• AttributeError: verifique tipos e inicializações; use dir() e hasattr().

Seção final

Python é uma linguagem acessível, mas pequenos erros de sintaxe, estrutura e tipo são parte natural do aprendizado e do desenvolvimento. Com as estratégias acima — isolamento do bug, inspeção de valores, uso de ferramentas (linters, formatadores, depuradores) e cobertura de testes — você reduzirá a frequência desses erros e aumentará a qualidade do seu código.

Notas importantes

Importante: nunca sufoque todas as exceções com um except genérico; capture tipos específicos (ex.: except ValueError:) e registre informações úteis para depuração.

Boas práticas de segurança e privacidade

• Não logue informações sensíveis (senhas, tokens) enquanto depura em produção.
• Em tratamento de erros em APIs, retorne mensagens amigáveis ao usuário e registre stack traces apenas em logs internos.

Obrigado por ler — pratique criando pequenos exemplos para cada erro e escrevendo testes que capturem os comportamentos indesejados.