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
defetclass, 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 = 1compte commex = 1, unx: intnu comme rien) et les aliastype. - Les imports, commentaires, docstrings, nouvelles lignes et indentation.
- Le nom d'un argument nommé dans un appel :
f(key=valeur)pèse autant quef(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.dpèse autant qued. Un chemin pointé nomme un seul objet. Le compter récompenseraitfrom numpy import logau détriment denp.log, ou un alias local pourself.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
evalouexecou 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ée | Remplace | Ce qui diffère |
|---|---|---|
x or default | x if x is not None else default | un 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 // b | int(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 comptage | une clé manquante renvoie 0 au lieu de lever une exception |
un @dataclass, lu comme row.name | un 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 standard | Remplace | Ce qui diffère |
|---|---|---|
@dataclass, avec field(default_factory=list), order=True, frozen=True | un __init__ qui ne fait que stocker ses paramètres ; un __eq__, __repr__, __lt__, __hash__ écrit à la main | une 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 break | rien |
defaultdict(list) | if key not in groups: groups[key] = [] | lire une clé manquante l'insère |
@cache, @cached_property | un 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.mul | un lambda qui ne fait qu'indexer, appeler une méthode ou appliquer un opérateur | str.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 longueur | rien |
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 |
@singledispatch | une chaîne isinstance | la 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.productouitertools.combinationspeuvent remplacer une boucle imbriquée.functools.reducepeut remplacer un pli qui n'a pas d'équivalent intégré.
Étapes
-
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.
-
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,collectionsoudataclassespeuvent 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
filteroumapsont plus simples qu'une compréhension ; - les appels de méthode qu'un opérateur surchargé remplace :
a | bpoura.union(b),a |= bpoura.update(b),a @ bpoura.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)) EOFMontrez 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.
-
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, ougit 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.
-
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.
-
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.