chasten
v0.2.0: Merge pull request #81 from AstuteSource
Chasten是一個Python程序，它使用XPath表達式在Python程序的抽象語法樹（AST）中找到模式。您可以使用Chasten快速實施自己的可配置的覆蓋規則，而無需使用複雜的AST分析框架或求助於不精確的正則表達式。
您是否要確保Python程序在async函數內部的for中沒有任何三圈？或者，您是否要確認Python程序中的每個功能都有類型的註釋和docstring評論？查斯頓可以幫忙！它允許您在包含XPath表達式的簡單YAML文件中表達這些檢查以及許多其他類型的分析。
Chasten （瞬態動詞）“使某人意識到失敗或犯錯了”，劍橋詞典。
Chasten （無數或單數名詞）“一種工具，分析了Python程序的抽象語法樹，以檢測程序員錯誤的潛在來源，以防止程序失敗”，Astutesoutsource開發人員。
chasten提醒我在main.py中的所有功能中添加docstrings和鍵入註釋。很容易看到要解決的問題！”chasten使我可以輕鬆地可靠地確認學生計劃具有所需的編碼結構。這比使用正則表達式要好得多！”chasten使我很有趣，很容易對我維護的Python代碼庫進行自動分析。”chasten的分析儀表板還可以有效地探索收集的數據。” 請按照以下步驟安裝chasten程序：
pipx install chasten以安裝Chastenpipx list並確認安裝了Chastenchasten --help學習如何使用該工具您可以使用兩個YAML文件配置chasten ，通常稱為config.yml和checks.yml 。儘管chasten可以生成起始配置，但是您可以檢查嗎？ ASTUTESOURCE/CHASTEN-CONFIGURATION存儲庫，例如設置該工具的配置文件。儘管config.yml文件可以引用多個檢查配置文件，但此示例顯示瞭如何指定單個checks.yml 。
# chasten configuration
chasten :
# point to a single checks file
checks-file :
- checks.yml checks.yml文件必須包含一個或多個檢查。接下來是一個檢查配置文件的示例，其中有兩個檢查，這些檢查分別在Python項目中找到了第一個可執行的非測試和測試案例功能。請注意， pattern屬性指定chasten將用於檢測Python函數類型的XPath版本2.0表達式。您可以鍵入chasten configure validate --config <path to chasten-configuration/ directory | config url> |配置url>帶有配置目錄的完全歸結名稱，該工具將確認您的配置符合工具的規範。您還可以使用命令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需要一個帶有Python源代碼的項目作為其analysis子命令的輸入，您可以克隆？ ASTUTESOURCE/LAZYTRACKER和？ Astutesource/Multiver Ounterion存儲庫是為方便分析而創建的現有Python項目的分叉。要用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/目錄之後，您可以運行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在multicounter項目中找到了10測試功能。如果您查看subject-data/lazytracker目錄，您會找到一個帶有諸如chasten-results-multicounter-20230821171712-5c52f2f1b61b4cce97624cc34cb39d4f.json和名稱組件的JSON文件，該multicounter類似於與JSON相似的編號。
由於all-test-function-definition檢查指定該程序必須在1到10測試之間，因此您會注意到此檢查通過lazytracker和multicounter 。這意味著chasten返回一個0錯誤代碼，與支票傳遞的操作系統通信。
您可以通過鍵入chasten analyze --help了解有關如何使用analyze子命令的更多信息。例如， chasten支持--check-include和--check-exclude選項，這些選項允許您分別根據模糊匹配規則分別包括並排除特定的支票，您可以為checks.yml文件中指定的任何檢查的屬性指定這些匹配規則。
在lazytracker和multicounter程序上運行chasten後，您可以將其單個JSON文件集成到單個JSON文件，相關的CSV文件和SQLITE數據庫中。製作integrated-data/目錄後，您可以鍵入此命令以執行集成：
chasten integrate all-programs
< path to subject-data > / ** / * .json
--save-directory < path to the integrated-data/ directory >該命令將產生一個目錄，例如chasten-flattened-csvs-sqlite-db-all-programs-20230823171016-2061b524276b4299b04359ba30452923/其中包含一個名為chasten.db的SQLITE數據庫和csv/ cosv/ cosv/ cosv/ cosv/ cosv/ cosv/ cosv/ cosv/ cosv/ c。 資料庫.
您可以通過鍵入chasten integrate --help來了解有關integrate子命令的更多信息。
當使用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報告說，即使pytest僅找到並運行5測試，也有6測試用例。這是由於tests/test_tracked.py test套件在lazytracker中包含一個以test_開頭test_函數的事實。此示例說明了用chasten靜態分析的局限性！即使該工具正確地檢測到了所有“測試功能”，但測試套件中功能的嵌套意味著pytest將運行外test_函數並將內部test_功能用於測試目的。
話雖如此， chasten正確地找到了multicounter項目的每個測試。您可以按照本文檔中的每個步驟遵循chasten將其應用於您自己的Python程序！
如果您想使您的chasten.db公開可供所有人學習，則可以使用chasten datasette-publish子命令。只要您遵循安裝說明？ simonw/datasette-publish-fly和？ simonw/datasette-publish-vercel，您可以使用插件來部署託管您的chasten.db的公共datasette集服務器。例如，運行命令chasten datasette-publish <path containing integrated results>/chasten.db --platform vercel將在lazytracker上運行chasten和multicounter的結果將結果發佈到Vercel Platform。
重要的是，使用--platform vercel選項使用chasten datasette-publish命令，您以前遵循datasette-publish-vercel插件的說明來安裝vercel命令行工具。這是必要的，因為儘管datasette-publish-vercel是chasten的依賴性之一，即使使用它，也不是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：
cd進入Dockerfile所在的Chasten目錄docker 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需求！ Black和Ruff絨毛工具來確保代碼的一致性，可讀性和遵守整個項目的預定格式標準，最終增強了開發人員之間的可維護性和協作。poetry run task fixformat poetry run task fiximports FixFormat在運送新功能之前。如果功能帶有刺傷問題，則由於測試套件的故障，該構建將在GitHub上破裂。Pytest和Hypothesis ，使我們能夠在整個項目中與既定的格式標準相結合，可讀性和一致性。在為功能編寫測試用例時，請在測試目錄中創建一個新文件，並使用命名慣例test_(name of file)創建一個新文件。poetry run task test ，或者如果您想測試基於OpenAI API的功能poetry run task test-api 。如果未經測試套件發貨，則由於添加了未經測試的代碼，將在GitHub上降低覆蓋範圍，並且將來可能會導致更大的問題。 由西蒙·威利森（Simon Willison）創建的Chasten和Symbex都是設計用於分析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 ():另一方面，Chasten利用Python軟件包（例如Typer and Rich）提供了一種用戶友好且功能豐富的命令行界面。 Chasten的可用命令包括：
在功能方面，SYMBEX旨在通過名稱或通配符搜索Python代碼以獲取功能和類。它提供了基於各種標準過濾結果的能力，包括功能類型（async或non-ashnc），文檔存在，可見性和類型註釋。
另一方面，Chasten的analyze命令對Python源代碼執行AST分析。它允許用戶指定項目名稱，XPATH版本，搜索路徑和各種過濾標準。 Chasten支持基於屬性，值和匹配置信度級別的支票包含和排除。該工具還提供了廣泛的配置選項以及以不同格式保存結果的能力，包括Markdown。
總而言之，儘管Chasten和Symbex都提供了分析Python源代碼的共同目的，但Chasten提供了更廣泛和用戶友好的CLI，並具有配置和結果管理的其他功能。另一方面，Symbex採用了簡潔的CLI，重點是搜索和過濾功能。兩種工具之間的選擇取決於用戶的偏好和Python代碼分析的特定要求。
除了Chasten和Symbex外，其他幾種工具還提供了通過Python源代碼進行分析和搜索的獨特功能，每個工具都適合特定用例。
