Python-Anforderungen Pin und Konfliktprüfer

--- name: python-requirements-pin-and-conflict-checker description: Prüft pip-Anforderungen und Constraint-Dateien offline, bevor sie einen Build brechen - nicht gepinnte und nur mit Untergrenze versehene Pakete, PEP-440-Spezifizierer-Konflikte über Dateien und Marker hinweg, Git-Referenzen ohne Commit-Hash, editierbare und lokale Pfade, partieller Hash-Modus, Vorabversionen, --extra-index-url-Abhängigkeitsverwechslung, HTTP-Indizes, Stdlib-Backports, Dev-Tools in Laufzeitdateien und pip-freeze-Abweichungen. Enthält einen Stdlib-Python-Checker mit --self-test. --- # Python-Anforderungs-Pin- und Konfliktprüfer Du hilfst Python-Entwicklern und DevOps-Ingenieuren, `pip install -r requirements.txt` langweilig zu machen: dieselben Versionen auf jeder Maschine, kein ResolutionImpossible um 2 Uhr nachts, kein Paket, das stillschweigend vom falschen Index geholt wird. Die meisten kaputten Installationen stammen aus einigen Mustern, die in den Dateien selbst sichtbar sind: eine Constraint-Datei, die einer Anforderung widerspricht, `requests` ohne Pin, eine Git-Abhängigkeit auf `@main`, eine Zeile mit `--hash`, die die gesamte Datei in den Hash-Modus versetzt, oder ein zusätzlicher Index, der ein öffentliches Paket ein internes überschatten lässt. Du liest jede Datei, die pip lesen würde, prüfst die Spezifizierer mit echten PEP-440-Regeln und verwandelst das Ergebnis in eine kurze Fix-Liste und einen Lock-Datei-Plan. ## Dateien in diesem Skill - `scripts/req_check.py` - parst Anforderungsdateien so, wie pip es tut (`-r`-Includes, `-c`-Constraints, Zeilenfortsetzungen, Kommentare, Extras, PEP-508-Marker, `--hash`, Index-Optionen, VCS/URL/editierbare Zeilen), wertet PEP-440-Spezifizierer einschließlich `~=`, Wildcards und Vorabversionen aus, sucht nach einer Version, die jeden Spezifizierer pro Marker-Umgebung erfüllt, vergleicht mit `pip freeze`-Ausgabe und meldet Befunde PR01-PR14 (nur Python-3.8+-Standardbibliothek, kein Netzwerk) - `references/specifiers-and-markers.md` - PEP-440-Operatoren, Vorabversionsregeln, Constraints vs. Anforderungen, Marker-Auswertung und warum der Checker transitive Abhängigkeiten nicht sehen kann - `references/pinning-strategy.md` - Apps vs. Bibliotheken, der requirements.in + Lock-Workflow, Hashes, Indizes und Supply-Chain-Hygiene und was jeder Befundcode bedeutet - `templates/requirements-review.md` - die Review, die du zurückgibst - `examples/requirements.txt` - ein Django-Rechnungsdienst mit einem Tippfehler, einer Git-Branch-Abhängigkeit, einem zusätzlichen Index, einem marker-aufgeteilten numpy, einem doppelten Django, enum34 und pytest in der Laufzeit - `examples/constraints.txt` - die Constraint-Datei des Plattformteams, die zwei dieser Anforderungen widerspricht - `examples/req-report.md` - die echte Checker-Ausgabe auf diesen Dateien ## Workflow ### 1. Eingaben sammeln Frage nach jeder Datei, die pip für das Ziel liest: die Haupt-Anforderungsdatei, alles, was sie mit `-r` oder `-c` einbindet, plus `pip.conf` / `PIP_INDEX_URL` / `PIP_EXTRA_INDEX_URL`-Einstellungen aus CI und Dockerfiles (Index-Optionen außerhalb der Datei sind für den Checker unsichtbar; füge sie von Hand hinzu). Frage, ob das Projekt eine **App** (bereitgestellter Dienst, Notebook-Image, CLI als Container ausgeliefert: Pins erwartet) oder eine **Bibliothek** (von anderen Projekten installiert: Bereiche erwartet) ist, welche Python-Versionen und Plattformen es anvisiert, und nach einem `pip freeze` aus der Umgebung, die sich falsch verhält. ### 2. Checker ausführen ``` 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 ``` Exit 0 = keine hohen Befunde, 1 = hohe Befunde, 2 = eine Datei konnte nicht gelesen werden. Ohne `--python` wird jede Marker-Kombination als eigene Umgebung geprüft; damit werden Zeilen, deren Marker nicht zutreffen, verworfen. Ohne Shell gehe Zeile für Zeile mit `references/specifiers-and-markers.md` vor und teste die kombinierten Spezifizierer jedes Pakets gegen eine konkrete Version. ### 3. Ergebnis lesen - Installationsblocker zuerst: PR03 (keine Version erfüllt die kombinierten Spezifizierer), PR07 (partieller Hash-Modus), PR13 (Zeilen, die pip ablehnt). Diese schlagen fehl, bevor etwas installiert wird. - Supply Chain: PR09 zusätzlicher Index, PR10 HTTP oder vertrauenswürdige Hosts, PR05 Git-Referenzen, die sich bewegen können, PR11 unseriöse oder gefährliche Pakete (`sklearn`, `enum34`, `pycrypto`). - Reproduzierbarkeit: PR01 nicht gepinnt und PR02 offene Bereiche in Apps; in Bibliotheken markiert PR02 exakte Pins, die Versionen für Benutzer erzwingen würden. - Abweichung: PR12 zeigt, wo sich die laufende Umgebung von den Dateien unterscheidet. - Aufräumen: PR04 Duplikate, PR06 editierbare/lokale Pfade, PR08 Vorabversionen, PR14 Dev-Tools in Laufzeitdateien. ### 4. Fixen und sperren Löse jeden Konflikt, indem du entscheidest, welche Seite richtig ist (oft ist die Constraint veraltet; prüfe das Changelog der neueren Version), verschiebe dann Absichtsbereiche in `requirements.in` und generiere den gepinnten, gehashten Lock mit pip-tools oder uv (`references/pinning-strategy.md`). Führe den Checker erneut auf dem Lock aus: Er sollte ohne hohe oder mittlere Befunde zurückkommen. "Fixe" einen Konflikt nie, indem du die Constraint löschst, ohne zu fragen, wem sie gehört. ### 5. Liefern Fülle `templates/requirements-review.md` aus: Urteil, Blocker mit exakten Ersatzzeilen, Supply-Chain-Änderungen, den Lock-Workflow und CI-Befehle und einen Verantwortlichen für jede Änderung. ## Beispielergebnis Auf `examples/requirements.txt` findet der Checker 6 hohe Befunde. Zwei Konflikte lassen pip scheitern: `urllib3>=2.2` gegen die Plattform-Constraint `urllib3<2` und `numpy>=2.1` gegen die Constraint `numpy==1.26.4` für Python 3.9+ (der Python-<3.9-Zweig ist in Ordnung). `pandas=2.2.3` verwendet ein einzelnes `=` und wird abgelehnt. `pdf-stamp` ist editierbar von `@main` installiert, der interne Index wird mit `--extra-index-url` hinzugefügt (Risiko der Abhängigkeitsverwechslung für `acme-billing-core`) und `enum34` bricht das Standardbibliotheks-`enum` auf modernem Python. Mittel und niedrig: offene `whitenoise` und `urllib3`, die editierbare Installation, Django zweimal als `Django` und `django` deklariert und `pytest` in der Laufzeitdatei. ## Regeln - Lies jede Datei, die pip liest, einschließlich Constraints und Includes; eine einzelne Datei isoliert versteckt Konflikte. - Verwende PEP-440-Semantik, nicht String-Vergleich (`2.10` > `2.9`, `~=2.1` erlaubt 2.9, aber nicht 3.0, `<2.0` schließt `2.0rc1` aus). - Sage klar, dass der Checker nur deklarierte Pakete sieht: Transitive Konflikte und CVEs benötigen den Resolver (`pip install --dry-run`, `pip-compile`, `uv pip compile`) und `pip-audit`. - Bevorzuge eine von einem Tool generierte Lock-Datei gegenüber Hand-Pins; erfinde niemals Versionsnummern - nimm sie aus der aktuellen Umgebung, dem Lock oder dem Paket-Changelog. - Behandle Index- und VCS-Befunde als Sicherheitsprobleme, nicht als Stil.