sk-python

Escreva e depure Python com atenção às armadilhas que produzem comportamento incorreto silencioso — defaults mutáveis, closures de ligação tardia, cópias rasas, exceções engolidas — além de tipagem, ambiente e empacotamento com uv ou venv, e estrutura de testes com pytest. Use ao escrever um script, serviço ou biblioteca Python, configurar um projeto Python ou depurar um comportamento que parece impossível.

O que é sk-python?

Esta skill fornece um guia abrangente para desenvolvedores Python, focando nas armadilhas sutis que podem levar a bugs silenciosos, difíceis de detectar. Ela cobre desde configuração de ambiente de desenvolvimento com ferramentas modernas como `uv` e `venv`, até tópicos avançados como mutação de coleções durante iteração, consumo de geradores, e boas práticas de tipagem com anotações. A skill também aborda padrões de teste com `pytest`, otimização de desempenho, e decisões de paralelismo com `asyncio`, threads e processos. O objetivo é ajudar desenvolvedores a evitar erros comuns, escrever código mais robusto e configurar projetos Python de forma reprodutível e segura. Ela suporta qualquer plataforma que execute Python (Linux, macOS, Windows) e é agnóstica de editor, sendo útil principalmente em ferramentas como Claude Code, Cursor ou Codex.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/vanhuydotcom/sk-skills/tree/HEAD/skills/sk-python

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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.

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

sk-api

Design and change API contracts (REST, gRPC, protobuf, events) so existing callers keep working, covering resource and method shape, error models, pagination, versioning and the deploy order a breaking change requires. Use when adding or altering an endpoint, message or event, or when judging whether a proposed change breaks a consumer.

sk-code-review

Shows an agent how to design, debug, or review "sk code review" so the concrete output is a code change with a check. The procedure moves through Code review, Establish the diff first, What to look for, in priority order. Use it when a new assignment calls for this craft.

sk-go-service

Implement, extend or debug a handler, service or repository in a Go backend service, covering context propagation, error wrapping, transaction boundaries, tenancy scoping and table-driven tests. Use when writing or changing Go server code, adding an endpoint or gRPC method, touching a repository query, or diagnosing a panic, leak or flaky test in a Go service.

sk-react

Build and fix React and TypeScript components, covering state placement, effect dependencies, data fetching, list rendering and the re-render traps that cause stale or looping UI. Use when writing or changing a React component or hook, debugging stale data, an infinite render loop or a lost input, or reviewing frontend code.

sk-system-design

Design or evaluate a distributed system from its constraints — service boundaries, synchronous versus event-driven communication, consistency, failure behaviour and capacity — and state the trade-off each choice buys. Use when splitting or merging services, choosing between a call and an event, deciding where data lives, reviewing an architecture proposal, or answering a system design question.

Habilidades Relacionadas