chasten
v0.2.0: Merge pull request #81 from AstuteSource
Chasten ist ein Python -Programm, das XPath -Ausdrücke verwendet, um Muster im abstrakten Syntaxbaum (AST) eines Python -Programms zu finden. Sie können Chasten verwenden, um Ihre eigenen konfigurierbaren Lining -Regeln schnell zu implementieren, ohne ein komplexes AST -Analyse -Framework verwenden zu müssen oder auf ungenaue reguläre Ausdrücke zu greifen.
Möchten Sie sicherstellen, dass ein Python-Programm keine dreifache for Schleifen innerhalb von async Funktionen hat? Oder möchten Sie bestätigen, dass jede Funktion in Ihrem Python -Programm Typanmerkungen und einen Docstring -Kommentar enthält? Chasten kann helfen ! Sie können diese Überprüfungen - und viele andere Arten von Analysen auch - in einfachen YAML -Dateien ausdrücken, die XPath -Ausdrücke enthalten.
Chasten (transitives Verb) "jemanden aufmerksam machen oder etwas falsch gemacht haben", Cambridge Dictionary.
Chasten (unzähliges oder singuläres Substantiv) "Ein Tool, das den abstrakten Syntaxbaum eines Python -Programms analysiert, um potenzielle Quellen für Programmiererfehler zu erkennen, um das Programmfehler zu verhindern", Astutesource -Entwickler.
chasten mich daran erinnert hat, Dokstrings und Anmerkungen zu allen Funktionen in main.py zu fügen. Es war leicht zu sehen, was zu reparieren war!"chasten erleichtert es mir leicht zu bestätigen, dass Schülerprogramme die erforderlichen Codierungskonstrukte haben. Es ist viel besser als die Verwendung regulärer Ausdrücke!"chasten es lustig und leicht für mich, eine automatische Analyse einer Python -Codebasis durchzuführen, die ich unterhalte."chasten Analyse -Dashboard, die von mir gesammelten Daten effektiv zu untersuchen." Befolgen Sie die folgenden Schritte, um das chasten Programm zu installieren:
pipx install chasten , um Chasten zu installierenpipx list ein und bestätigen Sie, dass Chasten installiert istchasten --help , um zu lernen, wie man das Tool benutzt Sie können chasten mit zwei YAML -Dateien konfigurieren, die normalerweise config.yml und checks.yml genannt werden. Obwohl chasten eine Startkonfiguration generieren kann, können Sie sich das ansehen? AstutSource/Chasten-Configuration Repository zum Beispiel (n) von Konfigurationsdateien, die das Tool einrichten. Obwohl die Datei config.yml auf mehrere Konfigurationsdateien auf mehrere Prüfung hinweisen kann, zeigt dieses Beispiel an, wie Sie eine einzelne checks.yml angeben.
# chasten configuration
chasten :
# point to a single checks file
checks-file :
- checks.yml Die Datei checks.yml muss eine oder mehrere Überprüfungen enthalten. Was folgt, ist ein Beispiel für eine Check-Konfigurationsdatei mit zwei Überprüfungen, die jeweils die erste ausführbare Zeile von Nicht-Test- und Test-Case-Funktionen in einem Python-Projekt finden. Beachten Sie, dass das pattern den Expression von XPath Version 2.0 angibt, mit dem chasten den angegebenen Typ der Python -Funktion erfasst. Sie können chasten configure validate --config <path to chasten-configuration/ directory | config url> Nachdem <path to chasten-configuration/directory | config url> Mit dem vollqualifizierten Namen Ihres Konfigurationsverzeichnisses und dem Tool bestätigen, dass Ihre Konfiguration der Spezifikation des Tools entspricht. Sie können auch den Befehl chasten configure create verwenden, um automatisch eine Startkonfiguration zu generieren! Tippen chasten configure --help Erklärt, wie das Tool konfiguriert wird.
checks :
- name : " all-non-test-function-definition "
code : " FUNC "
id : " FUNC001 "
description : " First executable line of a non-test function, skipping over docstrings and/or comments "
pattern : ' //FunctionDef[not(contains(@name, "test_"))]/body/Expr[value/Constant]/following-sibling::*[1] | //FunctionDef[not(contains(@name, "test_"))]/body[not(Expr/value/Constant)]/*[1] '
- name : " all-test-function-definition "
code : " FUNC "
id : " FUNC002 "
description : " First executable line of a test function, skipping over docstrings and/or comments "
pattern : ' //FunctionDef[starts-with(@name, "test_")]/body/Expr[value/Constant]/following-sibling::*[1] | //AsyncFunctionDef[starts-with(@name, "test_")]/body/Expr[value/Constant]/following-sibling::*[1] | //FunctionDef[starts-with(@name, "test_")]/body[not(Expr/value/Constant)]/*[1] | //AsyncFunctionDef[starts-with(@name, "test_")]/body[not(Expr/value/Constant)]/*[1] '
count :
min : 1
max : 10 Da chasten ein Projekt mit Python-Quellcode als Eingabe für seinen analysis Subkommando benötigt, können Sie das klonen? Astutsource/LazyTracker und? Astutsource/Multicounter -Repositories, die Gabeln bestehender Python -Projekte sind, die für eine bequeme Analyse erstellt wurden. Um diese beiden Projekte inkrementell mit chasten zu analysieren, können Sie die folgenden Befehle eingeben, um eine Ergebnisse JSON -Datei für jedes Projekt zu erstellen:
subject-data/ Verzeichnis erstellt haben, das ein lazytracker/ Verzeichnis enthält, können Sie den Befehl chasten analyze für das lazytracker -Programm ausführen: chasten analyze lazytracker
--config < path to the chasten-configuration/ directory | config url >
--search-path < path to the lazytracker/ directory >
--save-directory < path to the subject-data/lazytracker/ directory >
--save Jetzt können Sie die Ausgabe scannen, um zu bestätigen, dass chasten beispielsweise 6 Testfunktionen im lazytracker -Projekt findet. Wenn Sie sich im Verzeichnis subject-data/lazytracker ansehen, finden Sie eine JSON-Datei mit einem Namen wie chasten-results-lazytracker-20230823162341-4c23fc443a6b4c4aa09886f1ecb96e9f.json . Wenn Sie in diesem --save mehr als einmal chasten , erzeugen eine neue Ergebnisdatei mit einem anderen Zeitstempel (dh 20230823162341 ) und einer eindeutigen Identifikatorin (dh, 4c23fc443a6b4c4aa09886f1ecb96e9f ).
Nachdem Sie im vorhandenen subject-data/ Verzeichnis ein multicounter/ / Verzeichnis erstellt haben, können Sie den Befehl chasten analyze für das multicounter -Programm ausführen:
chasten analyze multicounter
--config < path to the chasten-configuration/ directory | config url >
--search-path < path to the multicounter/ directory >
--save-directory < path to the subject-data/lazytracker/ directory >
--save Jetzt können Sie die Ausgabe scannen, um zu bestätigen, dass chasten beispielsweise 10 Testfunktionen im multicounter findet. Wenn Sie sich im Verzeichnis subject-data/lazytracker ansehen, finden Sie eine JSON-Datei mit einem Namen wie chasten-results-multicounter-20230821171712-5c52f2f1b61b4cce97624cc34cb39d4f.json multicounter Namenskomponenten.
Da die Überprüfung der all-test-function-definition angibt, dass das Programm zwischen 1 und 10 Tests haben muss, werden Sie feststellen, dass dieser Check sowohl für lazytracker als auch multicounter passt. Dies bedeutet, dass chasten einen 0 -Fehlercode zurückgibt, um an Ihr Betriebssystem zu kommunizieren, das der Scheck übergeben hat.
Sie können mehr über die Verwendung des analyze Unterkommandos erfahren, indem chasten analyze --help eingeben. Zum Beispiel unterstützt chasten die Optionen --check-include und --check-exclude Optionen, mit denen Sie bestimmte Überprüfungen entsprechend den Fuzzy-Übereinstimmungsregeln enthalten und ausschließen können, die Sie für die in der checks.yml angegebenen Attribute eines Schecks angeben können.
Nachdem Sie chasten in den lazytracker und multicounter -Programmen ausgeführt haben, können Sie ihre individuellen JSON -Dateien in eine einzelne JSON -Datei, verwandte CSV -Dateien und eine SQLite -Datenbank integrieren. Sobald Sie ein integrated-data/ Verzeichnis erstellt haben, können Sie diesen Befehl eingeben, um die Integration durchzuführen:
chasten integrate all-programs
< path to subject-data > / ** / * .json
--save-directory < path to the integrated-data/ directory > Dieser Befehl erzeugt ein Verzeichnis wie chasten-flattened-csvs-sqlite-db-all-programs-20230823171016-2061b524276b4299b04359ba30452923/ die eine SQLite-Datenbank, die jeweils Chasten der chasten.db Deichten-Datei und eine csv/ Direktorie enthält. Datenbank.
Sie können mehr über den integrate Unterkommando erfahren, indem chasten integrate --help tippen.
Wenn Sie den Befehl chasten verwenden, kann das Anhängen dieses --verbose -Flaggen Ihre Erlebnisse zur Fehlerbehebung erheblich verbessern und ein detailliertes Verständnis der Funktionalität des Tools vermitteln. Hier ist ein Beispiel mit chasten analyze lazytracker :
chasten analyze lazytracker
--config < path to the chasten-configuration/ directory >
--search-path < path to the lazytracker/ directory >
--save-directory < path to the subject-data/lazytracker/ directory >
--save
--verbose Bei der Ausführung dieses Befehls können Sie erwarten, dass die Ausgabe informative Nachrichten wie Matching source code: Angeben, dass das Tool den Quellcode aktiv mit den angegebenen Mustern vergleichen kann. Darüber hinaus erhalten Sie detaillierte Übereinstimmungsergebnisse und geben Einblicke in die identifizierten Schecks.
Wenn Sie ein interaktives Analyse -Dashboard erstellen möchten, das verwendet? SIMONW/DATASETETE Sie können chasten datasette-serve <path containing integrated results>/chasten.db --port 8001 ausführen. Jetzt können Sie das Dashboard in Ihrem Webbrowser verwenden, um die Ergebnisse zu analysieren, während Sie den Quellcode für diese Projekte mit Ihrem Editor untersuchen! Die Untersuchung der Ergebnisse wird zeigen, dass chasten durch die Verwendung von? Spookylukey/PyastGrep verwendet den XPath-Ausdruck für die all-test-function-definition korrekt, um die erste Zeile des ausführbaren Quellcodes in jedem Test zu finden, das Dokument einer Funktion und führende Kommentare zu überspringen.
Für das lazytracker -Programm werden Sie feststellen, dass chasten Berichte, dass es 6 Testfälle gibt, obwohl pytest nur 5 Tests findet und ausführt. Dies liegt an der Tatsache, dass tests/test_tracked.py Test Suite in lazytracker eine Funktion enthält, die mit test_ in einer anderen Funktion beginnt, beginnend mit test_ . Dieses Beispiel zeigt die Einschränkungen der statischen Analyse mit chasten ! Obwohl das Tool alle "Testfunktionen" korrekt erkannt hat, bedeutet die Verschachtung der Funktionen in der Testsuite, dass pytest die Funktion der äußeren test_ ausführt und die Inner test_ -Funktion für Testzwecke verwendet.
Nachdem dies gesagt ist, findet chasten korrekt jeden der Tests für das multicounter -Projekt. Sie können jeden der vorherigen Schritte in diesem Dokument befolgen, um chasten auf Ihr eigenes Python -Programm anzuwenden!
Wenn Sie Ihr chasten.db für alle zu studieren möchten, können Sie den Unterkommando chasten datasette-publish verwenden. Solange Sie den Installationsanweisungen für befolgt haben? Simonw/Datasette-Publish-Fly und? Mit Simonw/Datasette-Publish-Vercel können Sie die Plugins verwenden, um einen öffentlichen datasette -Server bereitzustellen, auf dem Ihr chasten.db gehostet wird. Zum Beispiel wird das Ausführen des Befehls chasten datasette-publish <path containing integrated results>/chasten.db --platform vercel veröffentlichen die Ergebnisse aus dem Ausführen chasten auf lazytracker und multicounter auf der Vercel-Plattform.
Wichtig ist, dass die Verwendung des Befehls chasten datasette-publish mit der Option --platform vercel müssen zuvor die Anweisungen für das datasette-publish-vercel Plugin befolgt haben, um das Befehlszeilen-Tool vercel zu installieren. Dies ist notwendig, da, obwohl datasette-publish-vercel eine der Abhängigkeiten von chasten ist, weder chasten noch datasette-publish-vercel das vercel Tool bereitstellen, obwohl sie es verwenden. Sie müssen ähnliche Schritte unternehmen, bevor Sie Ihre Datenbank zum Fliegen veröffentlichen!
Obwohl chasten eine Befehlszeilenanwendung ist, erstellen Sie interaktiv die Befehlszeilen- und Optionen des Tools über eine Terminal User Interface (TUI). Um eine TUI-basierte Möglichkeit zu verwenden, um eine vollständige Befehlszeile für chasten zu erstellen, können Sie den Befehl chasten interact .
Chasten hat ein integriertes Systemprotokoll. Während der Verwendung von Chasten können Sie den Befehl chasten log in Ihrem Terminal verwenden. Mit der Systemprotokollfunktion können der Benutzer Ereignisse und Nachrichten sehen, die von chasten erzeugt werden. Darüber hinaus hilft die chasten log Funktion beim Finden von Fehler und den Ereignissen, die zum Fehler geführt haben. Damit das chasten -Programm für das Systemprotokoll angezeigt werden kann, müssen Sie ein separates Terminal öffnen und das Befehl chasten log verwenden. Zusätzlich müssen für jeden Befehl, der das --debug-level <choice of level> und --debug-dest SYSLOG ausführen, hinzugefügt werden.
Beispielsweise wird chasten datasette-serve --debug-level DEBUG --debug-dest SYSLOG < database path to file> die folgende Ausgabe im Systemprotokoll erzeugt.
? chasten: Analyze the AST of Python Source Code
? GitHub: https://github.com/gkapfham/chasten
Syslog server for receiving debugging information
Display verbose output? False
Debug level? DEBUG
Debug destination? SYSLOG
In jedem Befehl in chasten gibt es eine Option, um einen --debug-level hinzuzufügen. Die Debug -Ebene hat 5 Optionen Debug, Info, Warnung, Fehler und kritisch. Jede Stufe zeigt unterschiedliche Probleme im Systemprotokoll, bei dem Debugug die niedrigste Probleme aus der Eingabe ist, bei der kritisch die höchste Fehlerebene ist. Um weitere Informationen dazu zu nutzen, können Sie die Datei debug.py verweisen:
class DebugLevel ( str , Enum ):
"""The predefined levels for debugging."""
DEBUG = "DEBUG"
INFO = "INFO"
WARNING = "WARNING"
ERROR = "ERROR"
CRITICAL = "CRITICAL" Usage: chasten [OPTIONS] COMMAND [ARGS]...
╭─ Options ───────────────────────────────────────────────────────────────────────────────────╮
│ --install-completion Install completion for the current shell. │
│ --show-completion Show completion for the current shell, to copy it or │
│ customize the installation. │
│ --help Show this message and exit. │
╰─────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ──────────────────────────────────────────────────────────────────────────────────╮
│ analyze ? Analyze the AST of Python source code. │
│ configure ? Manage chasten ' s configuration. │
│ datasette-publish ? Publish a datasette to Fly or Vercel. │
│ datasette-serve ? Start a local datasette server. │
│ integrate ? Integrate files and make a database. │
│ interact Interactively configure and run. │
│ log ? Start the logging server. │
╰─────────────────────────────────────────────────────────────────────────────────────────────╯
Befolgen Sie die folgenden Schritte, um das chasten -Tool für die zukünftige Entwicklung zu installieren:
Sobald Python und Poesie installiert sind, gehen Sie bitte zum Chasten -Repository auf GitHub und installieren Sie das Tool mit dem Befehl git clone in Ihrem Terminal. Navigieren Sie dann zum Chasten -Verzeichnis und führen Sie die poetry install um alle Abhängigkeiten zu installieren.
Es gibt auch die Möglichkeit, Docker zu verwenden, um chasten zu verwenden
Befolgen Sie diese Schritte, um Docker zu verwenden:
cd in das Chasten -Verzeichnis, in dem sich die Dockerfile befindetdocker build -t chasten . Um den Behälter zu bauendocker run --rm -v "%cd%":/root/src -it chastendocker run --rm -v ${pwd}:/root/src -it chastendocker run --rm -v $(pwd):/root/src -it chastenpoetry installdocker ps um das Ausführen von Containerinformationen anzusehendocker commit <your-container-id> <your-image-name> um die Abhängigkeitsinstallation zu speichernchasten Bedürfnisse verwenden! Black und Ruff bei Chasten, um die Konsistenz, Lesbarkeit und Einhaltung vordefinierter Formatierungsstandards über das gesamte Projekt zu gewährleisten und letztendlich die Wartbarkeit und Zusammenarbeit zwischen Entwicklern zu verbessern.poetry run task fiximports und/oder poetry run task fixformat bevor neue Funktionen verschickt werden. Wenn Funktionen mit Leinenproblemen versendet werden, wird der Build aufgrund des Ausfalls der Testsuite auf GitHub eingebrochen.Pytest und Hypothesis , mit der wir die Codekonsistenz, Lesbarkeit und Ausrichtung auf festgelegte Formatierungsstandards während des gesamten Projekts stärken können. Erstellen Sie beim Schreiben von Testfällen für Funktionen eine neue Datei im Testverzeichnis mit dem Namenstest_ test_(name of file) .poetry run task test für die meisten Fälle oder wenn Sie die OpenAI-basierten Funktionen für poetry run task test-api vor dem Versand testen möchten. Wenn Merkmale ohne Testsuite versendet werden, wird die Abdeckung aufgrund der Hinzufügung von ungetestetem Code auf Github gesenkt und kann in Zukunft zu größeren Problemen führen. Chasten und Symsex, das von Simon Willison erstellt wurde, sind beide Tools, die für die Analyse des Python -Quellcodes entwickelt wurden, insbesondere mit der Suche nach der Suche nach Funktionen und Klassen in Dateien. Während sie ein gemeinsames Ziel haben, gibt es bemerkenswerte Unterschiede zwischen den beiden, insbesondere in Bezug auf ihre Befehlszeilenschnittstellen und Funktionen.
In Bezug auf die Befehlszeile-Schnittstelle verwendet der Symbire eine kurze CLI, die Abkürzungen für verschiedene Optionen verwendet. Beispielsweise lautet der Befehl zur Suche nach Funktionssignaturen in einer Datei mit dem Namen test_debug.py wie folgt:
command : symbex - s - f symbex / test_debug . py
def test_debug_level_values ():
def test_debug_level_isinstance ():
def test_debug_level_iteration ():
def test_debug_destination_values ():
def test_debug_destination_isinstance ():
def test_debug_destination_iteration ():
def test_level_destination_invalid ():
def test_debug_destination_invalid ():Chasten dagegen nutzt Python-Pakete wie Typer und Rich, um eine benutzerfreundliche und featurereiche Befehlszeilenschnittstelle bereitzustellen. Zu den verfügbaren Befehlen für Chasten gehören:
In Bezug auf die Funktionalität ist Symbrex so konzipiert, dass sie Python -Code nach Funktionen und Klassen nach Namen oder Wildcard durchsuchen. Es bietet die Möglichkeit, Ergebnisse auf der Grundlage verschiedener Kriterien zu filtern, einschließlich Funktionstyp (ASync oder Nicht-ASync), Präsenz, Sichtbarkeit und Anmerkungen von Dokumentationen).
Andererseits führt der Befehl von Chastens analyze eine AST -Analyse des Python -Quellcodes durch. Dadurch können Benutzer einen Projektnamen, eine XPath -Version, einen Suchpfad und verschiedene Filterkriterien angeben. Chasten unterstützt Schecks für Einbeziehung und Ausschluss basierend auf Attributen, Werten und Übereinstimmungen. Das Tool bietet auch umfangreiche Konfigurationsoptionen und die Möglichkeit, Ergebnisse in verschiedenen Formaten zu sparen, einschließlich Markdown.
Zusammenfassend lässt sich sagen, dass Chasten als auch der Symbäse den gemeinsamen Zweck der Analyse von Python-Quellcode erfüllen, und Chasten bietet eine vielseitigere und benutzerfreundlichere CLI mit zusätzlichen Funktionen der Konfiguration und des Ergebnismanagements. Die Symbire hingegen nimmt eine prägnante CLI mit dem Schwerpunkt auf der Suche und Filterfunktionen an. Die Auswahl zwischen den beiden Tools hängt von den Vorlieben des Benutzers und den spezifischen Anforderungen für die Python -Codeanalyse ab.
Zusätzlich zu Chasten und Symsex bieten mehrere andere Tools einzigartige Funktionen für die Analyse und Suche durch den Python -Quellcode, wobei jeweils bestimmte Anwendungsfälle geeignet sind.
