摘要

PEP 484 将类型提示引入 Python，其目标是使类型提示逐渐且易于采用。目前，类型信息必须手动分发。此 PEP 提供了一种标准化的方法，可以利用现有的工具来打包和分发类型信息，并最少的工作量，以及类型检查器解析模块并收集这些信息以进行类型检查的顺序。

基本原理

目前，包作者希望分发包含内联类型信息的代码。此外，维护者希望分发存根文件以保持 Python 2 兼容性，同时使用更新的注释语法。但是，没有标准方法来分发包含类型信息的包。此外，如果希望私下分发存根文件，则唯一可用的方法是通过设置 MYPYPATH 或等效项来手动指向存根。如果该包可以公开发布，则可以将其添加到 typeshed [1]。但是，这无法扩展，并且会给 typeshed 的维护者带来负担。此外，它将存根中的错误修复与使用 typeshed 的工具的版本绑定。

PEP 484 有一个关于分发类型信息的简短章节。在此 章节 中，PEP 建议使用 shared/typehints/pythonX.Y/ 来分发存根文件。但是，为每个第三方库手动添加存根文件的路径无法扩展。人们采用的最简单的方法是将其 site-packages 添加到他们的 MYPYPATH 中，但这会导致类型检查器在高度动态的包（例如 sqlalchemy 和 Django）上失败。

术语定义

“MAY”、“MUST”和“SHOULD”以及“SHOULD NOT”的定义应按 RFC 2119 中所述进行解释。

“内联” - 类型是使用 PEP 526 和 PEP 3107 语法（文件名以 .py 结尾）作为运行时代码的一部分。

“存根” - 仅包含类型信息的文件，不包含运行时代码（文件名以 .pyi 结尾）。

“分发” 是用于发布和分发版本的打包文件。（PEP 426）

“模块” 包含 Python 运行时代码或存根类型信息的文件。

“包” 是命名 Python 模块的目录或目录。（请注意包和分发之间的区别。虽然大多数分发都以它们安装的一个包命名，但有些分发会安装多个包。）

规范

在包中支持类型提示有几种动机和方法。此 PEP 识别用户希望创建的三种类型的包

1. 包维护者希望内联添加类型信息。
2. 包维护者希望通过存根添加类型信息。
3. 第三方或包维护者希望共享包的存根文件，但维护者不想将其包含在包的源代码中。

此 PEP 的目标是支持所有三种场景，并使它们易于添加到打包和部署中。

此规范的两个主要部分是打包规范和解析模块类型信息的解析顺序。类型检查规范旨在替换 shared/typehints/pythonX.Y/ PEP 484 的规范。

新的第三方存根库 SHOULD 通过此 PEP 中提出的第三方打包方法分发存根，而不是添加到 typeshed 中。Typeshed 将继续使用，但如果找到维护者，typeshed 中的第三方存根 MAY 被拆分为它们自己的包。

setup(
    ...,
    package_data = {
        'foopkg': ['py.typed'],
    },
    ...,
    )

shapes-stubs
└── polygons
    └── pentagon
        └── __init__.pyi

shapes-stubs
└── polygons
    └── hexagon
        └── __init__.pyi

实现

指示对类型支持的提议方案完全向后兼容，并且不需要修改包工具。包含内联类型的示例包可在 [typed_package] 中找到，以及 [stub_package]。一个示例包检查器 [pkg_checker]，它读取已安装包的元数据并报告其状态，例如未类型化、内联类型化或存根包。

mypy 类型检查器实现了 PEP 561 搜索，您可以在 mypy 文档 [4] 中了解相关信息。

[numpy-stubs] 是 numpy 分发版的一个真实仅存根包的示例。

致谢

如果没有 Ivan Levkivskyi、Jelle Zijlstra、Alyssa Coghlan、Daniel F Moisset、Andrey Vlasovskikh、Nathaniel Smith 和 Guido van Rossum 的想法、反馈和支持，这个 PEP 将是不可能的。

版本历史

• 2023-01-13

  • 阐明 模块解析顺序 的第 4 步适用于任何带有 py.typed 标记文件的包（而不仅仅是内联包）。

• 2021-09-20

  • 阐明仅存根命名空间包的期望和类型检查器行为。
  • 阐明命名空间包中单个文件模块的处理方式。

• 2018-07-09

  • 添加指向仅存根包示例的链接。

• 2018-06-19

  • 部分存根包可以查看 typeshed 以及运行时包。

• 2018-05-15

  • 添加部分存根包规范。

• 2018-04-09

  • 添加对 mypy 实现的引用。
  • 阐明存根包的优先级。

• 2018-02-02

  • 将仅存根包的后缀更改为 -stubs，而不是 _stubs。
  • 注意，仅存根包不需要 py.typed。
  • 添加关于 pip 和升级存根包的说明。

• 2017-11-12

  • 重写为仅使用现有工具。
  • 无需在元数据中指示类型信息的种类。
  • 标记文件名称从 .typeinfo 更改为 py.typed。

• 2017-11-10

  • 规范重写为使用包元数据而不是分发元数据。
  • 删除了仅存根包，并将其合并到第三方包规范中。
  • 删除了类型检查器考虑检查运行时版本的建议。
  • 更新了实现以反映 PEP 更改。

• 2017-10-26

  • 添加了实现参考。
  • 添加了致谢和版本历史记录。

• 2017-10-06

  • 重写为使用 .distinfo/METADATA 而不是特定于 distutils 的命令。
  • 阐明第三方存根包的版本控制。

• 2017-09-11

  • 添加了有关当前解决方案和 typeshed 的信息。
  • 阐明基本原理。

参考文献

版权

本文档已进入公有领域。