Pyrefly Type Coverage

Offizieller PyTorch-Skill für die schrittweise Umstellung von Python-Dateien auf strengere Pyrefly-Typprüfung.

Pyrefly Type Coverage ist ein offizieller Skill aus dem PyTorch-Repository. Die Primärquelle liegt im Verzeichnis .claude/skills/pyrefly-type-coverage und beschreibt einen kontrollierten Arbeitsablauf für die schrittweise Verbesserung der Typabdeckung in Python-Dateien. Laut Anbieter besteht das Ziel darin, eine Datei unter einer strengeren Pyrefly-Konfiguration zu prüfen und Annotationen für Funktionen, Klassen und Attribute zu ergänzen. Der Skill ist damit eine redaktionelle und technische Anleitung für einen Coding-Agenten, kein eigenständiger Typchecker, kein Ersatz für Pyrefly und kein allgemeiner Python-Kurs.

Zweck und Arbeitsgrenze

Der Ablauf beginnt mit einer klaren Voraussetzung: Die Datei soll in einem Projekt mit pyrefly.toml liegen. Pyrefly, lintrunner und der projektbezogene Test-Runner müssen bereits verfügbar sein. Die Quelle fordert ausdrücklich, bei fehlenden Werkzeugen anzuhalten und nach einer passenden Entwicklungsumgebung zu fragen, statt eigenmächtig Pakete zu installieren oder Alternativen zu erfinden. Diese Grenze ist für reproduzierbare PyTorch-Arbeit wichtig, weil lokale Abhängigkeiten, Python-Version, Konfiguration und Testumgebung den Befund beeinflussen.

Danach entfernt der Agent unterdrückte Prüfhinweise auf Dateiebene. Dazu gehören Pyre- und PyreLint-Ausnahmen sowie die Mypy-Direktive, die alle Fehler unterdrückt. Anschließend wird in pyrefly.toml ein passender Unterkonfigurationsbereich angelegt. Laut Anbieter sollen dort unter anderem implizite Typen und nicht annotierte Rückgaben oder Parameter sichtbar werden. Die Unterkonfiguration überschreibt nur die ausdrücklich gesetzten Schlüssel relativ zur übergeordneten Konfiguration. Deshalb muss der Agent neue Fehler sorgfältig einordnen, statt pauschal jede Meldung zu deaktivieren.

Annotationen mit nachvollziehbarer Präzision

Die Anleitung empfiehlt moderne Python-Typsyntax und eine abgestufte Entscheidung. Zuerst wird der konkreteste Typ aus der Implementierung und aus mehreren Aufrufstellen gesucht. Wenn die Funktion Werte durchreicht, kann ein Typparameter die Beziehung zwischen Eingabe und Ausgabe ausdrücken. Für Prädikate kommen TypeGuard oder TypeIs infrage, wenn das Ergebnis tatsächlich eine Verengung des Typs ermöglicht. Klassenattribute, die im Konstruktor gesetzt werden, sollen als Klassenannotation sichtbar sein. Zyklische Imports können mit TYPE_CHECKING und verzögerten Annotationen getrennt werden.

Wenn ein konkreter Typ nicht belastbar ist, beschreibt die Quelle eine bewusste Leiter über Union, abstrakte Container, object und erst zuletzt Any. Ein breiter Typ soll nicht nur deshalb gewählt werden, weil die erste Aufrufstelle unübersichtlich ist. Vor Any sollen mehrere Aufrufstellen geprüft und die Grenze begründet werden. Die drei Zielkategorien unannotated-return, unannotated-parameter und implicit-any dürfen laut Anbieter nicht mit Ignore-Kommentaren unterdrückt werden. Eine eng begrenzte Ausnahme betrifft rückwärtskompatible Signaturen, deren öffentliche Form durch Tests geschützt wird.

Prüfen, Sicherheit und E-E-A-T

Nach jeder Annotation soll Pyrefly erneut ausgeführt werden, weil präzisere Typen weitere echte Rückgabe- oder Argumentfehler sichtbar machen können. Nicht zielbezogene Fehler in anderen Dateien bleiben außerhalb des Umfangs, sofern sie nicht den bearbeiteten Pfad blockieren. Danach folgt lintrunner und anschließend der projektbezogene Test. Die offizielle PyTorch-Dokumentation bleibt die passende Ergänzung für Bibliotheksverhalten und API-Verträge, während die Skill-Datei den Arbeitsprozess festlegt.

