Python/mypy项目：使用已安装包的类型检查指南

Python/mypy项目：使用已安装包的类型检查指南

mypy Optional static typing for Python 项目地址: https://gitcode.com/gh_mirrors/my/mypy

概述

在Python类型检查领域，mypy作为静态类型检查工具，能够利用已安装包的类型信息来提升代码质量。本文将详细介绍如何在mypy中使用支持类型检查的第三方包，以及如何创建符合PEP 561标准的类型化包。

类型检查支持的两种形式

现代Python生态系统中，包可以通过两种主要方式提供类型信息：

1. 内联类型注解：直接在Python代码中使用类型注解
2. 存根文件(Stub Files)：单独的.pyi文件包含类型信息

例如，aiohttp这样的流行库已经内置了类型支持，而requests等库则通过types-requests这样的存根包提供类型信息。

使用已安装包的类型信息

基本使用方法

当你在运行mypy的环境中安装了支持类型检查的包时，mypy会自动发现并使用这些类型信息。这包括：

• 带有内联类型注解的包
• 专门提供类型信息的存根包（通常命名为types-<库名>）

pip install package_with_types  # 安装带有类型注解的包
pip install types-package      # 安装存根包

多环境处理

如果你在多个Python环境中工作，mypy默认只会检查运行mypy的环境中的包。有两种解决方案：

1. 在运行mypy的环境中安装相同的包
2. 使用--python-executable标志指定另一个Python环境

mypy --python-executable=/path/to/other/python my_script.py

特殊情况处理

• 禁用站点包检查：使用--no-site-packages标志
• 存根包限制：存根包必须安装才能被识别，不能通过MYPYPATH环境变量直接引用

创建支持类型检查的包

基本要求

根据PEP 561，包可以通过三种方式提供类型信息：

1. 源代码中包含类型注解
2. 附带存根文件
3. 作为单独的存根包发布

内联类型注解的实现

对于包含类型注解的包，需要在包目录中添加py.typed空文件：

package_a/
    __init__.py
    lib.py
    py.typed

在setup.py中需要声明包含此文件：

setup(
    ...,
    package_data={"package_a": ["py.typed"]},
    packages=["package_a"]
)

混合存根文件的实现

当同时提供实现文件和存根文件时：

package_b/
    __init__.py
    lib.py      # 实现文件
    lib.pyi     # 存根文件
    py.typed

setup.py需要包含两者：

setup(
    ...,
    package_data={"package_b": ["py.typed", "lib.pyi"]},
    packages=["package_b"]
)

纯存根包的实现

为现有库创建存根包时，包名应遵循<原包名>-stubs的格式：

package_c-stubs/
    __init__.pyi
    lib.pyi

对应的setup.py：

setup(
    ...,
    package_data={"package_c-stubs": ["__init__.pyi", "lib.pyi"]},
    packages=["package_c-stubs"]
)

发布注意事项

为确保类型文件被包含在发布包中，可能需要修改MANIFEST.in：

global-include *.pyi
global-include *.typed

版本兼容性建议

使用存根包时需注意版本兼容性：

• 新版存根包可能使用旧版mypy不支持的类型特性
• 如果固定了mypy版本，建议也固定存根包版本
• 从mypy 0.900开始，大多数第三方存根包需要显式安装

总结

通过合理利用Python生态中的类型信息，开发者可以显著提升代码质量和开发效率。无论是使用现有类型化包还是为自己的项目添加类型支持，理解mypy如何与这些包交互都是现代Python开发的重要技能。

mypy Optional static typing for Python 项目地址: https://gitcode.com/gh_mirrors/my/mypy