chasten
v0.2.0: Merge pull request #81 from AstuteSource
Casten - это программа Python, которая использует выражения XPath для поиска шаблонов в абстрактном синтаксисном дереве (AST) программы Python. Вы можете использовать наказание, чтобы быстро реализовать свои собственные настраиваемые правила внедрения, без необходимости использовать сложную структуру анализа AST или прибегать к неточным регулярным выражениям.
Вы хотите убедиться, что программа Python не имеет тройного заложенного for петли внутри async функций? Или вы хотите подтвердить, что каждая функция в вашей программе Python имеет аннотации типа и комментарий Docstring? Наслаждается, может помочь ! Это позволяет вам выразить эти проверки - и многие другие типы анализов - в простых файлах YAML, которые содержат выражения XPath.
Натолкните (переходный глагол) «чтобы кто -то знал о неудаче или о том, что сделал что -то не так», Кембриджский словарь.
Наслаждается (бесчисленным или единственным существительным) «инструмент, который анализирует абстрактное синтаксическое дерево программы Python для обнаружения потенциальных источников ошибок программиста, чтобы предотвратить неудачу программы», разработчики Astoutesource.
chasten напомнило мне добавить Docstrings и тип аннотации ко всем функциям в main.py Было легко увидеть, что исправить!»chasten мне легко достоверно подтвердить, что студенческие программы имеют необходимые конструкции кодирования. Это намного лучше, чем использование регулярных выражений!»chasten , что мне было весело и было легко провести автоматический анализ кодовой базы Python, который я поддерживаю».chasten позволяет мне эффективно исследовать данные, которые я собираю». Следуйте этим шагам, чтобы установить программу chasten :
pipx install chasten , чтобы установить наказаниеpipx list и подтвердите, что натолкнутchasten --help чтобы узнать, как использовать инструмент Вы можете настроить chasten с двумя файлами YAML, обычно называемыми config.yml и checks.yml . Хотя chasten может генерировать начальную конфигурацию, вы можете проверить? Репозиторий ASTUTESOURCE/CASTEN-CONFIGURATION, например, файлов конфигурации, которые настраивают инструмент. Хотя файл config.yml может ссылаться на несколько файлов конфигурации проверки, в этом примере показано, как указать один файл checks.yml :
# chasten configuration
chasten :
# point to a single checks file
checks-file :
- checks.yml Файл checks.yml должен содержать один или несколько чеков. Далее следует пример файла конфигурации проверки с двумя проверками, которые соответственно находят первую исполняемую строку функций не испытательных и тестовых функций в проекте Python. Обратите внимание, что атрибут pattern определяет выражение XPath версии 2.0, которое chasten , что будет использовать для обнаружения указанного типа функции Python. Вы можете ввести chasten configure validate --config <path to chasten-configuration/ directory | config url> после заполнения <path to chasten-configuration/directory | config url> с полностью квалифицированным именем вашего каталога конфигурации, и инструмент подтвердит, что ваша конфигурация соответствует спецификации инструмента. Вы также можете использовать команду chasten configure create Command для автоматического генерации начальной конфигурации! Typling chasten configure --help объяснит, как настроить инструмент.
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 Поскольку chasten нуждается в проекте с исходным кодом Python в качестве входного ввода в подкоманду analysis , вы можете клонировать? ASTUTESOURCE/LAZYTRACKER и? Astoutesource/Multicounter Repositories, которые являются вилками существующих проектов Python, созданных для удобного анализа. Чтобы постепенно проанализировать эти два проекта с chasten , вы можете ввести следующие команды для получения файла JSON результатов для каждого проекта:
subject-data/ каталога, который содержит lazytracker/ Directory, вы можете запустить команду chasten analyze для программы 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 Теперь вы можете сканировать вывод, чтобы подтвердить, что, например, chasten находит 6 тестовых функций в проекте lazytracker . Если вы посмотрите в каталоге subject-data/lazytracker вы найдете файл JSON с таким именем, как chasten-results-lazytracker-20230823162341-4c23fc443a6b4c4aa09886f1ecb96e9f.json . Запуск chasten в этой программе более одного раза будет создавать новый файл результатов с другой временной меткой (то есть 20230823162341 ) и уникальным идентификатором (IE, 4c23fc443a6b4c4aa09886f1ecb96e9f ) в его имени, таким образом, гарантируя, что вы не случайно напишите свои приоритетные результаты --save
После создания multicounter/ каталога в существующем subject-data/ каталоге вы можете запустить команду chasten analyze для программы 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 Теперь вы можете сканировать вывод, чтобы подтвердить, что, например, chasten находит 10 тестовых функций в проекте multicounter . Если вы посмотрите в каталоге subject-data/lazytracker вы найдете файл JSON с таким именем, как chasten-results-multicounter-20230821171712-5c52f2f1b61b4cce97624cc34cb39d4f.json и название компоненты, которые похожи на файл JSON для программы multicounter .
Поскольку проверка all-test-function-definition указывает, что программа должна иметь от 1 до 10 тестов, вы заметите, что эта проверка проходит как для lazytracker , так и для multicounter . Это означает, что chasten возвращает код ошибки 0 , чтобы передавать вашу операционную систему, что проверка прошла.
Вы можете узнать больше о том, как использовать analyze подкоманда, набрав chasten analyze --help . Например, chasten поддерживает параметры --check-include и --check-exclude которые позволяют вам соответственно включать и исключать конкретные проверки в соответствии с нечеткими правилами сопоставления, которые вы можете указать для любого из атрибутов чека, указанных в файле checks.yml .
После запуска chasten на программах lazytracker и multicounter программ вы можете интегрировать их отдельные файлы JSON в один файл JSON, связанные файлы CSV и базу данных SQLITE. После того, как вы сделали integrated-data/ каталог, вы можете ввести эту команду для выполнения интеграции:
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 база данных.
Вы можете узнать больше о integrate подколме, набрав chasten integrate --help .
При использовании команды chasten , добавление этого флага --verbose может значительно улучшить ваш опыт устранения неполадок и дать подробное понимание функциональности инструмента. Вот пример с 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 После выполнения этой команды вы можете ожидать, что вывод содержит информативные сообщения, такие как Matching source code: указывая, что инструмент активно сравнивает исходный код с указанными шаблонами. Кроме того, вы получите подробные результаты соответствия, предоставляя представление о выявленных чеках.
Если вы хотите создать интерактивную панель панели анализа, которая использует? SIMONW/DATASETTE Вы можете запустить chasten datasette-serve <path containing integrated results>/chasten.db --port 8001 . Теперь вы можете использовать панель панели в своем веб -браузере, чтобы проанализировать результаты, пока вы изучаете исходный код для этих проектов с вашим редактором! Изучение результатов покажет, что chasten , благодаря использованию? Spookylukey/Pyastgrep, правильно использует выражение XPath для all-test-function-definition чтобы найти первую строку исполняемого исходного кода внутри каждого теста, пропуская DocString функции и ведущие комментарии.
Для программы lazytracker вы заметите, что chasten сообщения о том, что существует 6 тестовых случаев, хотя pytest находит только и проходит 5 тестов. Это связано с тем, что набор тестов tests/test_tracked.py в lazytracker содержит функцию, начиная с test_ внутри другой функции, начиная с test_ . Этот пример иллюстрирует ограничения статического анализа с chasten ! Несмотря на то, что инструмент правильно обнаружил все «тестовые функции», гнездование функций в испытательном наборе означает, что pytest будет выполнять функцию внешнего test_ и использовать функцию Inner test_ в целях тестирования.
С учетом сказанного, chasten правильно находит каждый из тестов для проекта multicounter . Вы можете следовать каждому из предыдущих шагов в этом документе, чтобы применить chasten свою собственную программу Python!
Если вы хотите сделать свой chasten.db публично доступным для всех, чтобы изучать, вы можете использовать подколенность chasten datasette-publish набор данных. Пока вы следовали инструкциям по установке? Simonw/DataSette-Publish-Fly и? SIMONW/DataSette-Publish-Vercel, вы можете использовать плагины для развертывания общедоступного сервера datasette , который размещает ваш chasten.db . Например, запуск команды chasten datasette-publish <path containing integrated results>/chasten.db --platform vercel опубликует результаты запуска chasten на lazytracker и multicounter на платформу Vercel.
Важно отметить, что использование команды chasten datasette-publish с опцией --platform vercel требует, чтобы вы ранее следовали инструкциям для плагина datasette-publish-vercel для установки инструмента командной строки vercel . Это необходимо, потому что, хотя datasette-publish-vercel является одной из зависимостей chasten , ни chasten , ни datasette-publish-vercel не предоставляют инструмент vercel , даже если они используют его. Вы должны предпринять аналогичные шаги, прежде чем публиковать свою базу данных, чтобы летать!
Несмотря на то, что chasten является приложением командной строки, вы создаете интерактивное создание аргументов и параметров командной строки инструмента через пользовательский интерфейс терминала (TUI). Чтобы использовать способ создания полной командной строки для chasten , вы можете ввести Command chasten interact .
Chasten встроенный системный журнал. Используя наток, вы можете использовать chasten log в вашем терминале. Функция журнала системы позволяет пользователю видеть события и сообщения, которые производятся chasten . Кроме того, функция chasten log поможет в поиске ошибок и событий, которые привели к возникновению ошибки. Для того, чтобы программа chasten , чтобы отобразить системный журнал, вам придется открыть отдельный терминал и использовать chasten log Commong Compen. Кроме того, для каждой команды, которая запускается, необходимо добавить значение --debug-level <choice of level> и --debug-dest SYSLOG .
Например, chasten datasette-serve --debug-level DEBUG --debug-dest SYSLOG < database path to file> будет создавать следующий выход в системном журнале.
? 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
В каждой команде в chasten есть возможность добавить --debug-level . Уровень отладки имеет 5 вариантов отладки, информации, предупреждения, ошибок и критических. Каждый уровень будет показывать разные проблемы в журнале системы, где отладка является самым низким уровнем проблемы с входа, где критическим является самый высокий уровень ошибки. Чтобы использовать больше информации об этом, вы можете ссылаться на файл 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. │
╰─────────────────────────────────────────────────────────────────────────────────────────────╯
Следуйте этим шагам, чтобы установить chasten инструмент для будущей разработки:
Как только Python и поэзия установлены, перейдите в The Casten Repository на GitHub и установите инструмент, используя команду git clone в вашем терминале. Затем перейдите к каталогу Casten и запустите poetry install чтобы установить все зависимости.
Существует также возможность использовать Docker для использования chasten
Следуйте этим шагам, чтобы использовать Docker:
cd в каталог Dockerfiledocker build -t chasten . Чтобы построить контейнерdocker 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 типа контейнераdocker ps для просмотра информации об запуске контейнераdocker commit <your-container-id> <your-image-name> , чтобы сохранить установку Devingecychasten потребностей! Black and Ruff на Casten, чтобы обеспечить согласованность кода, читабельность и соблюдение предопределенных стандартов форматирования по всему проекту, что в конечном итоге улучшает обслуживание и сотрудничество между разработчиками.poetry run task fiximports и/или poetry run task fixformat перед отправкой новых функций. Если функции поставляются с проблемами вкладки, сборка будет нарушена на GitHub из -за сбоя испытательного набора.Pytest и Hypothesis , которая позволяет нам укреплять согласованность, читаемость и согласованность кода с установленными стандартами форматирования на протяжении всего проекта. При написании тестовых примеров для функций создайте новый файл в каталоге Tests с соглашением от именования test_(name of file) .poetry run task test для большинства случаев или, если вы хотите проверить функции OpenAI API poetry run task test-api . Если функции отправляются без испытательного набора, покрытие будет снижено на GitHub из -за добавления непроверенного кода и может привести к более крупным проблемам в будущем. Casten и Symbex, созданный Simon Willison, являются инструментами, предназначенными для анализа исходного кода Python, в частности, сфокусированы на поиске функций и классов в файлах. Хотя они имеют общую цель, между ними существуют заметные различия, особенно с точки зрения их интерфейсов и функциональности командной строки.
С точки зрения интерфейса командной строки, Symbex использует краткий CLI, используя сокращения для различных вариантов. Например, команда для поиска подписей функций в файле с именем test_debug.py выглядит следующим образом:
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 ():С другой стороны, наказание использует пакеты Python, такие как Typer и Rich, чтобы предоставить удобный пользовательский и богатый функции интерфейс командной строки. Доступные команды для наказания включают:
С точки зрения функциональности, Symbex предназначен для поиска кода Python для функций и классов по имени или подстановочному знаку. Он обеспечивает возможность фильтровать результаты на основе различных критериев, включая тип функции (асинхронизация или несинхрочные), наличие документации, видимость и аннотации типа.
С другой стороны, команда analyze Hasten выполняет анализ AST на исходном коде Python. Это позволяет пользователям указать имя проекта, версию XPath, путь поиска и различные критерии фильтрации. Наслаждается проверкой для включения и исключения на основе атрибутов, значений и соответствующих уровней доверия. Инструмент также предоставляет обширные параметры конфигурации и возможность сохранять результаты в различных форматах, включая разметку.
Таким образом, в то время как как наказывают, так и Symbex служат общей цели анализа исходного кода Python, Casten предлагает более универсальный и удобный CLI с дополнительными функциями конфигурации и управления результатами. Symbex, с другой стороны, принимает краткий CLI с акцентом на поиск и фильтрацию функциональных возможностей. Выбор между двумя инструментами зависит от предпочтений пользователя и конкретных требований для анализа кода Python.
В дополнение к Casten и Symbex, несколько других инструментов предлагают уникальные возможности для анализа и поиска через исходный код Python, каждый из которых обслуживает конкретные варианты использования.
