python-reduzir-complexidade

Mede e reduz a complexidade de código Python, contada como tokens lexicais imperativos por um script incluído. Propõe simplificações, verifica a equivalência funcional de cada uma ou argumenta por que uma diferença não importa, e remede para confirmar a redução na contagem.

O que é python-reduzir-complexidade?

Este agente auxilia desenvolvedores Python a medir e reduzir a complexidade do código, contando tokens lexicais imperativos (sintaxe que executa algo) com o script `imperative_tokens.py`. Ele suporta arquivos .py e notebooks .ipynb, e segue regras claras: declarações, imports, anotações de tipo e qualificações de atributos não contam, enquanto comandos, operadores, chamadas, literais e compreensões são contados. O agente primeiro estabelece uma linha de base, propõe simplificações (como substituir loops por compreensões, usar bibliotecas padrão, remover código morto), aplica e verifica cada mudança quanto à equivalência funcional (argumentando diferenças quando necessário) e remede a complexidade para confirmar a redução. Caso a mudança altere o comportamento, o agente exige justificativa sólida baseada no código (ex.: o valor diferente não pode ocorrer, ninguém observa a diferença), e mudanças que afetam comportamento público ou exigem decisão do usuário são sinalizadas para aprovação explícita. O objetivo não é apenas reduzir a contagem de tokens, mas melhorar a legibilidade e manutenibilidade, respeitando as regras do projeto e evitando reduções que sacrifiquem segurança ou clareza.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/jachymb/skills/tree/main/python-reduce-complexity

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

Reduzir complexidade Python

Arquivos: $ARGUMENTS

A complexidade do código deve ser preferencialmente baixa. A complexidade é medida como o número de tokens lexicais Python que fazem parte do código imperativo: sintaxe que executa algo. Declarações organizam o código sem adicionar lógica, portanto são gratuitas.

O que conta

imperative_tokens.py, ao lado deste arquivo, é a definição.

Não contam:

  • Cabeçalhos de def e class, do primeiro decorador até os dois pontos que abrem o corpo: decoradores, parâmetros, valores padrão, classes base, anotação de retorno. Tudo isso é avaliado uma vez, com a definição, e declara uma interface.
  • Anotações de tipo (x: int = 1 conta como x = 1, x: int puro como nada) e aliases type.
  • Imports, comentários, docstrings, novas linhas e indentação.
  • O nome de um argumento nomeado em uma chamada: f(chave=valor) pesa tanto quanto f(valor). Passar um argumento por nome é preferível na maioria das situações, então não custa nada.
  • Qualificação de atributo: a.b.c.d pesa tanto quanto d. Um caminho pontilhado nomeia um único objeto. Contá-lo recompensaria from numpy import log em vez de np.log, ou um alias local para self.x, e nenhum dos dois altera a lógica.

Contados: todos os outros tokens. Comandos (if, for, while, try, with, return, raise, …), atribuições, operadores, chamadas, literais, compreensões e lambdas, com suas vírgulas, dois pontos e ambos os delimitadores de um par. Uma chamada, portanto, pesa um a mais do que o operador que faz o mesmo: a.update(b) tem 4 tokens, a |= b tem 3.

De um notebook (.ipynb), as células de código contam. Uma linha mágica ou de shell (%config …, !pip …) conta como a chamada em que o IPython a transforma. Uma célula sob uma cell magic (%%bash, %%html) conta 0. A exceção é uma cell magic que executa o corpo como Python (ExecutionMagics do IPython, como %%time e %%capture): a magia conta como uma line magic e o corpo como código. Uma magia que não é embutida no IPython instalado, como uma de uma extensão, conta 0 e o script exibe um aviso: repasse esse aviso no relatório. Um notebook cujo kernel não é Python conta 0. O script importa o IPython apenas quando recebe um notebook Python e pergunta quais magias são embutidas.

A contagem é um proxy

Uma contagem mais baixa é a evidência de uma simplificação, não a simplificação em si.

  • Refatorações significativas são permitidas: uma nova função auxiliar, uma nova classe base, um novo arquivo. A contagem é então comparada em todos os arquivos afetados combinados (etapa 4), então a lógica movida entre arquivos resulta em zero líquido.
  • Requer sua própria justificativa: mover lógica para onde o script não olha, que é um valor padrão, um argumento de decorador, uma expressão de classe base ou uma nova dependência. A proposta declara por que a mudança é boa além da contagem mais baixa.
  • Proibido: código em uma string para eval ou exec ou execução externa similar.
  • Inlining de uma variável usada uma vez é aceitável apenas quando não prejudica a legibilidade. Um bom nome para uma variável intermediária ajuda o leitor a entender a intenção.
  • Não são reduções: remover comportamento (validação em uma fronteira, tratamento de erro, um caso suportado) e trocar legibilidade por alguns tokens (um one-liner denso, uma vírgula final removida).

As próprias regras do projeto (CLAUDE.md, diretrizes de codificação) têm precedência sobre a contagem.

