python-reduce-complexity

Mesure et réduit la complexité du code Python, comptée en jetons lexicaux impératifs par un script intégré. Propose des simplifications, vérifie l'équivalence fonctionnelle de chacune et remesure pour confirmer la baisse du compte.

Qu'est-ce que python-reduce-complexity ?

Cette compétence permet de mesurer et réduire la complexité du code Python en comptant les jetons lexicaux impératifs (exécutant une logique) à l'aide du script `imperative_tokens.py`. Les déclarations (définitions de fonctions/classes, annotations de type, imports, docstrings) ne sont pas comptées, ce qui encourage des refontes significatives comme l'ajout de fonctions auxiliaires. La compétence propose des simplifications, vérifie l'équivalence fonctionnelle de chaque changement (avec une gestion nuancée des différences acceptables), et remesure le code modifié pour confirmer la baisse du compte. Elle fonctionne sur les fichiers `.py` et les notebooks `.ipynb` (avec prise en charge des cellules magiques Python). Elle s'appuie sur une approche systématique : établissement d'une référence initiale, proposition de simplifications (code mort, duplication, utilisation de la bibliothèque standard, etc.), application vérifiée une par une, et rapport détaillé incluant les changements non strictement équivalents avec leur justification. La compétence respecte avant tout les règles du projet (CLAUDE.md) et exige l'accord explicite de l'utilisateur pour toute modification de comportement observable.

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

Installed? Explore more Développement et programmation skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Réduire la complexité Python

Fichiers : $ARGUMENTS

La complexité du code doit de préférence rester faible. La complexité est mesurée comme le nombre de jetons lexicaux Python qui font partie du code impératif : la syntaxe qui exécute quelque chose. Les déclarations organisent le code sans ajouter à sa logique, elles sont donc gratuites.

Ce qui compte

imperative_tokens.py, placé à côté de ce fichier, en est la définition.

Ne sont pas comptés :

  • Les en-têtes def et class, du premier décorateur jusqu'au deux-points qui ouvre le corps : décorateurs, paramètres, valeurs par défaut, classes de base, annotation de retour. Tout cela est évalué une fois, avec la définition, et déclare une interface.
  • Les annotations de type (x: int = 1 compte comme x = 1, un x: int nu comme rien) et les alias type.
  • Les imports, commentaires, docstrings, nouvelles lignes et indentation.
  • Le nom d'un argument nommé dans un appel : f(key=valeur) pèse autant que f(valeur). Passer un argument par mot-clé est préférable dans la plupart des situations, donc cela ne coûte rien.
  • La qualification d'attribut : a.b.c.d pèse autant que d. Un chemin pointé nomme un seul objet. Le compter récompenserait from numpy import log au détriment de np.log, ou un alias local pour self.x, et aucun ne change la logique.

Comptés : tous les autres jetons. Instructions (if, for, while, try, with, return, raise, …), affectations, opérateurs, appels, littéraux, compréhensions et lambdas, avec leurs virgules, deux-points et les deux parenthèses d'une paire. Un appel pèse donc un de plus que l'opérateur qui fait la même chose : a.update(b) fait 4 jetons, a |= b en fait 3.