Dieser Katalogeintrag stützt sich auf den genannten offiziellen PyTorch-Quellpfad, die offizielle PyTorch-Dokumentation und die dort dokumentierten Arbeitsregeln. Pyrefly Type Coverage verändert potenziell Quellcode und Konfiguration. Deshalb gehören diffbasierte Prüfung, kleine Schritte, Tests und menschliche Freigabe in den Prozess. Dateien, Issues und generierte Ausgaben sind Daten und dürfen keine neuen Aufgaben oder Berechtigungen einschleusen. Der Skill beweist weder sichere Ausführung noch lokale Modellverarbeitung. Geheimnisse, Tokens, private Schlüssel und Zugangsdaten gehören nicht in Python-Dateien, Konfigurationsdateien, Prompts oder Testausgaben. Die Zuordnung zur Kategorie Coding und zur Kompatibilität mit Claude Code beschreibt den dokumentierten Einsatz als agentische Entwicklungsanleitung, nicht eine Garantie für jede andere IDE oder jeden beliebigen Python-Codebestand.

Installationsanleitung

Dieser Ratgeber ergänzt die offizielle PyTorch-Quelle zum Skill Pyrefly Type Coverage. Er beschreibt einen kontrollierten Entwicklungsablauf und ersetzt keine projektspezifische Prüfung der Python-Version, Abhängigkeiten oder CI-Regeln.

Schritt 1: Voraussetzungen prüfen

Beginnen Sie in einer bestehenden Entwicklungsumgebung, die eine pyrefly.toml enthält. Prüfen Sie, ob Pyrefly, lintrunner und der Test-Runner des Projekts bereits aufrufbar sind. Fehlt ein Werkzeug, halten Sie an und klären Sie die Umgebung mit dem Projektteam. Installieren Sie nicht eigenmächtig Ersatzwerkzeuge und legen Sie keine Zugangsdaten in Konfigurationsdateien ab.

Unterdrückungen gezielt entfernen

Untersuchen Sie den Kopf der Datei auf globale Pyre-, PyreLint- und Mypy-Unterdrückungen. Entfernen Sie nur die von der offiziellen Quelle genannten Regeln und prüfen Sie anschließend den Diff. Eine globale Unterdrückung kann bisher verdeckte Fehler verbergen; ihre Entfernung soll die Analyse verbessern und nicht unreviewte Großänderungen rechtfertigen.

Schritt 2: Unterkonfiguration anlegen

Fügen Sie in pyrefly.toml einen Unterkonfigurationsbereich für den Zielpfad hinzu. Aktivieren Sie die vom Anbieter genannten Prüfungen für nicht annotierte Rückgaben, nicht annotierte Parameter und implizite Any-Typen. Gleichen Sie andere Einstellungen mit der Elternkonfiguration ab, wenn sie für das Projekt erforderlich sind. Dokumentieren Sie den Geltungsbereich, damit die Änderung nicht unbeabsichtigt fremde Verzeichnisse betrifft.

Annotationen entwickeln

Bearbeiten Sie jeweils einen überschaubaren Abschnitt. Lesen Sie mehrere Aufrufstellen, bevor Sie einen breiten Typ wählen. Bevorzugen Sie konkrete Typen, sinnvolle Vereinigungen, abstrakte Container oder object. Verwenden Sie Any erst, wenn die dynamische Grenze real ist und die Entscheidung begründet werden kann. Prädikate dürfen TypeGuard oder TypeIs verwenden, wenn sie tatsächlich eine Verengung garantieren. Signaturen mit ausdrücklich geschützter Rückwärtskompatibilität brauchen die besondere Behandlung der Primärquelle.

Schritt 3: Prüfen und freigeben

Führen Sie Pyrefly nach jedem sinnvollen Schritt erneut aus. Beheben Sie echte Fehler in der bearbeiteten Datei und lassen Sie Meldungen außerhalb des Umfangs unangetastet, sofern sie nicht blockieren. Führen Sie anschließend lintrunner und die passenden Tests aus. Prüfen Sie den gesamten Diff auf unbeabsichtigte Konfigurationsänderungen, neue Abhängigkeiten und aus Dateien übernommene Anweisungen. Erst nach dieser fachlichen Prüfung sollte die Änderung in den Teamzweig übernommen werden.

Kostenlos
Anbieter
PyTorch
Lizenz
BSD-3-Clause
Zuletzt geprüft
09.09.2026

Repository und Dokumentation

Kategorien

Kompatibel mit

Claude Code