chasten
v0.2.0: Merge pull request #81 from AstuteSource
Chastenは、XPath式を使用してPythonプログラムの抽象的構文ツリー（AST）のパターンを見つけるPythonプログラムです。 Chastenを使用して、複雑なAST分析フレームワークを使用したり、不正確な正規表現を使用したりすることなく、独自の構成可能な糸くずルールをすばやく実装できます。
Pythonプログラムに、 async関数内のループforトリプルネストがないことを確認しますか？または、Pythonプログラム内のすべての機能にタイプの注釈とDocstringコメントがあることを確認しますか？チャステンは助けになります！ XPath式を含む簡単なYAMLファイルで、これらのチェック、および他の多くのタイプの分析も表現できます。
Chasten （Transitive Verb）「失敗や何か間違ったことをしたことを誰かに認識させるために」Cambridge Dictionary。
Chasten （数え切れないほどの名詞または単数名詞）「Pythonプログラムの抽象的な構文ツリーを分析して、プログラムの故障を防ぐためにプログラマーミスの潜在的なソースを検出するツール」、Astutesource開発者。
chasten main.pyのすべての機能にドキュストリングとタイプの注釈を追加することを思い出させてくれてうれしいです。何を修正するかを簡単に確認できました！」chasten 、学生プログラムに必要なコーディング構造があることを確実に確認することを簡単に確認できます。通常の表現を使用するよりもはるかに優れています！」chasten私が維持しているPythonコードベースの自動分析を楽しく簡単に行うことができました。」chastenの分析ダッシュボードでは、収集したデータを効果的に調査できます。」 これらの手順に従って、 chastenプログラムをインストールします。
pipx install chasten Chastenをインストールしますpipx listを入力し、Chastenがインストールされていることを確認しますchasten --helpツールの使用方法を学ぶためにヘルプ通常、 config.ymlとchecks.ymlと呼ばれる2つのyamlファイルでchastenを構成できます。 chasten開始構成を生成できますが、チェックアウトできますか？ツールをセットアップする構成ファイルの場合、Astutesource/chasten-configurationリポジトリ。 config.ymlファイルは複数のチェック構成ファイルを参照できますが、この例は単一のchecks.ymlファイルを指定する方法を示しています。
# chasten configuration
chasten :
# point to a single checks file
checks-file :
- checks.yml checks.ymlファイルには、1つ以上のチェックが含まれている必要があります。以下は、Pythonプロジェクトでテストとテストケース機能の最初の実行可能ラインをそれぞれ見つける2つのチェックを備えたチェック構成ファイルの例です。 pattern属性は、 chasten指定されたタイプのPython関数を検出するために使用するXPathバージョン2.0式を指定することに注意してください。 chasten configure validate --config <path to chasten-configuration/ directory | config url> <path to chasten-configuration/directory | config url>構成ディレクトリの完全に資格のある名前を使用して、構成が完全に認定された名前<path to chasten-configuration/directory | config url>使用して、構成がツールの仕様を満たしていることを確認します。また、Command chasten configure createコマンドを使用して、開始構成を自動的に生成することもできます。 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 、 analysisサブコマンドへの入力としてPythonソースコードを使用したプロジェクトを必要とするため、クローンを作成できますか？ astutesource/lazytrackerと？便利な分析のために作成された既存のPythonプロジェクトのフォークであるAstuteSource/Multicounterリポジトリ。これら2つのプロジェクトをchastenを使用して徐々に分析するには、次のコマンドを入力して、各プロジェクトの結果JSONファイルを作成できます。
lazytracker/ Directoryを含むsubject-data/ディレクトリを作成した後、 lazytrackerプログラムのchasten analyzeコマンドを実行できます。 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 lazytrackerプロジェクトで6テスト機能を見つけることを確認できます。 subject-data/lazytrackerディレクトリを見ると、 chasten-results-lazytracker-20230823162341-4c23fc443a6b4c4aa09886f1ecb96e9f.jsonのような名前のJSONファイルがあります。このプログラムでchasten複数回実行すると、異なるタイムスタンプ（IE、 20230823162341 ）と一意の識別子（つまり、 4c23fc443a6b4c4aa09886f1ecb96e9f ）を備えた新しい結果ファイルが--saveされます。
既存のsubject-data/ディレクトリにmulticounter/ /ディレクトリを作成した後、 multicounterプログラムのchasten analyzeコマンドを実行できます。
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 multicounterプロジェクトで10テスト機能を見つけることを確認できます。 subject-data/lazytrackerディレクトリを見ると、 chasten-results-multicounter-20230821171712-5c52f2f1b61b4cce97624cc34cb39d4f.jsonおよび名前のコンポーネントが、JSONファイルに類似しているmulticounterに似たコンポーネントのような名前があります。
all-test-function-definitionチェックは、プログラムに1 10テストが必要であることを指定しているため、このチェックがlazytrackerとmulticounter両方に合格していることに気付くでしょう。これは、 chasten 0エラーコードを返して、チェックが合格したオペレーティングシステムと通信することを意味します。
chasten analyze --helpを入力することにより、 analyzeサブコマンドの使用方法について詳しく知ることができます。たとえば、 chasten 、 checks.ymlファイルで指定されているチェックの属性を指定できるファジーマッチングルールに従って、それぞれ特定のチェックを含めて除外できる--check-includeおよび--check-excludeオプションをサポートします。
lazytrackerおよびmulticounterプログラムでchastenを実行した後、個々のJSONファイルを単一のJSONファイル、関連するCSVファイル、およびSQLiteデータベースに統合できます。 integrated-data/ Directoryを作成したら、このコマンドを入力して統合を実行できます。
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データベース。
chasten integrate --helpを入力することにより、 integrate Sub-Commandの詳細について詳しく知ることができます。
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実行できます。これで、Webブラウザのダッシュボードを使用して結果を分析できます。これらのプロジェクトのソースコードをエディターで調査できます。結果を調べると、その使用を通してchastenが明らかになりますか？ spookylukey/pyastgrepは、Xpath式をall-test-function-definitionに正しく使用して、各テスト内の実行可能ソースコードの最初の行を見つけ、関数のドキュストリングと主要なコメントをスキップします。
lazytrackerプログラムの場合、 pytest 5テストのみを見つけて実行している場合でも、 chasten 6テストケースがあると報告していることに気付くでしょう。これは、 lazytrackerのtests/test_tracked.pyテストスイートには、 test_から始まる別の関数内のtest_から始まる関数が含まれているためです。この例は、 chastenによる静的分析の制限を示しています！ツールはすべての「テスト関数」を正しく検出しましたが、テストスイートの関数のネストは、 pytest外側のtest_関数を実行し、テスト目的で内側のtest_関数を使用することを意味します。
そうは言っても、 chasten multicounterプロジェクトの各テストを正しく見つけます。このドキュメントの以前の各手順に従って、 chasten独自のPythonプログラムに適用できます！
chasten.dbをすべての人が勉強できるように公開したい場合は、 chasten datasette-publish sub-commandを使用できます。インストールの指示に従っている限り？ simonw/datasette-publish-fly and？ Simonw/Datasette-Publish-Vercelでは、プラグインを使用して、 chasten.dbホストするパブリックdatasetteサーバーを展開できます。たとえば、コマンドchasten datasette-publish <path containing integrated results>/chasten.db --platform vercelの実行は、 lazytrackerおよびmulticounterでchastenを実行した結果をVercelプラットフォームに公開します。
重要なことに、 --platform vercelオプションを使用してchasten datasette-publishコマンドを使用するには、以前にdatasette-publish-vercelプラグインの指示に従ってvercelコマンドラインツールをインストールする必要があります。これは、 datasette-publish-vercelがchastenの依存関係の1つであるため、 chastenもdatasette-publish-vercelも使用している場合でもvercelツールを提供しないためです。飛行するためにデータベースを公開する前に、同様の手順を実行する必要があります！
chastenはコマンドラインアプリケーションですが、ターミナルユーザーインターフェイス（TUI）を介してツールのコマンドライン引数とオプションをインタラクティブに作成します。 TUIベースの方法を使用してchasten用の完全なコマンドラインを作成するには、 chasten interact入力できます。
Chastenには、組み込みシステムログがあります。 Chastenを使用している間、端末にchasten log使用することができます。システムログ機能により、ユーザーはchastenによって作成されたイベントやメッセージを表示できます。さらに、 chasten log機能は、バグとバグの発生につながったイベントを見つけるのに役立ちます。 chastenプログラムがシステムログに表示するには、別の端末を開き、 chasten logを使用する必要があります。さらに、 --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と詩がインストールされたら、GithubのChastenリポジトリに移動し、端末のgit cloneコマンドを使用してツールをインストールしてください。次に、Chastenディレクトリに移動し、コマンドpoetry installを実行して、すべての依存関係をインストールします。
Dockerを使用してchastenを使用するオプションもあります
これらの手順に従って、Dockerを利用します。
Dockerfileが配置されているchastenディレクトリへのcddocker 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>依存関係を保存するchastenのニーズにDockerを使用できます！ BlackとRuffを使用して、プロジェクト全体でコードの一貫性、読みやすさ、および事前定義されたフォーマット基準を順守し、最終的に開発者間の保守性とコラボレーションを強化します。poetry run task fiximportsおよび/またはpoetry run task fixformat新しい機能を出荷する前に。機能に糸くずの問題が発生した場合、テストスイートの障害によりビルドがGitHubで壊れます。PytestとHypothesisを使用して、プロジェクト全体で確立されたフォーマット標準とコードの一貫性、読みやすさ、および整合性を強化することができます。機能のテストケースを作成するときは、Naming Convention test_(name of file)を使用して、Tests Directoryに新しいファイルを作成します。poetry run task testまたは出荷前にOpenai APIベースの機能をテストする場合はpoetry run task test-apiテストしたい場合。テストスイートなしで機能が出荷されると、テストされていないコードが追加されているため、GitHubでカバレッジが下げられ、将来的にはより大きな問題につながる可能性があります。 Simon Willisonによって作成されたChastenとSymbexは、特にファイル内の機能とクラスの検索に焦点を当てたPythonソースコードを分析するために設計されたツールです。彼らは共通の目標を共有していますが、特にコマンドラインインターフェイスと機能の観点から、2つの間に顕著な違いがあります。
コマンドラインインターフェイスに関しては、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 ():一方、Chastenは、TyperやRichなどのPythonパッケージを活用して、ユーザーフレンドリーで機能が豊富なコマンドラインインターフェイスを提供します。チャステンのために利用可能なコマンドは次のとおりです。
機能性の観点から、Symbexは、名前またはワイルドカードで機能とクラスのPythonコードを検索するように設計されています。関数タイプ（非同期または非アジン）、ドキュメントの存在、可視性、およびタイプの注釈など、さまざまな基準に基づいて結果をフィルタリングする機能を提供します。
一方、Chastenのanalyzeコマンドは、PythonソースコードでAST分析を実行します。ユーザーは、プロジェクト名、XPathバージョン、検索パス、およびさまざまなフィルタリング基準を指定できます。 Chastenは、属性、値、および一致の信頼レベルに基づいて、包含および除外のチェックをサポートしています。このツールは、広範な構成オプションと、マークダウンを含むさまざまな形式で結果を保存する機能も提供します。
要約すると、ChastenとSymbexの両方がPythonソースコードを分析するという共通の目的を果たしていますが、Chastenは、構成と結果管理の追加機能を備えた、より汎用性の高いユーザーフレンドリーなCLIを提供します。一方、Symbexは、検索とフィルタリングの機能に焦点を当てた簡潔なCLIを採用しています。 2つのツールの選択は、ユーザーの好みとPythonコード分析の特定の要件に依存します。
ChastenとSymbexに加えて、他のいくつかのツールは、Pythonソースコードを分析および検索するためのユニークな機能を提供します。それぞれが特定のユースケースに対応しています。