Pour un notebook (.ipynb), les cellules de code comptent. Une ligne magique ou shell (%config …, !pip …) compte comme l'appel en lequel IPython la transforme. Une cellule sous une magie de cellule (%%bash, %%html) compte 0. L'exception est une magie de cellule qui exécute le corps en tant que Python (les ExecutionMagics d'IPython, comme %%time et %%capture) : la magie compte comme une ligne magique et le corps comme du code. Une magie qui n'est pas intégrée dans l'IPython installé, comme celle d'une extension, compte 0 et le script imprime un avertissement : transmettez cet avertissement dans le rapport. Un notebook dont le noyau n'est pas Python compte 0. Le script importe IPython uniquement lorsqu'on lui donne un notebook Python, et lui demande quelles magies sont intégrées.

Le compte est un indicateur

Un compte plus bas est la preuve d'une simplification, pas la simplification elle-même.

  • Les refontes significatives sont autorisées : une nouvelle fonction d'aide, une nouvelle classe de base, un nouveau fichier. Le compte est alors comparé sur l'ensemble des fichiers affectés (étape 4), donc la logique déplacée entre fichiers s'annule.
  • Nécessite sa propre justification : déplacer la logique là où le script ne regarde pas, c'est-à-dire une valeur par défaut, un argument de décorateur, une expression de classe de base ou une nouvelle dépendance. La proposition indique pourquoi le changement est bon en dehors du compte plus bas.
  • Interdit : du code dans une chaîne pour eval ou exec ou une exécution externe similaire.
  • L'inlining d'une variable utilisée une seule fois n'est acceptable que si cela ne nuit pas à la lisibilité. Un bon nom pour une variable intermédiaire aide le lecteur à comprendre l'intention.
  • Ne sont pas des réductions : supprimer un comportement (validation à une frontière, gestion d'erreur, un cas pris en charge), et troquer la lisibilité contre quelques jetons (une ligne dense, une virgule finale supprimée).

Les propres règles du projet (CLAUDE.md, directives de codage) priment sur le compte.

Changements qui ne sont pas strictement équivalents

Un changement peut altérer le comportement pour simplifier, lorsqu'un argument montre que le programme reste correct. La proposition indique ce qui diffère, sur quelles entrées, et l'argument avec ses preuves dans le code :

  • L'entrée différente ne peut pas se produire. Preuve : le code qui construit ou valide la valeur.
  • Personne n'observe la différence. Preuve : tous les consommateurs de la valeur, listés.
  • La différence est observable mais inoffensive : autre tirage d'un générateur ensemencé, un algorithme plus lent, une erreur levée plus tôt. Cela nécessite l'accord explicite de l'utilisateur. De même pour toute différence qu'une valeur de retour publique, une sortie écrite ou un test peut voir.

Quelques exemples, pour montrer la forme de l'argument. Tout autre changement qui altère le comportement est argumenté de la même manière, qu'il ressemble ou non à l'un de ceux-ci :

Forme simplifiéeRemplaceCe qui diffère
x or defaultx if x is not None else defaultun x faux (0, "", []) est aussi remplacé
zip(a, b)l'indexation des deux par range(len(a))un b plus court tronque silencieusement ; strict=True conserve la vérification
a // bint(a / b)les opérandes négatifs arrondissent dans l'autre sens
max(xs, key=f)sorted(xs, key=f)[-1]en cas d'égalité, le premier des éléments égaux gagne, pas le dernier
xs.sort()xs = sorted(xs)la liste passée par l'appelant est modifiée
Counter(xs)une boucle de comptageune clé manquante renvoie 0 au lieu de lever une exception
un @dataclass, lu comme row.nameun enregistrement dict, lu comme row["name"]l'indexation, .get, le dépaquetage ** et la sérialisation JSON de l'enregistrement cessent de fonctionner

L'argument repose sur le code, pas sur les données d'aujourd'hui : "le fichier n'a pas de doublons" n'en est pas un, et "probablement unique" non plus. Supprimer un comportement reste exclu : une validation à une frontière n'est pas argumentée.

En cas de doute, l'utilisateur décide. Si la preuve est incomplète (un consommateur en dehors du dépôt, une valeur construite par du code qui ne peut pas être lu) ou s'il n'est pas clair qu'une différence est inoffensive, ne tranchez pas. Proposez le changement avec ce qui diffère et ce qui est inconnu, poursuivez avec les autres propositions, et ne l'appliquez qu'avec l'accord de l'utilisateur.

Formes de la bibliothèque standard

Un échantillon de cas fréquents, pour montrer à quoi ressemble un tel remplacement. Ce n'est pas un catalogue : les fonctions intégrées, la bibliothèque standard et les dépendances installées du projet en offrent bien d'autres, et un remplacement qui manque dans le tableau est aussi valable que celui qui y figure.

Forme standardRemplaceCe qui diffère
@dataclass, avec field(default_factory=list), order=True, frozen=Trueun __init__ qui ne fait que stocker ses paramètres ; un __eq__, __repr__, __lt__, __hash__ écrit à la mainune classe qui n'avait pas de __eq__ compare désormais par valeur et n'est pas hachable (eq=False conserve l'identité) ; __eq__ compare aussi la classe ; un None explicite n'est plus la valeur par défaut
any(p(x) for x in xs), all(…), next(filter(p, xs), None)une boucle de drapeau ou de recherche avec breakrien
defaultdict(list)if key not in groups: groups[key] = []lire une clé manquante l'insère
@cache, @cached_propertyun dictionnaire de mémoïsation ; un attribut paresseux if self._x is None@cache sur une méthode conserve chaque instance sur laquelle elle a été appelée ; la propriété est réinitialisée avec del, pas en assignant None
itemgetter("foo"), str.strip, operator.mulun lambda qui ne fait qu'indexer, appeler une méthode ou appliquer un opérateurstr.strip lève une exception sur une valeur qui n'est pas une str
Path(chemin).read_text()with open(chemin) as fichier: et fichier.read()rien
nom.removeprefix(préfixe), ligne.partition("=")startswith et une tranche ; split et une vérification de longueurrien
chain.from_iterable(xss)[x for xs in xss for x in xs]un itérateur : enveloppez-le dans list si le résultat est indexé ou lu deux fois
batched(xs, n)xs[i:i + n] sur range(0, len(xs), n)un itérateur de tuples, pas une liste de tranches
@singledispatchune chaîne isinstancela classe enregistrée la plus spécifique gagne, pas le premier test qui correspond ; l'argument dispatché est le premier, passé par position

@singledispatch et les arguments de @dataclass déplacent la logique dans un en-tête, là où le script ne regarde pas. Leur raison en dehors du compte : les méthodes générées suivent la liste des champs et ne peuvent pas en dériver, et chaque type obtient sa propre fonction, qu'un nouveau type ne touche pas.

D'autres formes n'aident qu'en fonction du contexte, donc elles nécessitent une considération supplémentaire :

  • itertools.product ou itertools.combinations peuvent remplacer une boucle imbriquée.
  • functools.reduce peut remplacer un pli qui n'a pas d'équivalent intégré.

Étapes

  1. Référence. Exécutez le script sur les fichiers de l'argument avec l'interpréteur du projet (Python 3.12 ou ultérieur) et conservez la sortie :

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

    Exécutez les tests maintenant : une suite qui échoue avant le changement ne peut rien vérifier après. Si l'utilisateur a seulement demandé une mesure, rapportez-la et arrêtez-vous.

  2. Proposer. Lisez le code pour ce qu'il calcule, pas pour des motifs à faire correspondre, et demandez pour chaque fonction, boucle et branche si le même résultat peut être exprimé avec moins. Les listes et tableaux de cette compétence montrent à quoi ressemble une simplification. Ils ne sont pas l'espace de recherche : la plupart de ce qui peut disparaître est spécifique au code en question, et aucune liste ne peut l'anticiper. Un passage qui ne vérifie que les motifs listés est incomplet.

    Les trouvailles habituelles, approximativement par ordre de rendement :

    • code mort : fonctions, paramètres et branches inutilisés qui ne peuvent pas être pris ;
    • la même logique écrite deux fois, ici ou dans un autre fichier, qu'un assistant partagé ou une classe de base contiendrait une fois ;
    • du code écrit à la main que la bibliothèque standard, une fonction intégrée ou une dépendance installée fournit déjà ; les utilitaires de la bibliothèque standard comme itertools, functools, operator, collections ou dataclasses peuvent aider, et "Formes de la bibliothèque standard" ci-dessus liste les cas fréquents ;
    • les boucles qui construisent une valeur : une compréhension est généralement meilleure qu'une boucle, et parfois les fonctions intégrées filter ou map sont plus simples qu'une compréhension ;
    • les appels de méthode qu'un opérateur surchargé remplace : a | b pour a.union(b), a |= b pour a.update(b), a @ b pour a.dot(b). Vérifiez d'abord les types des opérandes : |= sur un ensemble nécessite un ensemble, alors que .update() accepte tout itérable ;
    • les branches qui s'effondrent en données (un dictionnaire) ou dans le chemin général ;
    • l'état et les conversions qui n'existent que pour être annulés ;
    • les vérifications défensives loin d'une frontière de programme ;
    • du code plus strict que ses entrées ne le nécessitent, où une forme plus simple ne diffère que sur des entrées qui ne peuvent pas se produire ou de manière que personne n'observe (tableau ci-dessus).

    Puis parcourez le code une fois de plus, les fonctions les plus longues en premier, pour ce qui ne correspond à rien de tout cela : un algorithme ou une structure de données différent qui rend la comptabilité inutile, un calcul réordonné pour qu'un cas particulier disparaisse, une fonction d'une dépendance que le projet utilise déjà qui fait tout le travail, deux fonctions qui diffèrent par une valeur. Une telle proposition est soumise aux mêmes règles que toute autre listée.

    Pour peser un extrait, comme les lignes d'une proposition avant et après, passez-le au script sans argument de fichier. Il imprime le compte seul. L'extrait doit pouvoir être analysé tout seul, donc déindentez-le :

    python "${CLAUDE_SKILL_DIR}/imperative_tokens.py" <<'EOF'
    non_compté |= set(range(premier, dernier))
    EOF
    

    Montrez chaque proposition comme une forme de code, les lignes clés avant et après, avec l'économie attendue en jetons, les autres fichiers qu'elle touche et toute justification ou argument que les sections ci-dessus demandent. Appliquez sur le feu vert de l'utilisateur, ou directement s'il a déjà demandé que les modifications soient faites.

  3. Appliquer et vérifier, une proposition à la fois, pour qu'un échec pointe vers sa cause.

    • Avant la première modification d'un fichier hors de la référence, mesurez-le et ajoutez-le à la référence. Un nouveau fichier commence à 0.
    • Les tests passent, inchangés. Un test modifié en même temps que le code qu'il vérifie ne le vérifie plus ; si l'un doit changer (il appelle un assistant supprimé), dites-le.
    • Les tests qui n'exécutent jamais les lignes modifiées ne prouvent rien. Pour ces lignes, exécutez l'ancienne version (git stash, ou git show HEAD:<chemin> dans un fichier temporaire) et la nouvelle sur les mêmes entrées, cas limites inclus, et comparez les sorties. Les résultats en virgule flottante sont identiques, ou le rapport indique la taille de la différence.
    • Un changement qui n'est pas strictement équivalent est comparé sur les entrées que son argument admet. Vérifiez ensuite l'argument lui-même : lisez le code qui construit la valeur, ou recherchez chaque consommateur. Une preuve qui ne tient pas abandonne la proposition.
    • Un changement de comportement public (une signature, un type d'exception, l'ordre d'une sortie) n'est pas un changement équivalent. Il nécessite l'accord explicite de l'utilisateur.
  4. Remesurer. Exécutez le script sur tous les fichiers affectés : ceux de l'argument et tout autre fichier que le changement a modifié ou créé. Un fichier supprimé se termine à 0. Le total combiné est inférieur au total combiné de la référence, ou le changement est annulé. De même pour celui qui a échoué à l'étape 3.

  5. Rapporter. Par fichier affecté et combiné : jetons avant, après et la différence. Puis ce qui a vérifié l'équivalence (quels tests, quelles comparaisons directes), chaque changement qui n'est pas strictement équivalent, avec ce qui diffère et son argument, chaque changement qui attend la décision de l'utilisateur, et chaque proposition qui a été abandonnée, avec la raison.

Skills associés