当我重构代码时，我经常发现自己枯燥地添加类型注解，这些注解从上下文可以看出：不返回任何内容的函数、布尔标志等。这就是自动类型推断的作用：它会自动添加这些类型并插入正确的注解。

用法

可以从CLI直接调用Autotyping，用作pre-commit钩子或通过libcst接口作为codemod运行。以下是使用CLI的方式：

• pip install autotyping
• python -m autotyping /path/to/my/code

默认情况下，它什么也不做；您必须添加标志以使其执行更多转换。以下是一些支持的项目：

• 注解返回类型
  • --none-return：为没有返回、yield或raise的函数添加-> None返回类型
  • --scalar-return：为只返回bool、str、bytes、int或float对象的函数添加返回注解
• 注解参数类型
  • --bool-param：为默认值为True或False的任何函数参数添加: bool注解
  • --int-param、--float-param、--str-param、--bytes-param：为默认值为int、float、str或bytes对象的任何参数添加注解
  • --annotate-optional foo:bar.Baz：为任何形式为 foo=None 的参数添加从 bar 导入的 Baz 作为类型。例如，使用 --annotate-optional uid:my_types.Uid 为代码库中的任何 uid 添加类型注解，默认为 Optional[my_types.Uid]。
  • --annotate-named-param foo:bar.Baz：为没有默认值的名为 foo 的任何参数添加 bar.Baz。例如，使用 --annotate-named-param uid:my_types.Uid 为代码库中的任何没有默认值的 uid 参数添加类型注解，为 my_types.Uid。
  • --guess-common-names：根据开源 Python 代码中的常见模式推断某些参数类型。例如，推断 verbose 参数的类型为 bool。
• 注释魔法方法
  • --annotate-magics：为某些魔法方法添加类型注解。目前执行以下操作
    • __str__ 返回 str
    • __repr__ 返回 str
    • __len__ 返回 int
    • __length_hint__ 返回 int
    • __init__ 返回 None
    • __del__ 返回 None
    • __bool__ 返回 bool
    • __bytes__ 返回 bytes
    • __format__ 返回 str
    • __contains__ 返回 bool
    • __complex__ 返回 complex
    • __int__ 返回 int
    • __float__ 返回 float
    • __index__ 返回 int
    • __exit__：三个参数是 Optional[Type[BaseException]]、Optional[BaseException] 和 Optional[TracebackType]
    • __aexit__：与 __exit__ 相同
  • --annotate-imprecise-magics：为一些额外的魔法方法添加不精确的类型注解。目前为 __iter__、__await__ 和 __reversed__ 添加 typing.Iterator 返回注解。这些注解应该有一个泛型参数来指示你正在迭代的对象，但对于自动类型推断来说这太难了。
• 外部集成
  • --pyanalyze-report：使用 pyanalyze 的 suggested_parameter_type 和 suggested_return_type 代码建议的类型。你可以使用类似以下命令生成这些代码：pyanalyze --json-output failures.json -e suggested_return_type -e suggested_parameter_type -v .
  • --only-without-imports：仅应用不需要新导入的 pyanalyze 建议。这很有用，因为需要导入的建议可能需要更多手动工作。

有两个快捷标志可以同时启用多个转换

• --safe 启用始终安全的更改。这包括 --none-return、--scalar-return 和 --annotate-magics。
• --aggressive 启用风险更高的更改，更有可能产生新的类型检查器错误。它包括所有 --safe 以及 --bool-param、--int-param、--float-param、--str-param、--bytes-param 和 --annotate-imprecise-magics。

LibCST

自动类型推断作为 LibCST codemod 构建；有关如何使用 codemods 的更多信息，请参阅 LibCST 文档。

如果你希望通过 libcst.tool 接口运行某些内容，你可以这样做

• 确保你有一个包含 'autotyping' 的 .libcst.codemod.yaml 文件，并将其放在 modules 列表中。有关示例，请参阅此存储库中的 .libcst.codemod.yaml。
• 运行 python -m libcst.tool codemod autotyping.AutotypeCommand /path/to/my/code

pre-commit 插件

pre-commit 插件是自动在提交之前运行的脚本，这使得它们非常适合检查和强制执行代码格式（或在这种情况下，类型）。

1. 要将 autotyping 添加为 pre-commit 插件，你首先需要安装 pre-commit，如果你还没有安装的话

pip install pre-commit

2. 之后，在存储库的根目录中创建或更新 .pre-commit-config.yaml 文件，并添加以下内容

- repos:
  - repo: https://github.com/JelleZijlstra/autotyping
    rev: 24.9.0
    hooks:
      - id: autotyping
        stages: [commit]
        types: [python]
        args: [--safe] # or alternatively, --aggressive, or any of the other flags mentioned above 

3. 最后，运行以下命令将 pre-commit 插件安装到你的存储库中

pre-commit install

现在每次您提交更改时，自动类型化会自动为您的代码添加类型注解！

限制

自动类型化旨在成为一个简单的工具，它使用启发式方法来查找手动添加会感到繁琐的注解。启发式方法可能会失败，因此您应该在运行自动类型化后运行类型检查器，以验证它添加的类型是否正确。

已知限制

• 自动类型化不模拟函数中的代码流，因此它可能会错过隐式的 None 返回。

更新日志

24.9.0（2024年9月23日）

• 添加了预提交支持。（感谢Akshit Tyagi和Matthew Akram。）
• 添加了缺少的依赖项。（感谢Stefane Fermigier。）

24.3.0（2024年3月25日）

• 添加了调用自动类型化的更简单方法。现在，您可以使用 python3 -m autotyping 简单地调用此工具。（感谢Shantanu Jain。）
• 停止支持Python 3.7；添加对Python 3.12的支持。（感谢Hugo van Kemenade。）
• 为一些更多的魔法方法推断返回类型。（感谢Dhruv Manilawala。）

23.3.0（2023年3月3日）

• 修复了某些特定参数名称（如 iterables）上的崩溃（由Marco Gorelli贡献）

23.2.0（2023年2月3日）

• 添加了 --guess-common-names（由John Litborn贡献）
• 修复了 --safe 和 --aggressive 标志，使其不忽略参数
• --length-hint 应返回 int（由Nikita Sobolev贡献）
• 修复了导入添加中的错误（由Shantanu贡献）

22.9.0（2022年9月5日）

• 添加了 --safe 和 --aggressive
• 添加了 --pyanalyze-report
• 不要为标记有 @abstractmethod 的方法和stub文件中的方法添加 None 返回类型
• 改进类型推断
  • "string" % ... 总是 str
  • b"bytes" % ... 总是 bytes
  • 当左右两侧类型相同时，and 或 or 运算符返回该类型
  • is、is not、in 和 not in 总是返回 bool

21.12.0（2021年12月21日）

• PyPI上的首次发布