chasten
v0.2.0: Merge pull request #81 from AstuteSource
Chasten est un programme Python qui utilise des expressions XPath pour trouver des modèles dans l'arbre de syntaxe abstrait (AST) d'un programme Python. Vous pouvez utiliser Chasten pour implémenter rapidement vos propres règles de liaison configurables, sans avoir à utiliser un cadre d'analyse AST complexe ou à recourir à des expressions régulières imprécises.
Voulez-vous vous assurer qu'un programme Python n'a pas de triple nerveux for les boucles à l'intérieur des fonctions async ? Ou, voulez-vous confirmer que chaque fonction dans votre programme Python a des annotations de type et un commentaire docstring? Chasten peut aider ! Il vous permet d'exprimer ces vérifications - et de nombreux autres types d'analyses également - dans des fichiers YAML simples qui contiennent des expressions XPath.
Chasten (verbe transitif) "pour sensibiliser quelqu'un à l'échec ou avoir fait quelque chose de mal", Cambridge Dictionary.
Chasten (nom non comptable ou singulier) "Un outil qui analyse l'arbre de syntaxe abstrait d'un programme Python pour détecter les sources potentielles d'erreurs du programmeur afin d'éviter la défaillance du programme", les développeurs astutesource.
chasten m'a rappelé d'ajouter des docstrings et de taper des annotations à toutes les fonctions de main.py Il était facile de voir quoi réparer!"chasten me permet de confirmer de manière fiable que les programmes étudiants ont les constructions de codage requises. C'est beaucoup mieux que d'utiliser des expressions régulières!"chasten m'a rendu amusant et facile pour moi de faire une analyse automatisé d'une base de code Python que je maintiens."chasten me permet d'explorer efficacement les données que je collectionne." Suivez ces étapes pour installer le programme chasten :
pipx install chasten pour installer Chastenpipx list et confirmez que Chasten est installéchasten --help pour apprendre à utiliser l'outil Vous pouvez configurer chasten avec deux fichiers YAML, normalement appelés config.yml et checks.yml . Bien que chasten puisse générer une configuration de départ, vous pouvez consulter le? Référentiel Astutesource / Chasten-Configuration par exemple des fichiers de configuration qui configurent l'outil. Bien que le fichier config.yml puisse faire référence à plusieurs fichiers de configuration de vérification, cet exemple montre comment spécifier un seul fichier checks.yml :
# chasten configuration
chasten :
# point to a single checks file
checks-file :
- checks.yml Le fichier checks.yml doit contenir un ou plusieurs chèques. Ce qui suit est un exemple de fichier de configuration de vérification avec deux vérifications qui trouvent respectivement la première ligne exécutable de fonctions non test et de test de test dans un projet Python. Notez que l'attribut pattern spécifie l'expression XPATH version 2.0 que chasten utilisera pour détecter le type spécifié de fonction Python. Vous pouvez taper chasten configure validate --config <path to chasten-configuration/ directory | config url> Après avoir rempli <path to chasten-configuration/directory | config url> avec le nom entièrement qualifié de votre répertoire de configuration et l'outil confirmera que votre configuration répond à la spécification de l'outil. Vous pouvez également utiliser la commande chasten configure create pour générer automatiquement une configuration de démarrage! Typing chasten configure --help expliquera comment configurer l'outil.
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 Étant donné que chasten a besoin d'un projet avec le code source Python comme entrée dans sa sous-commande analysis , vous pouvez cloner le? Astutesource / lazytracker et? Référentiels Astutesource / MultiCounter qui sont des fourches de projets Python existants créés pour une analyse pratique. Pour analyser progressivement ces deux projets avec chasten , vous pouvez taper les commandes suivantes pour produire un fichier JSON des résultats pour chaque projet:
subject-data/ répertoire qui contient un répertoire lazytracker/ Rendre, vous pouvez exécuter la commande chasten analyze pour le programme lazytracker : 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 Vous pouvez désormais numériser la sortie pour confirmer que, par exemple, chasten trouve 6 fonctions de test dans le projet lazytracker . Si vous regardez dans le répertoire subject-data/lazytracker vous trouverez un fichier JSON avec un nom comme chasten-results-lazytracker-20230823162341-4c23fc443a6b4c4aa09886f1ecb96e9f.json . L'exécution de chasten sur ce programme produira plus d'une fois un nouveau fichier de résultats avec un horodatage différent (c.-à-d. 20230823162341 ) et un identifiant unique (c'est-à-dire 4c23fc443a6b4c4aa09886f1ecb96e9f ) dans son nom, en vous assurant donc de ne pas écrire accidentellement sur vos résultats antérieurs lorsque vous utilisez --save .
Après avoir créé un multicounter/ répertoire dans le subject-data/ répertoire existant, vous pouvez exécuter la commande chasten analyze pour le programme multicounter :
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 Vous pouvez désormais numériser la sortie pour confirmer que, par exemple, chasten trouve 10 fonctions de test dans le projet multicounter . Si vous regardez dans le répertoire subject-data/lazytracker vous trouverez un fichier JSON avec un nom comme chasten-results-multicounter-20230821171712-5c52f2f1b61b4cce97624cc34cb39d4f.json et des composants de noms similaires à la fichier JSON créé pour le programme multicounter .
Étant donné que la vérification all-test-function-definition spécifie que le programme doit subir entre 1 et 10 tests, vous remarquerez que cette vérification passe à la fois pour lazytracker et multicounter . Cela signifie que chasten renvoie un code d'erreur 0 pour communiquer à votre système d'exploitation que le chèque a réussi.
Vous pouvez en savoir plus sur la façon d'utiliser la sous-commande analyze en tapant chasten analyze --help . Par exemple, chasten prend en charge les options --check-include et --check-exclude qui vous permettent respectivement d'inclure et d'exclure des vérifications spécifiques en fonction des règles de correspondance floues que vous pouvez spécifier pour l'un des attributs d'un chèque spécifié dans le fichier checks.yml .
Après avoir exécuté chasten sur les programmes lazytracker et multicounter , vous pouvez intégrer leurs fichiers JSON individuels dans un seul fichier JSON, des fichiers CSV connexes et une base de données SQLite. Une fois que vous avez fait un integrated-data/ , vous pouvez taper cette commande pour effectuer l'intégration:
chasten integrate all-programs
< path to subject-data > / ** / * .json
--save-directory < path to the integrated-data/ directory > This command will produce a directory like chasten-flattened-csvs-sqlite-db-all-programs-20230823171016-2061b524276b4299b04359ba30452923/ that contains a SQLite database called chasten.db and a csv/ directory with CSV files that correspond to each of the tables inside of the base de données.
Vous pouvez en savoir plus sur la sous-command integrate en tapant chasten integrate --help .
Lors de l'utilisation de la commande chasten , ajouter ce drapeau --verbose peut améliorer considérablement votre expérience de dépannage et fournir une compréhension détaillée de la fonctionnalité de l'outil. Voici un exemple avec 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 Lors de l'exécution de cette commande, vous pouvez vous attendre à ce que la sortie contienne des messages informatifs tels que Matching source code: indiquant que l'outil compare activement le code source avec les modèles spécifiés. De plus, vous recevrez des résultats de correspondance détaillés, fournissant des informations sur les contrôles identifiés.
Si vous souhaitez créer un tableau de bord d'analyse interactif qui utilise? SIMONW / DATASETTE Vous pouvez exécuter chasten datasette-serve <path containing integrated results>/chasten.db --port 8001 . Vous pouvez maintenant utiliser le tableau de bord de votre navigateur Web pour analyser les résultats pendant que vous étudiez le code source de ces projets avec votre éditeur! L'examen des résultats révélera que chasten , par son utilisation? SpookyLukey / Pyastgrep, utilise correctement l'expression XPATH pour all-test-function-definition pour trouver la première ligne de code source exécutable à l'intérieur de chaque test, en sautant les commentaires docstrants et principaux d'une fonction.
Pour le programme lazytracker , vous remarquerez que chasten rapporte qu'il y a 6 cas de test même si pytest ne trouve et exécute 5 tests. Cela est dû au fait que tests/test_tracked.py Test Suite dans lazytracker contient une fonction commençant par test_ à l'intérieur d'une autre fonction commençant par test_ . Cet exemple illustre les limites de l'analyse statique avec chasten ! Même si l'outil a détecté correctement toutes les "fonctions de test", la nidification des fonctions dans la suite de test signifie que pytest exécutera la fonction externe test_ et utilisera la fonction test_ interne à des fins de test.
Cela dit, chasten trouve correctement chacun des tests pour le projet multicounter . Vous pouvez suivre chacune des étapes précédentes de ce document pour appliquer chasten à votre propre programme Python!
Si vous souhaitez rendre votre chasten.db accessible au public pour que tout le monde puisse étudier, vous pouvez utiliser le sous-commande chasten datasette-publish . Tant que vous avez suivi les instructions d'installation? Simonw / Datasette-Publish-Fly et? SimonW / Datasette-Publish-Vercel, vous pouvez utiliser les plugins pour déployer un serveur datasette public qui héberge votre chasten.db . Par exemple, l'exécution de la commande chasten datasette-publish <path containing integrated results>/chasten.db --platform vercel publiera les résultats de l'exécution chasten sur lazytracker et multicounter sur la plate-forme Vercel.
Surtout, l'utilisation de la commande chasten datasette-publish avec l'option --platform vercel vous oblige à avoir suivi les instructions du plugin de datasette-publish-vercel pour installer l'outil de ligne de commande vercel . Cela est nécessaire car, bien que datasette-publish-vercel soit l'une des dépendances de chasten , ni chasten ni datasette-publish-vercel ne fournissent l'outil vercel même s'ils l'utilisent. Vous devez prendre des mesures similaires avant de publier votre base de données pour voler!
Même si chasten est une application de ligne de commande, vous créez des arguments et des options de ligne de commande de l'outil via une interface utilisateur (TUI) de l'outil. Pour utiliser un moyen basé sur TUI pour créer une ligne de commande complète pour chasten , vous pouvez taper la commande chasten interact .
Chasten a un journal système intégré. Lorsque vous utilisez Chasten, vous pouvez utiliser la chasten log CONCROYAGE dans votre terminal. La fonction de journal système permet à l'utilisateur de voir des événements et des messages produits par chasten . De plus, la fonction chasten log aidera à trouver des bogues et les événements qui ont conduit au bogue. Pour que le programme chasten s'affiche dans le journal système, vous devrez ouvrir un terminal séparé et utiliser le chasten log de commande. De plus pour chaque commande qui est exécutée le --debug-level <choice of level> et --debug-dest SYSLOG devra être ajouté.
Par exemple, chasten datasette-serve --debug-level DEBUG --debug-dest SYSLOG < database path to file> produira la sortie suivante dans le journal système.
? 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
Dans chaque commande de chasten , il existe une option pour ajouter un --debug-level . Le niveau de débogage a 5 options de débogage, d'informations, d'avertissement, d'erreur et de critique. Chaque niveau affichera différents problèmes dans le journal système où le débogage est le niveau de problème le plus bas de l'entrée où la critique est le plus haut niveau d'erreur. Pour tirer parti de plus d'informations à ce sujet, vous pouvez référencer le fichier debug.py :
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. │
╰─────────────────────────────────────────────────────────────────────────────────────────────╯
Suivez ces étapes pour installer l'outil chasten pour le développement futur:
Une fois Python et la poésie installés, veuillez accéder au référentiel Chasten sur GitHub et installer l'outil à l'aide de la commande git clone dans votre terminal. Accédez ensuite au répertoire Chasten et exécutez l' poetry install de commande pour installer toutes les dépendances.
Il y a aussi la possibilité d'utiliser Docker pour utiliser chasten
Suivez ces étapes pour utiliser Docker:
cd dans le répertoire Chasten où se trouve le Dockerfiledocker build -t chasten . Pour construire le conteneurdocker run --rm -v "%cd%":/root/src -it chastendocker run --rm -v ${pwd}:/root/src -it chastendocker run --rm -v $(pwd):/root/src -it chastenpoetry install de type conteneurdocker ps pour afficher les informations de conteneur en cours d'exécutiondocker commit <your-container-id> <your-image-name> pour enregistrer l'installation dépendantechasten ! Black et Ruff sur le chaste pour assurer la cohérence du code, la lisibilité et l'adhésion aux normes de mise en forme prédéfinies dans l'ensemble du projet, améliorant finalement la maintenabilité et la collaboration entre les développeurs.poetry run task fiximports et / ou poetry run task fixformat avant d'expédier de nouvelles fonctionnalités. Si les fonctionnalités sont expédiées avec des problèmes de liaison, la construction se brisera sur GitHub en raison de la défaillance de la suite de tests.Pytest et Hypothesis qui nous permet de fortifier la cohérence, la lisibilité et l'alignement du code avec les normes de mise en forme établies tout au long du projet. Lors de la rédaction de cas de test pour les fonctionnalités, créez un nouveau fichier dans le répertoire des tests avec le test_(name of file) .poetry run task test pour la plupart des cas ou si vous souhaitez tester les fonctionnalités basées sur l'API OpenAI poetry run task test-api avant l'expédition. Si les fonctionnalités sont expédiées sans suite de tests, la couverture sera abaissée sur GitHub en raison de l'ajout de code non testé et pourrait entraîner des problèmes plus importants à l'avenir. Chasten et Symbex, créés par Simon Willison, sont tous deux des outils conçus pour analyser le code source Python, en se concentrant en particulier sur la recherche de fonctions et de classes dans les fichiers. Bien qu'ils partagent un objectif commun, il existe des différences notables entre les deux, en particulier en termes d'interfaces et de fonctionnalités en ligne de commande.
En termes d'interface de ligne de commande, Symbex utilise une CLI concise, en utilisant des abréviations pour diverses options. Par exemple, la commande pour rechercher des signatures de fonction dans un fichier nommé test_debug.py est le suivant:
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, en revanche, exploite des packages Python tels que Typer et Rich pour fournir une interface de ligne de commande conviviale et riche en fonctionnalités. Les commandes disponibles pour Chasten comprennent:
En termes de fonctionnalités, Symbex est conçu pour rechercher le code Python pour les fonctions et les classes par nom ou générique. Il offre la possibilité de filtrer les résultats en fonction de divers critères, y compris le type de fonction (asynchrone ou non-async), la présence de documentation, la visibilité et les annotations de type.
D'un autre côté, la commande analyze de Chasten effectue une analyse AST sur le code source Python. Il permet aux utilisateurs de spécifier un nom de projet, une version XPath, un chemin de recherche et divers critères de filtrage. Chasten prend en charge les vérifications de l'inclusion et de l'exclusion en fonction des attributs, des valeurs et des niveaux de confiance. L'outil offre également des options de configuration étendues et la possibilité d'enregistrer des résultats dans différents formats, y compris Markdown.
En résumé, alors que Chasten et Symbex servent le but commun d'analyser le code source Python, Chasten propose une CLI plus polyvalente et conviviale avec des fonctionnalités supplémentaires de configuration et de gestion des résultats. Symbex, en revanche, adopte une CLI concise en mettant l'accent sur la recherche et le filtrage des fonctionnalités. Le choix entre les deux outils dépend des préférences de l'utilisateur et des exigences spécifiques pour l'analyse du code Python.
En plus de Chasten et Symbex, plusieurs autres outils offrent des capacités uniques pour analyser et rechercher le code source Python, chacun s'adre à des cas d'utilisation spécifiques.
