PyAnnotate：自动生成PEP-484注释

根据运行时观察到的调用参数和返回类型将注释插入到源代码中。

有关许可和版权信息，请参阅本文件末尾。

博客文章：http://mypy-lang.blogspot.com/2017/11/dropbox-releases-pyannotate-auto.html

如何使用

请参阅示例目录。

阶段 1：收集运行时类型

• 按照常规方式安装（见下文“繁琐流程”部分）
• 将from pyannotate_runtime import collect_types添加到您的测试中
• 在测试设置初期，请调用 collect_types.init_types_collection()
• 在调用 collect_types.start() 和 collect_types.stop() 之间包围你的测试执行（或者使用下面的上下文管理器）
• 完成后，调用 collect_types.dump_stats(filename)

start() 和 stop() 之间的所有调用将被分析，观察到的类型将被写入（以 JSON 格式）到传递给 dump_stats() 的文件名。每个导出调用可以包含多个 start/stop 对。

如果您想在运行 pytest 时自动收集类型，请参阅 example/example_conftest.py 和 example/README.md。

除了使用 start() 和 stop() 之外，您还可以使用上下文管理器

collect_types.init_types_collection()
with collect_types.collect():
    <your code here>
collect_types.dump_stats(<filename>)

第二阶段：将类型插入到您的源代码中

命令行工具 pyannotate 可以根据第一阶段收集的注释将注释添加到您的源代码中。关键参数包括

• 使用 --type-info FILE 告诉它传递给 dump_stats() 的文件
• 位置参数是要注释的源文件
• 如果没有其他标志，工具将打印一个 diff，表明它建议执行的操作，但不会实际执行。请审查输出。
• 添加 -w 使工具实际更新您的文件。（请使用 git 或其他方式备份。）

此时，您可能需要运行 mypy 并迭代。您可能需要调整更改以使 mypy 完全满意。

注意事项和技巧

• 最好一次处理一个文件，至少直到您对工具感到舒适。
• 工具不会触及已经具有注释的函数。
• 工具可以生成以下任一项
  • 类型注释，即 Python 2 风格的注释
  • 内联类型注释，即 Python 3 风格的注释，使用 v1.0.7+ 中的 --py3

繁文缛节

安装

这应该适用于 Python 2.7，以及 Python 3.4 及更高版本。

pip install pyannotate

这安装了几个项目

• 一个运行时模块，pyannotate_runtime/collect_types.py，它使用配置钩子收集和导出在运行时观察到的类型。

• 一个库包，pyannotate_tools，包含可以读取运行时模块导出的数据并将注释插入源代码的代码。

• 一个入口点，pyannotate，它在您的文件上运行库包。

有关依赖项，请参阅 setup.py 和 requirements.txt。

测试等。

要运行单元测试，请使用 pytest

pytest

待办事项

我们很乐意您帮助解决这些问题

• 更好的文档。
• Python 3 代码生成。
• 重构工具模块（目前遗留架构显而易见）。

致谢

以下人员对这款工具做出了重大贡献

• 托尼·格鲁
• 谢尔盖·沃罗比耶夫
• 尤卡·莱赫托萨拉
• 吉多·范罗苏姆

许可证等。

1. 许可证：Apache 2.0。
2. 版权归属：版权所有（c）2017 Dropbox，Inc。
3. 项目的外部贡献应受 Dropbox 的贡献者许可协议（CLA）的约束：https://opensource.dropbox.com/cla/