chasten
v0.2.0: Merge pull request #81 from AstuteSource
Chasten es un programa de Python que utiliza expresiones XPath para encontrar patrones en el árbol de sintaxis abstracto (AST) de un programa Python. Puede usar Chasten para implementar rápidamente sus propias reglas de pelusa configurables, sin tener que usar un marco de análisis AST complejo o recurrir a expresiones regulares imprecisas.
¿Quiere asegurarse de que un programa de Python no tenga ningún triple anidado for bucles dentro de las funciones async ? O, ¿desea confirmar que cada función dentro de su programa Python tiene anotaciones de tipo y un comentario de documentos? ¡Chasten puede ayudar ! Le permite expresar estos controles, y muchos otros tipos de análisis también, en archivos YAML simples que contienen expresiones XPath.
Chasten (verbo transitivo) "para que alguien consciente del fracaso o de haber hecho algo mal", Cambridge Dictionary.
Casten (innumerable o singular sustantivo) "Una herramienta que analiza el árbol de sintaxis abstracto de un programa de Python para detectar posibles fuentes de errores de programador para evitar la falla del programa", los desarrolladores de AtTuteurce.
chasten me haya recordado a agregar documentos y anotaciones de tipo a todas las funciones en main.py ¡Fue fácil ver qué arreglar!"chasten me facilita confirmar de manera confiable que los programas de estudiantes tienen las construcciones de codificación requeridas. ¡Es mucho mejor que usar expresiones regulares!"chasten me hizo divertido y fácil para mí hacer un análisis automatizado de una base de código Python que mantengo".chasten me permite explorar de manera efectiva los datos que recopile". Siga estos pasos para instalar el programa chasten :
pipx install chasten para instalar Chastenpipx list y confirme que Chasten está instaladochasten --help para aprender a usar la herramienta Puede configurar chasten con dos archivos YAML, normalmente llamados config.yml y checks.yml . Aunque chasten puede generar una configuración inicial, puede consultar el? Repositorio de configuración de Astutesurce/Chasten, por ejemplo, por ejemplo (s) de archivos de configuración que configuran la herramienta. Aunque el archivo config.yml puede hacer referencia a múltiples archivos de configuración de verificación, este ejemplo muestra cómo especificar un solo archivo checks.yml :
# chasten configuration
chasten :
# point to a single checks file
checks-file :
- checks.yml El archivo checks.yml debe contener una o más cheques. Lo que sigue es un ejemplo de un archivo de configuración de verificación con dos comprobaciones que encuentran respectivamente la primera línea ejecutable de funciones sin pruebas y de prueba en un proyecto de Python. Tenga en cuenta que el atributo pattern especifica la expresión de XPath Versión 2.0 que chasten usará para detectar el tipo especificado de la función Python. Puede escribir chasten configure validate --config <path to chasten-configuration/ directory | config url> Después de completar <path to chasten-configuration/directory | config url> con el nombre totalmente calificado de su directorio de configuración y la herramienta confirmará que su configuración cumple con la especificación de la herramienta. ¡También puede usar el comando chasten configure create para generar automáticamente una configuración inicial! Escribir chasten configure --help explicará cómo configurar la herramienta.
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 Dado que chasten necesita un proyecto con el código fuente de Python como la entrada a su subcomcomando analysis , puede clonar el? Astutesurce/LazyTracker y? Repositorios Astutesurce/MultiCounter que son tenedores de proyectos de Python existentes creados para un análisis conveniente. Para analizar incrementalmente estos dos proyectos con chasten , puede escribir los siguientes comandos para producir un archivo JSON de resultados para cada proyecto:
subject-data/ que contenga un directorio lazytracker/ , puede ejecutar el comando chasten analyze para el programa 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 Ahora puede escanear la salida para confirmar que, por ejemplo, chasten encuentra 6 funciones de prueba en el proyecto lazytracker . Si mira en el directorio de subject-data/lazytracker encontrará un archivo JSON con un nombre como chasten-results-lazytracker-20230823162341-4c23fc443a6b4c4aa09886f1ecb96e9f.json . Ejecutar chasten en este programa más de una vez producirá un nuevo archivo de resultados con una marca de tiempo diferente (es decir, 20230823162341 ) y un identificador único (es decir, 4c23fc443a6b4c4aa09886f1ecb96e9f ) a su nombre, lo que garantiza que no escriba accidentalmente sobre sus resultados anteriores cuando use --save .
Después de crear un directorio multicounter/ en el subject-data/ existentes, puede ejecutar el comando chasten analyze para el programa 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 Ahora puede escanear la salida para confirmar que, como ejemplo, chasten encuentra 10 funciones de prueba en el proyecto multicounter . Si busca en el directorio de subject-data/lazytracker encontrará un archivo JSON con un nombre como chasten-results-multicounter-20230821171712-5c52f2f1b61b4cce97624cc34cb39d4f.json y componentes de nombre que son similares al archivo JSON creado para el programa multicounter .
Dado que la verificación all-test-function-definition especifica que el programa debe tener entre 1 y 10 pruebas, notará que esta verificación pasa tanto para lazytracker como para multicounter . Esto significa que chasten devuelve un código de error 0 para comunicarse a su sistema operativo que pasó la verificación.
Puede obtener más información sobre cómo usar el submand analyze escribiendo chasten analyze --help . Por ejemplo, chasten es compatible con las opciones --check-include y --check-exclude que le permiten incluir respectivamente y excluir las verificaciones específicas de acuerdo con las reglas de coincidencia difusa que puede especificar para cualquiera de los atributos de un cheque especificados en el archivo checks.yml .
Después de ejecutar chasten en los programas lazytracker y multicounter , puede integrar sus archivos JSON individuales en un solo archivo JSON, archivos CSV relacionados y una base de datos SQLite. Una vez que haya realizado un integrated-data/ , puede escribir este comando para realizar la integración:
chasten integrate all-programs
< path to subject-data > / ** / * .json
--save-directory < path to the integrated-data/ directory > Este comando producirá un directorio como chasten-flattened-csvs-sqlite-db-all-programs-20230823171016-2061b524276b4299b04359ba30452923/ que contiene una base de datos de Sqlite llamada chasten.db y un directorio csv/ Director con los archivos CSV que corresponden a cada uno de las tareas de las tareas de las tareas que corresponden a las tareas de las tareas que corresponden a las tareas de las tareas que corresponden a las tareas de las tareas que corresponden a las tareas de las tareas que corresponden a las tareas de las tareas que corresponden a las tareas que corresponden a las tareas de las tareas que corresponden a las tareas de las tareas que corresponden a las tareas que corresponden a las tareas de las tareas que corresponden a las tareas de las tareas. base de datos.
Puede obtener más información sobre el submand integrate escribiendo chasten integrate --help .
Al utilizar el comando chasten , agregar este indicador --verbose puede mejorar significativamente su experiencia de solución de problemas y proporcionar una comprensión detallada de la funcionalidad de la herramienta. Aquí hay un ejemplo con 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 Al ejecutar este comando, puede esperar que la salida contenga mensajes informativos como Matching source code: indicando que la herramienta está comparando activamente el código fuente con los patrones especificados. Además, recibirá resultados de coincidencia detallados, proporcionando información sobre las verificaciones identificadas.
¿Si desea crear un tablero de análisis interactivo que use? Simonw/DataSette Puede ejecutar chasten datasette-serve <path containing integrated results>/chasten.db --port 8001 . ¡Ahora puede usar el tablero en su navegador web para analizar los resultados mientras estudia el código fuente de estos proyectos con su editor! ¿Examinar los resultados revelará que chasten , a través de su uso? Spookylukey/PyastGrep, utiliza correctamente la expresión XPATH para all-test-function-definition para encontrar la primera línea de código fuente ejecutable dentro de cada prueba, saltando sobre el documento de una función y los comentarios principales.
Para el programa lazytracker , notará que chasten informa que hay 6 casos de prueba a pesar de que pytest solo encuentra y ejecuta 5 pruebas. Esto se debe al hecho de que tests/test_tracked.py Test Suite en lazytracker contiene una función que comienza con test_ dentro de otra función que comienza con test_ . ¡Este ejemplo ilustra las limitaciones del análisis estático con chasten ! A pesar de que la herramienta detectó correctamente todas las "funciones de prueba", la anidación de las funciones en el conjunto de pruebas significa que pytest ejecutará la función externa test_ y usará la función interna test_ para fines de prueba.
Dicho esto, chasten encuentra correctamente cada una de las pruebas para el proyecto multicounter . ¡Puede seguir cada uno de los pasos anteriores de este documento para aplicar chasten a su propio programa Python!
Si desea hacer que su chasten.db esté disponible públicamente para que todos los estudien, puede usar el subcomcomando chasten datasette-publish . ¿Mientras haya seguido las instrucciones de instalación? Simonw/DataSette Publish-Fly y? SimonW/DataSette Publish-Vercel, puede usar los complementos para implementar un servidor datasette público que aloja su chasten.db . Por ejemplo, la ejecución del comando chasten datasette-publish <path containing integrated results>/chasten.db --platform vercel publicará los resultados de ejecutar chasten en lazytracker y multicounter en la plataforma Vercel.
Es importante destacar que el uso del comando chasten datasette-publish con la opción --platform vercel requiere que haya seguido previamente las instrucciones para el complemento datasette-publish-vercel para instalar la herramienta de línea de comandos vercel . Esto es necesario porque, aunque datasette-publish-vercel es una de las dependencias de chasten , ni chasten ni datasette-publish-vercel proporcionan la herramienta vercel a pesar de que la usan. ¡Debe tomar pasos similares antes de publicar su base de datos para volar!
Aunque chasten es una aplicación de línea de comandos, crea interactivamente crear los argumentos y opciones de línea de comandos de la herramienta a través de una interfaz de usuario terminal (TUI). Para usar la forma basada en TUI para crear una línea de comandos completa para chasten , puede escribir el comando chasten interact .
Chasten tiene un registro de sistema incorporado. Mientras usa Chasten, puede usar el comando chasten log en su terminal. La función de registro del sistema permite al usuario ver eventos y mensajes producidos por chasten . Además, la función chasten log ayudará a encontrar errores y los eventos que llevaron a que ocurriera el error. Para que el programa chasten se muestre en el registro del sistema, deberá abrir un terminal separado y usar el chasten log . Además para cada comando que se ejecute --debug-level <choice of level> y --debug-dest SYSLOG deberá agregarse.
Por ejemplo, chasten datasette-serve --debug-level DEBUG --debug-dest SYSLOG < database path to file> producirá la siguiente salida en el registro del sistema.
? 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
En cada comando en chasten , hay una opción para agregar un --debug-level . El nivel de depuración tiene 5 opciones de depuración, información, advertencia, error y crítico. Cada nivel mostrará diferentes problemas en el registro del sistema donde la depuración es el nivel más bajo de problemas de la entrada donde crítico es el nivel más alto de error. Para aprovechar más información sobre esto, puede hacer referencia al archivo 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. │
╰─────────────────────────────────────────────────────────────────────────────────────────────╯
Siga estos pasos para instalar la herramienta chasten para el desarrollo futuro:
Una vez que se instale Python y Poetry, vaya al repositorio de Chasten en GitHub e instale la herramienta utilizando el comando git clone en su terminal. Luego navegue al directorio de Chasten y ejecute la poetry install de comando para instalar todas las dependencias.
También existe la opción de usar Docker para usar chasten
Siga estos pasos para utilizar Docker:
cd en el directorio de Chasten donde se encuentra el Dockerfiledocker build -t chasten . Para construir el contenedordocker 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 tipo contenedordocker ps para ver la ejecución de la información del contenedordocker commit <your-container-id> <your-image-name> para guardar la instalación de dependienteschasten ! Black and Ruff en Chasten para garantizar la consistencia del código, la legibilidad y el cumplimiento de los estándares de formato predefinidos en todo el proyecto, mejorando en última instancia la mantenibilidad y la colaboración entre los desarrolladores.poetry run task fiximports y/o poetry run task fixformat antes de enviar nuevas funciones. Si las características se envían con problemas de pelusa, la compilación se romperá en GitHub debido a la falla de la suite de prueba.Pytest y Hypothesis que nos permite fortalecer la consistencia, legibilidad y alineación del código con estándares de formato establecidos en todo el proyecto. Al escribir casos de prueba para funciones, cree un nuevo archivo en el directorio de pruebas con la convención de nombres test_(name of file) .poetry run task test para la mayoría de los casos o si desea probar las características de OpenAI basadas en poetry run task test-api antes del envío. Si las características se envían sin una suite de prueba, la cobertura se reducirá en GitHub debido a la adición de código no probado y puede conducir potenitalmente a problemas más grandes en el futuro. Chasten y Symbex, creado por Simon Willison, son herramientas diseñadas para analizar el código fuente de Python, particularmente centrados en buscar funciones y clases dentro de los archivos. Si bien comparten un objetivo común, existen diferencias notables entre los dos, especialmente en términos de sus interfaces y funcionalidad de línea de comandos.
En términos de interfaz de línea de comandos, SymBex emplea una CLI concisa, utilizando abreviaturas para varias opciones. Por ejemplo, el comando para buscar firmas de funciones en un archivo llamado test_debug.py es el siguiente:
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, por otro lado, aprovecha los paquetes de Python como Typer y Rich para proporcionar una interfaz de línea de comandos fácil de usar y rica en funciones. Los comandos disponibles para Chasten incluyen:
En términos de funcionalidad, SymBex está diseñado para buscar en el código de Python para funciones y clases por nombre o comodín. Proporciona la capacidad de filtrar los resultados basados en diversos criterios, incluido el tipo de función (async o no async), presencia de documentación, visibilidad y anotaciones de tipo.
Por otro lado, el comando analyze de Chasten realiza un análisis AST en el código fuente de Python. Permite a los usuarios especificar un nombre de proyecto, versión XPATH, ruta de búsqueda y varios criterios de filtrado. Chasten admite los controles de inclusión y exclusión basados en atributos, valores y niveles de confianza. La herramienta también proporciona opciones de configuración extensas y la capacidad de guardar resultados en diferentes formatos, incluido Markdown.
En resumen, mientras que Chasten y Symbex tienen el propósito común de analizar el código fuente de Python, Chasten ofrece una CLI más versátil y fácil de usar con características adicionales de configuración y administración de resultados. Symbex, por otro lado, adopta una CLI concisa con un enfoque en la búsqueda y el filtrado de funcionalidades. La elección entre las dos herramientas depende de las preferencias del usuario y los requisitos específicos para el análisis del código de Python.
Además de Chasten y Symbex, varias otras herramientas ofrecen capacidades únicas para analizar y buscar a través del código fuente de Python, cada una de ellas a casos de uso específicos.
