摘要

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的信息。
  • 澄清基本原理。

参考资料

版权

本文档已置于公共领域。