retype

!!! 注意：自2022年8月14日起，该项目不再受支持/维护 !!!

将.pyi存根文件中的类型注解重新应用到您的代码库中。

用法

Usage: retype [OPTIONS] [SRC]...

  Re-apply type annotations from .pyi stubs to your codebase.

Options:
  -p, --pyi-dir DIRECTORY     Where to find .pyi stubs.  [default: types]
  -t, --target-dir DIRECTORY  Where to write annotated sources.  [default:
                              typed-src]
  -i, --incremental           Allow for missing type annotations in both stubs
                              and the source.
  -q, --quiet                 Don't emit warnings, just errors.
  -a, --replace-any           Allow replacing Any annotations.
  --hg                        Post-process files to preserve implicit byte
                              literals.
  --traceback                 Show a Python traceback on error.
  --version                   Show the version and exit.
  --help                      Show this message and exit.

当您运行 retype 时，它会遍历您传递的所有文件SRC，在 types/ 目录中找到相应的.pyi文件，并使用Python 3函数和变量注解语法从.pyi重新应用类型注解到源代码。生成的合并源代码将保存到 typed-src/。

您还可以将目录作为源代码传递，在这种情况下，retype 将递归地在其中查找.py文件。

它足够智能，可以执行以下操作

• 重新应用类型导入
• 重新应用函数参数注解
• 重新应用函数返回值注解
• 重新应用方法参数和返回值注解
• 重新应用函数级别变量注解
• 重新应用模块级别名称注解
• 重新应用模块级别类型别名注解
• 重新应用类级别字段注解
• 重新应用实例级别字段注解
• 验证现有源注解与.pyi文件的一致性
• 验证源函数签名与.pyi文件的一致性
• 读取.pyi文件中的函数签名类型注释
• 读取.pyi文件中的变量类型注释
• 将现有源类型注释视为注解
• 在应用注解时从源中移除重复的类型注释
• 将源中剩余的类型注释标准化为注解；即使相应的.pyi文件缺失，也会执行此操作

待办事项列表

• 添加一个 --backward 选项，以输出类型注释而不是注解
• 处理桩中的 sys.version_info 和 sys.platform 检查

设计原则

• 给定的.pyi文件可以是不完整的（渐进式类型化，宝贝！）
• 函数和类在.pyi文件和源代码中的顺序可以不正确
• 如果源代码中缺少函数或类，则为错误
• 如果函数的签名在.pyi文件和源代码之间不兼容，则为错误
• 如果源代码中的注解与.pyi文件不兼容，则为错误

已知限制

• 注解源代码中的行号将不再与原始源代码匹配；这是因为重新应用类型需要从.pyi文件中复制类型导入和别名定义。
• 虽然将保留原始源代码的格式，但应用注解的格式可能与.pyi文件中的格式不同。
• 重新应用类型注解的源代码不能使用传统的 print 语句；这在运行时不起作用。
• __init__() 方法中的类属性注解将被直接移动到实现中的相应 __init__() 方法。它们永远不会被翻译为类级别属性注解，因此如果该方法缺失，翻译将失败。同样，类级别属性注解也永远不会应用于 __init__() 方法。
• .pyi文件中的前向引用将仅对类型别名和类型变量正确解决（通过在源中使用之前插入它们）。由于类和函数定义的顺序不正确，其他形式的前向引用在源代码中不会正常工作。修改您的.pyi文件以使用字符串。 retype 不会自动发现失败的前向引用并将它们字符串化。
• .pyi文件中存在的局部变量注解将被转移到源代码中给定函数的主体级别。换句话说，如果源代码在循环或条件语句分支中定义了一个变量，retype 将在函数的开始处创建一个无值的变量注解。使用宽泛的类型，并在相关的代码路径中使用 assert isinstance() 检查约束类型。
• 因此，现有源变量注解和嵌套在条件语句和循环中的类型注释将不会被去重（并且 mypy 将会抱怨一个名称已被定义）。
• 桩中的异步函数将与相同作用域中具有相同名称的常规函数匹配，反之亦然。这是为了能够注解使用 @asyncio.coroutine 语句编写的异步函数。

测试

只需运行

tox

OMG，这只适用于Python 3！

放松一下，您可以在Python 3.6+下完美地将 retype 作为工具运行，即使您想分析Python 2代码。这样，您将能够解析所有在Python 3上支持的新语法，同时还能同时有效地处理所有Python 2语法。

通过将代码限定在Python 3.6+，我可以专注于检查的质量和重用新版本的所有优秀功能（查看pathlib或f-strings），而不是浪费在Unicode兼容性等方面。

注意：由于bpo-23894，使用f-strings重新输入模块需要在Python 3.6.2+上运行。

许可证

MIT

变更日志

20.10.0

• 标记python3.8和python3.9兼容

19.9.0

• 添加模块入口点，现在您可以通过python -m retype调用它
• 在文件夹合并时自动排除由.gitignore排除的所有文件
• 支持ast3.num
• 修复了一个问题，导致合并在路径上不是递归的
• 使用基于setup.cfg的包装配置
• 通过pyproject.toml添加PEP-517/8声明
• 在wheel和sdist中包含许可证
• 该项目的代码库现在使用black格式化，导入通过isort排序，并使用Azure Pipelines代替Travis（也在Windows和macOs上测试）

17.12.0

• 支持--replace-any，允许替换现有的Any注释而不引发错误

• 错误修复：如果后面跟着另一个注释，不要重新应用# type: ignore作为注释。原始补丁由Shannon Zhu提供。

17.6.3

• 错误修复：不要尝试将# type: ignore重新应用于函数注释

• 错误修复：支持任意源文件编码，补丁由Michael Overmeyer提供。

• 错误修复：支持文件末尾缺少换行符，补丁由Michael Overmeyer提供。

• 错误修复：在--incremental中，根据PEP 8格式化默认值（如果类型不存在，则等于号周围没有空格）

17.6.2

• 错误修复：--incremental之前不能与多个参数一起使用

17.6.1

• 支持--incremental存根应用程序（即允许存根和源对于某些参数和/或返回值缺少注释）

17.6.0

• 支持异步函数

• 支持--traceback以获取有关内部错误的更多信息

17.4.0

• 首次发布版本

• 按日期版本化

作者

由Łukasz Langa拼凑而成。Michael Overmeyer和Bernat Gabor做出了多项改进。