Python
Python é fácil de escrever e fácil de errar sutilmente. Isto cobre as armadilhas que falham silenciosamente e a configuração de projeto que evita um ambiente quebrado.
Armadilhas que falham silenciosamente
Argumentos padrão mutáveis são avaliados uma vez, na definição, e compartilhados por toda chamada:
def add(item, bucket=[]): # errado: bucket persiste entre chamadas
def add(item, bucket=None): # certo
bucket = [] if bucket is None else bucket
Closures têm ligação tardia. Um lambda criado em um loop captura a variável, não seu valor, então cada
um deles vê o valor final. Vincule explicitamente com um argumento padrão, ou use
functools.partial.
is é identidade, não igualdade. Funciona para None, True e False, e para nada mais.
Parece funcionar para inteiros pequenos e strings curtas porque estes são internalizados, que é
exatamente o que faz o bug sobreviver aos testes.
Cópias são rasas. list(xs), xs[:] e dict(d) copiam o contêiner e compartilham os
elementos. Estruturas aninhadas precisam de copy.deepcopy.
Um except: puro captura tudo, incluindo KeyboardInterrupt e SystemExit. Capture a
exceção específica, e nunca escreva except Exception: pass — se for realmente ignorável, registre-a
e diga por quê.
Divisão inteira e igualdade float. / sempre produz um float; // arredonda para baixo em direção ao
infinito negativo, então -7 // 2 é -4. Nunca compare floats com ==; use math.isclose, ou Decimal
para dinheiro.
Iterar uma coleção enquanto a modifica pula elementos. Construa uma nova lista, ou itere uma cópia.
Geradores são consumidos uma vez. Uma segunda passada sobre o mesmo gerador não produz nada, o que parece um resultado vazio em vez de um erro.
Ambiente e empacotamento
Nunca instale no interpretador do sistema. Crie um ambiente virtual por projeto e ative-o,
ou deixe o uv gerenciá-lo:
uv venv && uv pip install -e ".[dev]" # ou: python -m venv .venv
Declare dependências em pyproject.toml, e faça commit de um arquivo de bloqueio para que o ambiente seja
reprodutível. Um requirements.txt com versões não fixadas não é reprodutível e quebrará em uma
máquina futura.
Fixe a versão do Python que o projeto suporta e declare-a em pyproject.toml. O comportamento difere
entre versões menores mais do que as pessoas esperam.
Quando algo importa em um lugar e não em outro, a causa é quase sempre o interpretador
em vez do código. Verifique which python e python -c "import sys; print(sys.executable)"
antes de depurar a importação.
Tipos
Anote assinaturas de funções — parâmetros e retorno. O corpo raramente precisa de anotação; a fronteira sempre precisa, porque é disso que outro código depende.
Execute um verificador de tipos na CI. Anotações que nada verifica ficam desatualizadas e se tornam documentação enganosa.
Use X | None em vez de um opcional-por-convenção puro, e torne a opcionalidade visível na
assinatura. Prefira tipos específicos em vez de Any; quando o tipo é genuinamente desconhecido, use o
equivalente de unknown — object — e restrinja-o, para que o verificador force a restrição.
Para dados estruturados prefira um dataclass, ou um modelo de validação na fronteira onde
os dados chegam de fora. Um dicionário de strings passado entre funções perde toda garantia no
primeiro erro de digitação.
Expressões importantes
Use uma compreensão quando ela mapeia ou filtra, e um loop quando faz qualquer outra coisa. Uma compreensão com efeito colateral ou três cláusulas é mais difícil de ler do que o loop que substituiu.
Use pathlib.Path em vez de caminhos de string, e um gerenciador de contexto para qualquer coisa que precise ser
fechada — arquivos, conexões, travas, diretórios temporários.
Produza a partir de um gerador em vez de construir uma lista quando a entrada for grande ou ilimitada; esta é a diferença entre um script que flui e um que esgota a memória.
Use enumerate, zip, e dict.get com um valor padrão em vez de aritmética de índices e verificações de
pertencimento. Eles são mais rápidos e eliminam uma classe de erro de um a menos.
Testes
pytest, com assert simples. Use @pytest.mark.parametrize para casos orientados por tabela em vez de
um loop dentro de um teste, para que cada caso seja relatado separadamente.
Coloque a configuração compartilhada em uma fixture com o escopo mais estreito que funciona. Uma fixture de escopo de sessão que contém estado mutável vaza entre testes e produz falhas dependentes da ordem.
Afirme a exceção específica com pytest.raises, incluindo a mensagem quando ela importa.
Desempenho, quando importa
Meça antes de otimizar — time.perf_counter para um número aproximado, cProfile para onde o tempo vai.
O ganho usual é mover o trabalho para fora do interpretador: um built-in, uma compreensão, str.join
em vez de concatenação repetida, uma busca em set ou dict em vez de percorrer uma lista, ou uma
chamada de biblioteca vetorizada para trabalho numérico.
Para concorrência limitada por I/O use asyncio ou threads; para trabalho limitado pela CPU use processos, porque a
trava de interpretador global significa que threads não ajudarão.