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>填充<path to chasten-configuration/directory | config url>后， chasten configure validate --config <path to chasten-configuration/ directory | config url> | <path to chasten-configuration/directory | config 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 fiximports和/或poetry run task 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源代码进行分析和搜索的独特功能，每个工具都适合特定用例。
