Vérificateur de conflits et d'épinglage des exigences Python

--- name: python-requirements-pin-and-conflict-checker description: Vérifie les fichiers pip requirements et constraints hors ligne avant qu'ils ne cassent un build - paquets non épinglés et avec uniquement des bornes inférieures, conflits de spécificateurs PEP 440 entre fichiers et marqueurs, références git sans hash de commit, chemins éditables et locaux, mode de hachage partiel, pré-versions, confusion de dépendances --extra-index-url, index http, backports de la bibliothèque standard, outils de développement dans les fichiers d'exécution et dérive de pip freeze. Inclut un vérificateur de la bibliothèque standard Python avec --self-test. --- # Vérificateur d'épinglage et de conflits des exigences Python Vous aidez les développeurs Python et les ingénieurs DevOps à rendre `pip install -r requirements.txt` ennuyeux : les mêmes versions sur chaque machine, pas de ResolutionImpossible à 2 heures du matin, aucun paquet silencieusement récupéré depuis le mauvais index. La plupart des installations cassées proviennent de quelques schémas visibles dans les fichiers eux-mêmes : un fichier de contraintes qui contredit une exigence, `requests` sans épinglage, une dépendance git sur `@main`, une ligne avec `--hash` qui bascule tout le fichier en mode de hachage, ou un index supplémentaire qui permet à un paquet public de masquer un paquet interne. Vous lisez chaque fichier que pip lirait, vérifiez les spécificateurs avec les règles réelles PEP 440, et transformez le résultat en une courte liste de correctifs et un plan de fichier de verrouillage. ## Fichiers dans cette compétence - `scripts/req_check.py` - analyse les fichiers d'exigences comme le fait pip (inclusions `-r`, contraintes `-c`, continuations de ligne, commentaires, extras, marqueurs PEP 508, `--hash`, options d'index, lignes VCS/URL/éditables), évalue les spécificateurs PEP 440 y compris `~=`, les jokers et les pré-versions, recherche une version qui satisfait chaque spécificateur par environnement de marqueur, compare avec la sortie de `pip freeze`, et rapporte les résultats PR01-PR14 (bibliothèque standard Python 3.8+ uniquement, sans réseau) - `references/specifiers-and-markers.md` - opérateurs PEP 440, règles de pré-versions, contraintes vs exigences, évaluation des marqueurs, et pourquoi le vérificateur ne peut pas voir les dépendances transitives - `references/pinning-strategy.md` - applications vs bibliothèques, flux de travail requirements.in + verrouillage, hachages, index et hygiène de la chaîne d'approvisionnement, et ce que signifie chaque code de résultat - `templates/requirements-review.md` - la revue à remettre - `examples/requirements.txt` - un service de facturation Django avec une faute de frappe, une dépendance de branche git, un index supplémentaire, un numpy divisé par marqueur, un Django en double, enum34 et pytest dans l'exécution - `examples/constraints.txt` - le fichier de contraintes de l'équipe plateforme qui contredit deux de ces exigences - `examples/req-report.md` - la sortie réelle du vérificateur sur ces fichiers ## Flux de travail ### 1. Collecter les entrées Demandez chaque fichier que pip lit pour la cible : le fichier d'exigences principal, tout ce qu'il inclut avec `-r` ou `-c`, plus les paramètres `pip.conf` / `PIP_INDEX_URL` / `PIP_EXTRA_INDEX_URL` depuis CI et Dockerfiles (les options d'index hors fichier sont invisibles pour le vérificateur ; ajoutez-les à la main). Demandez si le projet est une **application** (service déployé, image notebook, CLI livré en conteneur : épinglages attendus) ou une **bibliothèque** (installée par d'autres projets : plages attendues), quelles versions Python et plateformes il cible, et un `pip freeze` depuis l'environnement qui se comporte mal. ### 2. Exécuter le vérificateur ``` python3 scripts/req_check.py examples/requirements.txt python3 scripts/req_check.py requirements.txt --python 3.12 --platform linux python3 scripts/req_check.py requirements.txt requirements-dev.txt --installed freeze.txt python3 scripts/req_check.py requirements.txt --mode lib --json python3 scripts/req_check.py --self-test ``` Code de sortie 0 = aucun résultat élevé, 1 = résultats élevés, 2 = un fichier n'a pas pu être lu. Sans `--python`, chaque combinaison de marqueurs est vérifiée comme son propre environnement ; avec, les lignes dont les marqueurs ne s'appliquent pas sont supprimées. Sans shell, allez ligne par ligne avec `references/specifiers-and-markers.md` et testez les spécificateurs combinés de chaque paquet contre une version concrète. ### 3. Lire le résultat - Bloqueurs d'installation en premier : PR03 (aucune version ne satisfait les spécificateurs combinés), PR07 (mode de hachage partiel), PR13 (lignes que pip refuse). Ceux-ci échouent avant que quoi que ce soit ne s'installe. - Chaîne d'approvisionnement : PR09 index supplémentaire, PR10 http ou hôtes de confiance, PR05 références git qui peuvent bouger, PR11 paquets bidon ou dangereux (`sklearn`, `enum34`, `pycrypto`). - Reproductibilité : PR01 non épinglé et PR02 plages ouvertes dans les applications ; dans les bibliothèques, PR02 signale les épinglages exacts qui forceraient des versions sur les utilisateurs. - Dérive : PR12 montre où l'environnement en cours diffère des fichiers. - Nettoyages : PR04 doublons, PR06 chemins éditables/locaux, PR08 pré-versions, PR14 outils de développement dans les fichiers d'exécution. ### 4. Corriger et verrouiller Résolvez chaque conflit en décidant quel côté est correct (souvent la contrainte est obsolète ; vérifiez le journal des modifications de la version plus récente), puis déplacez les plages au niveau de l'intention vers `requirements.in` et générez le verrou épinglé et haché avec pip-tools ou uv (`references/pinning-strategy.md`). Ré-exécutez le vérificateur sur le verrou : il devrait revenir sans résultats élevés ou moyens. Ne "corrigez" jamais un conflit en supprimant la contrainte sans demander qui la possède. ### 5. Livrer Remplissez `templates/requirements-review.md` : verdict, bloqueurs avec lignes de remplacement exactes, changements de chaîne d'approvisionnement, flux de travail de verrouillage et commandes CI, et un propriétaire pour chaque changement. ## Exemple de résultat Sur `examples/requirements.txt`, le vérificateur trouve 6 résultats élevés. Deux conflits font échouer pip : `urllib3>=2.2` contre la contrainte plateforme `urllib3<2`, et `numpy>=2.1` contre la contrainte `numpy==1.26.4` pour Python 3.9+ (la branche Python < 3.9 est correcte). `pandas=2.2.3` utilise un seul `=` et est refusé. `pdf-stamp` est installé en mode éditable depuis `@main`, l'index interne est ajouté avec `--extra-index-url` (risque de confusion de dépendances pour `acme-billing-core`), et `enum34` casse la bibliothèque standard `enum` sur Python moderne. Moyen et faible : `whitenoise` et `urllib3` à plage ouverte, l'installation éditable, Django déclaré deux fois comme `Django` et `django`, et `pytest` dans le fichier d'exécution. ## Règles - Lisez chaque fichier que pip lit, y compris les contraintes et les inclusions ; un seul fichier isolé masque les conflits. - Utilisez la sémantique PEP 440, pas la comparaison de chaînes (`2.10` > `2.9`, `~=2.1` permet 2.9 mais pas 3.0, `<2.0` exclut `2.0rc1`). - Dites clairement que le vérificateur ne voit que les paquets déclarés : les conflits transitifs et les CVE nécessitent le résolveur (`pip install --dry-run`, `pip-compile`, `uv pip compile`) et `pip-audit`. - Préférez un fichier de verrouillage généré par un outil plutôt que des épinglages manuels ; n'inventez jamais de numéros de version - prenez-les depuis l'environnement actuel, le verrou, ou le journal des modifications du paquet. - Traitez les résultats d'index et VCS comme des problèmes de sécurité, pas de style.