Mudanças que não são estritamente equivalentes

Uma mudança pode alterar o comportamento em prol da simplicidade quando um argumento mostra que o programa permanece correto. A proposta declara o que difere, em quais entradas, e o argumento com sua evidência no código:

  • A entrada diferente não pode ocorrer. Evidência: o código que constrói ou valida o valor.
  • Ninguém observa a diferença. Evidência: todos os consumidores do valor, listados.
  • A diferença é observável, mas inofensiva: outro sorteio de um gerador semeado, um algoritmo mais lento, um erro levantado mais cedo. Isso precisa da concordância explícita do usuário. O mesmo vale para qualquer diferença que um valor de retorno público, saída escrita ou teste possa ver.

Alguns exemplos, para mostrar a forma do argumento. Qualquer outra mudança que altere o comportamento é argumentada da mesma forma, independentemente de se assemelhar a um destes:

Forma mais simplesSubstituiO que difere
x or defaultx if x is not None else defaultum x falso (0, "", []) também é substituído
zip(a, b)indexar ambos por range(len(a))um b mais curto trunca silenciosamente; strict=True mantém a verificação
a // bint(a / b)operandos negativos arredondam para o outro lado
max(xs, key=f)sorted(xs, key=f)[-1]em empate, o primeiro dos itens iguais vence, não o último
xs.sort()xs = sorted(xs)a lista que o chamador passou é mutada
Counter(xs)um loop de contagemuma chave ausente retorna 0 em vez de levantar exceção
um @dataclass, lido como linha.nomeum registro de dicionário, lido como linha["nome"]indexação, .get, desempacotamento ** e serialização JSON do registro param de funcionar

O argumento se baseia no código, não nos dados de hoje: "o arquivo não tem duplicatas" não é um argumento, e "provavelmente único" também não. Remover comportamento continua excluído: validação em uma fronteira não é argumentada.

Quando estiver em dúvida, o usuário decide. Se a evidência estiver incompleta (um consumidor fora do repositório, um valor construído por código que não pode ser lido) ou não for claro se uma diferença é inofensiva, não a resolva de nenhuma forma. Ofereça a mudança com o que difere e o que é desconhecido, prossiga com as outras propostas e aplique-a apenas com a concordância do usuário.

Formas da biblioteca padrão

Uma amostra de casos frequentes, para mostrar a aparência de tal substituição. Não é um catálogo: as funções embutidas, a biblioteca padrão e as dependências instaladas do projeto oferecem muitas outras, e uma substituição que falta na tabela é tão válida quanto uma que está nela.

Forma padrãoSubstituiO que difere
@dataclass, com field(default_factory=list), order=True, frozen=Trueum __init__ que só armazena seus parâmetros; um __eq__, __repr__, __lt__, __hash__ escritos à mãouma classe que não tinha __eq__ agora compara por valor e não é hashable (eq=False mantém identidade); __eq__ também compara a classe; um None explícito não se torna mais o padrão
any(p(x) for x in xs), all(…), next(filter(p, xs), None)um loop de flag ou busca com breaknada
defaultdict(list)if key not in groups: groups[key] = []ler uma chave ausente a insere
@cache, @cached_propertyum dicionário de memo; um atributo lazy if self._x is None@cache em um método mantém cada instância em que foi chamado viva; a propriedade é resetada com del, não atribuindo None
itemgetter("foo"), str.strip, operator.mulum lambda que apenas indexa, chama um método ou aplica um operadorstr.strip levanta exceção em um valor que não é str
Path(caminho).read_text()with open(caminho) as arquivo: e arquivo.read()nada
nome.removeprefix(prefixo), linha.partition("=")startswith e uma fatia; split e uma verificação de comprimentonada
chain.from_iterable(xss)[x for xs in xss for x in xs]um iterador: envolva-o em list onde o resultado é indexado ou lido duas vezes
batched(xs, n)xs[i:i + n] sobre range(0, len(xs), n)um iterador de tuplas, não uma lista de fatias
@singledispatchuma cadeia de isinstancea classe registrada mais específica vence, não o primeiro teste que corresponde; o argumento despachado é o primeiro, passado por posição

@singledispatch e os argumentos de @dataclass movem lógica para um cabeçalho, onde o script não olha. Sua razão além da contagem: os métodos gerados seguem a lista de campos e não podem se desviar dela, e cada tipo ganha uma função própria, que um novo tipo não modifica.

Outras formas só ajudam dependendo do contexto, portanto precisam de consideração adicional:

  • itertools.product ou itertools.combinations podem substituir um loop aninhado.
  • functools.reduce pode substituir uma dobra que não possui função embutida.

