MonkeyType 23.3.0

示例

假设some/module.py最初包含

def add(a, b):
    return a + b

并且myscript.py包含

from some.module import add

add(1, 2)

现在我们想要通过运行myscript.py来推断some/module.py中add的类型注解，使用MonkeyType。一种方法是运行

$ monkeytype run myscript.py

默认情况下，这会将调用跟踪输出到当前工作目录中的 SQLite 数据库文件 monkeytype.sqlite3。然后您可以使用 monkeytype 命令为模块生成存根文件，或将类型注解直接应用于您的代码。

运行 monkeytype stub some.module 将输出一个存根

def add(a: int, b: int) -> int: ...

运行 monkeytype apply some.module 将修改 some/module.py

def add(a: int, b: int) -> int:
    return a + b

此示例演示了 MonkeyType 的价值和局限性。使用 MonkeyType，很容易添加反映运行时实际使用的具体类型的注解，但这些注解可能并不总是与函数的完整预期功能匹配。例如，add 可以处理比整数多得多的类型。同样，MonkeyType 可能会生成一个具体的 List 注解，而一个抽象的 Sequence 或 Iterable 可能更合适。MonkeyType 的注解是一个信息性初稿，需要由开发者检查和修正。

动机

可读性和静态分析是向代码添加类型注解的主要动机。在许多 Python 风格指南中，已经在函数的文档字符串中记录了函数的参数和返回类型；注解是提供此类文档的标准化方式，它还允许类型检查器（如 mypy）进行静态分析。

有关 Python 类型注解的动机和设计，请参阅 PEP 483 和 PEP 484。

要求

MonkeyType 需要 Python 3.7+ 和 libcst 库（用于将类型存根应用到代码文件）。它仅生成 Python 3 类型注解（没有类型注释）。

安装

使用 pip 安装 MonkeyType

pip install MonkeyType

MonkeyType 的工作原理

MonkeyType 使用 Python 提供的 sys.setprofile 钩子来拦截函数调用、函数返回和生成器产生，并记录参数/返回值/产生值的类型。

它根据这些数据生成 存根文件，并可以使用 libcst 将这些存根文件直接应用到您的代码。

有关详细信息，请参阅 完整文档。

故障排除

检查您的问题是否在 常见问题列表 中提及。

开发

有关 MonkeyType 的开发和贡献信息，请参阅 CONTRIBUTING.rst。

授权

MonkeyType 是 BSD 授权。

23.3.0

• 向 apply 命令添加 --pep_563 标志。感谢 Sagar Badiyani。合并 #282，修复 #111 和 #203。

• 删除对 Django 的硬依赖；现在根据是否可导入，有条件地启用 django.utils.functional.cached_property 支持。

• 添加对 Python 3.11 的支持。

22.2.0

• 停止支持 Python 3.6。

• 修复在 Python 3.9 上生成存根时出现的 AttributeError: __args__。感谢 GameDungeon 和 ntjess 的报告。修复 #231。

• 修复收集具有联合类型的跟踪时出现的 AttributeError: ‘_SpecialForm’ 对象没有属性 ‘__name__’。感谢 Federico Caselli 的报告。修复 #243。

21.5.0

• 修复与 Python 3.9 的兼容性。感谢 Felix Yan。合并 #217，修复 #205。

• 正确渲染空元组的类型。感谢 Pradeep Kumar Srinivasan。合并 #191，修复 #190。

20.5.0

• 需要 libcst>=0.3.5。

• 向 apply 命令添加 --ignore-existing-annotations 标志。

20.4.2

• 在 setup.py 中添加缺失的 libcst 依赖。

20.4.1

• 为嵌套在泛型类型中的 TypedDicts 生成存根。当最大大小为零时，完全禁用 TypedDicts。感谢 Pradeep Kumar Srinivasan。合并 #162，修复 #159。

• 移除 stringcase 依赖，仅手动实现 pascal_case 函数。

• 通过必要的和可选的键缩小字典跟踪，以获取非总体的 TypedDict 类声明。感谢 Pradeep Kumar Srinivasan。

• 使用 libcst 的 ApplyTypeAnnotationsVisitor 实现 monkeytype apply。这正确地应用生成的 TypedDict 类。感谢 Pradeep Kumar Srinivasan。

• 递归渲染泛型类型，以处理嵌套的特殊情况，如 List['Movie']。感谢 Pradeep Kumar Srinivasan。修复 #76。

19.11.2

• 由于它会破坏 –apply，因此现在默认禁用 TypedDict 生成。

19.11.1

• 添加 setup.py 依赖项 mypy-extensions 和 stringcase。感谢 Nicholas Bollweg 提供的报告。

19.11.0

• 为字典（最多到配置的最大大小）跟踪每个键的值类型，如果跟踪的类型一致，则在存根中输出 TypedDict 而不是同构字典。感谢 Pradeep Kumar Srinivasan。合并 #143，修复 #105。

• 修复空元组导致的崩溃。感谢 akayunov 提供的报告，Christophe Simonis 提供的最简单情况复现。修复 #136。

• 不要将字符串化的注释添加到类型存根中。感谢 Łukasz Langa。合并 #148。

