AexPy /eɪkspaɪ/是PY thon 中的一个pi EX plorer，用于检测 Python 包中的 API 重大更改。

AexPy 是10 月 31 日至 11 月 3 日在美国北卡罗来纳州夏洛特市举行的第 33 届 IEEE 软件可靠性工程国际研讨会 ( ISSRE 2022 ) 会议论文集“ AexPy: Detecting API Breaking Changes in Python Packages ”的原型实现， 2022 年。

如果您在工作中使用了我们的方法或结果，请根据引文文件进行引用。

https://user-images.githubusercontent.com/34736356/182772349-af0a5f20-d009-4daa-b4a9-593922ed66fe.mov

• AexPy 是如何工作的？方法设计和评估在 AexPy 的会议论文中（即将发表）。
• 我们如何实现 AexPy？源代码和实现在AexPy 的存储库中。
• 如何使用 AexPy？详细的文档和数据在AexPy 的网站上。

graph LR;
    Package-->Version-1;
    Package-->Version-2;
    Version-1-->Preprocessing-1;
    Version-2-->Preprocessing-2;
    Preprocessing-1-->Extraction-1;
    Preprocessing-2-->Extraction-2;
    Extraction-1-->Difference;
    Extraction-2-->Difference;
    Difference-->Evaluation;
    Evaluation-->Breaking-Changes;

AexPy 还提供了一个框架来处理 Python 包、提取 API 和检测更改，该框架旨在轻松重用和定制。有关详细信息，请参阅以下“高级工具”部分和源代码。

特征

• 预处理
  • 构建包并获取源代码。
  • 计算包文件大小和代码行数。
  • 读取包元数据并检测顶级模块。
• 提取
  • 从 Python 包中提取 API，包括模块、类、函数、属性。
  • 收集详细的API，包括参数、实例属性。
  • 检测 API 别名并构建调用图。
  • 通过静态类型分析器丰富 API 的类型信息。
• 差异化
  • 在两个版本之间配对 API 后检测 API 更改。
  • 根据他们的严重程度改变等级。
• 报告
  • 为 API 更改检测结果生成人类可读的报告。
• 配料
  • 批量处理包和发布。
• 框架
  • 自定义实施细节。
  • 使用日志记录和缓存在 AexPy 的通用管道中定义自定义处理器和处理 Python 包。
  • 为 API 描述、更改等生成 JSON 格式的可移植数据。
  • 通过 AexPy 的命令行/RESTful API/前端执行处理和查看数据。

安装

我们建议使用我们的 Docker 镜像来运行 AexPy。其他发行版可能会受到环境错误的影响。

docker pull stardustdl/aexpy:latest

# or the image from the main branch

docker pull stardustdl/aexpy:main

要运行原始包而不是图像，请确保您的 Python 解释器在UTF-8 模式下工作。

用法

前端

AexPy 为探索 API 和更改提供了一个方便的前端。http://localhost:8008使用以下命令启动服务器，然后在浏览器中访问前端。

docker run -p 8008:8008 stardustdl/aexpy:latest serve

前端依赖于端点处的 AexPy 的 RESTful API /api。

命令行

使用以下命令检测名为 demo 的包的 v1.0 和 v2.0 之间的更改：

docker run stardustdl/aexpy:latest report demo@1.0:2.0

# e.g. detect API changes between jinja2 v3.1.1 and v3.1.2
docker run stardustdl/aexpy:latest report jinja2@3.1.1:3.1.2

使用以下命令提取名为 demo 的包 v1.0 的 API 信息：

docker run stardustdl/aexpy:latest extract demo@1.0

# e.g. extract APIs from click v8.1.3
docker run stardustdl/aexpy:latest extract click@8.1.3

对于所有可用命令，请使用以下命令：

docker run stardustdl/aexpy:latest --help

高级工具

配料

AexPy 支持批量处理包的所有可用版本。

aexpy batch coxbuild

日志记录

处理可能会花费时间，您可以将多个-v用于详细日志。

docker run aexpy:latest -vvv extract click@8.1.3

数据

您可以挂载缓存目录/data来保存处理后的数据。AexPy 将使用缓存数据（如果存在），并在缓存目录下生成 JSON 格式的结果。

docker run -v /path/to/cache:/data aexpy:latest extract click@8.1.3

cat /path/to/cache/extracting/types/click/8.1.3.json

管道

AexPy 在其管道中有四个阶段，使用以下命令运行相应的阶段。

aexpy preprocess coxbuild@0.0.1
aexpy extract coxbuild@0.0.1
aexpy diff coxbuild@0.0.1:0.0.2
aexpy report coxbuild@0.0.1:0.0.2

这四个阶段是松散耦合的。相邻阶段通过 JSON 传输数据，在模型目录中定义。您可以轻松地为每个阶段编写自己的实现，并将您的实现组合到管道中。有关如何实现阶段和集成其他工具的示例，请参见第三个目录。