Etapas

  1. Linha de base. Execute o script nos arquivos do argumento com o interpretador do projeto (Python 3.12 ou posterior) e mantenha a saída:

    python "${CLAUDE_SKILL_DIR}/imperative_tokens.py" <arquivo.py | notebook.ipynb> [...]
    

    Execute os testes agora: uma suíte que falha antes da mudança não pode verificar nada depois dela. Se o usuário pediu apenas uma medição, reporte-a e pare.

  2. Proponha. Leia o código pelo que ele computa, não por padrões para corresponder, e pergunte de cada função, loop e ramificação se o mesmo resultado pode ser expresso com menos. As listas e tabelas nesta skill mostram a aparência de uma simplificação. Elas não são o espaço de busca: a maior parte do que pode ser removido é específica do código em questão, e nenhuma lista antecipa isso. Uma passagem que apenas verifica os padrões listados é incompleta.

    Os achados comuns, aproximadamente em ordem de rendimento:

    • código morto: funções não utilizadas, parâmetros e ramificações que não podem ser executadas;
    • a mesma lógica escrita duas vezes, aqui ou em outro arquivo, que um auxiliar compartilhado ou classe base manteria uma vez;
    • código escrito à mão que a biblioteca padrão, função embutida ou uma dependência instalada já fornece; utilitários da biblioteca padrão como itertools, functools, operator, collections ou dataclasses podem ajudar, e "Formas da biblioteca padrão" acima lista os casos frequentes;
    • loops que constroem um valor: uma compreensão geralmente é melhor que um loop, e ocasionalmente a função embutida filter ou map é mais simples que uma compreensão;
    • chamadas de método que um operador sobrecarregado substitui: a | b para a.union(b), a |= b para a.update(b), a @ b para a.dot(b). Verifique os tipos dos operandos primeiro: |= em um conjunto precisa de um conjunto, enquanto .update() aceita qualquer iterável;
    • ramificações que colapsam em dados (um mapeamento) ou no caminho geral;
    • estado e conversões que existem apenas para serem desfeitos;
    • verificações defensivas longe de uma fronteira do programa;
    • código mais rigoroso do que suas entradas exigem, onde uma forma mais simples difere apenas em entradas que não podem ocorrer ou de maneiras que ninguém observa (tabela acima).

    Em seguida, percorra o código mais uma vez, as funções mais longas primeiro, em busca do que não se encaixa em nenhum desses: um algoritmo ou estrutura de dados diferente que torna a contabilidade desnecessária, um cálculo reordenado para que um caso especial desapareça, uma função de uma dependência que o projeto já usa e que faz todo o trabalho, duas funções que diferem em um valor. Tal proposta é submetida às mesmas regras de qualquer uma listada.

    Para pesar um trecho, como as linhas de uma proposta antes e depois, direcione-o para o script sem um argumento de arquivo. Ele imprime apenas a contagem. O trecho precisa ser analisável por conta própria, então remova a indentação:

    python "${CLAUDE_SKILL_DIR}/imperative_tokens.py" <<'EOF'
    nao_contado |= set(range(primeiro, ultimo))
    EOF
    

    Mostre cada proposta como forma de código, as linhas-chave antes e depois, com a economia esperada em tokens, os outros arquivos que ela toca e qualquer justificativa ou argumento que as seções acima solicitem. Aplique com o sinal verde do usuário, ou diretamente se ele já pediu que as mudanças fossem feitas.

  3. Aplique e verifique, uma proposta de cada vez, para que uma falha aponte sua causa.

    • Antes da primeira edição em um arquivo fora da linha de base, meça-o e adicione-o à linha de base. Um novo arquivo começa em 0.
    • Os testes passam, inalterados. Um teste editado junto com o código que ele verifica não o verifica mais; se um precisar mudar (ele chama um auxiliar removido), diga isso.
    • Testes que nunca executam as linhas alteradas não provam nada. Para essas linhas, execute a versão antiga (git stash, ou git show HEAD:<caminho> em um arquivo temporário) e a nova nas mesmas entradas, incluindo casos de borda, e compare as saídas. Resultados de ponto flutuante são idênticos, ou o relatório declara o tamanho da diferença.
    • Uma mudança que não é estritamente equivalente é comparada nas entradas que seu argumento admite. Em seguida, verifique o próprio argumento: leia o código que constrói o valor ou procure por cada consumidor. Evidência que não se sustenta descarta a proposta.
    • Uma mudança no comportamento público (uma assinatura, um tipo de exceção, a ordem de uma saída) não é uma mudança equivalente. Ela precisa da concordância explícita do usuário.
  4. Remedeça. Execute o script em todos os arquivos afetados: os do argumento e todos os outros arquivos que a mudança editou ou criou. Um arquivo deletado termina em 0. O total combinado é menor que a linha de base combinada, ou a mudança é revertida. O mesmo vale para uma que falhou na etapa 3.

  5. Reporte. Por arquivo afetado e combinado: tokens antes, depois e a diferença. Em seguida, o que verificou a equivalência (quais testes, quais comparações diretas), toda mudança que não é estritamente equivalente, com o que difere e seu argumento, toda mudança que aguarda a decisão do usuário, e toda proposta que foi descartada, com o motivo.

Habilidades Relacionadas