• 在类型重写器中不要崩溃，因为用户定义的类型与 typing 模块中的容器类型命名冲突。感谢 Łukasz Langa。合并 #146。

• 在解析参数之前而不是期间加载配置，以避免 argparse 在自定义配置的导入时间捕获 TypeError/ValueError，并用通用的“无效值”消息替换。参见 https://bugs.python.org/issue30220。感谢 Daniel G Holmes 提供的报告。合并 #142，修复 #141。

• 为 collections.defaultdict 添加类型支持。感谢 Dinesh Kesavan。合并 #152。

19.5.0

• 根据 PEP 561 将 monkeytype 包标记为已类型化。感谢 Vasily Zakharov 提供的报告。

• 添加 -v 选项；除非提供，否则不要显示无法解码的单独跟踪。

19.1.1

• 在应用存根时传递 --incremental，以便它不会因部分存根（例如某些跟踪的解码失败）而窒息。

19.1.0

• 添加 --omit-existing-annotations 选项，由 apply 暗示。合并 #129。修复 #11 和 #81。

• 在存根中渲染所有参数默认值 ...。删除 CLI 选项 --include-unparsable-defaults 和 --exclude-unparsable-defaults 以及配置方法 include_unparsable_defaults()。合并 #128，修复 #123。

• 正确渲染前向引用（来自现有注释）。合并 #127。

• 默认将 Generator[…, None, None] 重写为 Iterator[None]。合并 #110，修复 #4。感谢 iyanuashiri。

18.8.0

• 支持 Python 3.7。合并 #107，修复 #78。

• 当将文件名传递给存根/应用时打印有用的错误消息。合并 #88，修复 #65。感谢 rajathagasthya。

• 修复在 list_modules 中没有跟踪时的崩溃。合并 #106，修复 #90。感谢 tyrinwu。

• 启用 python -m monkeytype {run,stub,apply} ...。合并 #100，修复 #99。感谢 retornam。

18.5.1

• 添加环境变量 MONKEYTYPE_TRACE_MODULES 以更容易地跟踪 site-packages 中的代码。合并 #83，修复 #82。感谢 Bo Peng。

• 修复通过< span class="docutils literal"> monkeytype run 运行脚本时传递额外参数的问题。合并#85。感谢邱丹尼。

• 修复将文件名传递给retype时处理空格的问题。合并#79，修复#77。

• 在存根中永不渲染NoneType，用None替代。合并#75，修复#5。感谢约翰·阿诺德。

18.2.0

• 将< cite> __main__ 模块的过滤移至CallTraceStoreLogger而不是核心跟踪代码，以便它可以被IPython跟踪等特殊用例覆盖。合并#72，修复#68。感谢托尼·快速。

• 为模块文件类似于module/__init__.py的模块生成存根。打印retype的stdout/stderr。合并#69，修复#66。感谢约翰·阿诺德。

18.1.13

• 改进在“找不到跟踪”和/或文件路径给定而不是模块名称时出现的错误消息。合并#37，部分修复#65。感谢阿尼·科斯凯拉。

• 添加< span class="docutils literal"> monkeytype list_modules 子命令以列出在跟踪数据库中存在的所有模块。合并#61，修复#60。感谢亚历克斯·米亚索耶多夫。

• 将< span class="docutils literal">< span class="pre"> --diff 选项添加到< span class="docutils literal"> monkeytype stub 。合并#59，修复#58。感谢泰林！

• 将< span class="docutils literal">< span class="pre"> --ignore-existing-annotations 选项添加到< span class="docutils literal"> monkeytype stub 。合并#55，修复#15。感谢泰林！

18.1.11

• 修复RewriteEmptyContainers重写器中参数仅包含空容器类型（且不止一个）时的崩溃问题。修复#53。

18.1.10

• 当存根应用程序失败时显示retype错误。合并#52，修复#49。

• 将< span class="docutils literal">< span class="pre"> --sample-count 选项添加以显示给定存根基于的跟踪数量。合并#50，修复#7。感谢泰林。

• 添加< span class="docutils literal"> monkeytype run < span class="pre"> -m 以作为脚本运行模块。合并#41。感谢西蒙·戈米泽。

• 添加对Django的< span class="docutils literal"> cached_property 装饰器的支持。合并#46，修复#9。感谢王克里斯托弗。

• 捕获并记录序列化异常而不是崩溃。修复#38，合并#39。

• 修复当Python库路径是符号链接时默认代码过滤器中的错误。合并#40。感谢西蒙·戈米泽。

17.12.3

• 将_from _io模块的导入重写为io。（#1，合并#32）。感谢拉丹·贾达奥。

• 将Config.cli_context()作为自定义CLI初始化和清理逻辑的钩子（#28；合并#29）。感谢罗德尼·福尔兹。

17.12.2

• 在默认代码过滤器中排除“冻结的importlib”函数。

• 修复使用< span class="docutils literal"> monkeytype run 运行脚本时的参数传递（#18；合并#21）。感谢罗德尼·福尔兹。

• 修复为NewType类型生成的注释（#22；合并#23）。感谢罗德尼·福尔兹。

17.12.1

• 修复在虚拟环境外使用MonkeyType（#16）。感谢吉多·范·罗苏姆的报告。

17.12.0

• 初始公开版本。