typeshed，一个神奇的 Python 库！

大家好，我是涛哥，本文内容来自 涛哥聊Python ，转载请标原创。

更多Python学习内容：http://ipengtao.com

大家好，今天为大家分享一个神奇的 Python 库 - typeshed。

Github地址：https://github.com/python/typeshed

---

在 Python 开发中，类型检查器（如 mypy）和 IDE（如 PyCharm）能够显著提高代码的可读性和可维护性。然而，Python 本身是一种动态类型语言，标准库和第三方库通常没有类型注解。这就需要一个包含这些库类型信息的资源库，以便类型检查器能够正常工作。Typeshed 正是这样一个项目，它提供了 Python 标准库和常用第三方库的类型注解。这些注解能够帮助开发者在使用类型检查器时发现潜在的错误，提升代码质量。

本文将详细介绍 typeshed 库，包括其安装方法、主要特性、基本和高级功能，以及实际应用场景，帮助全面了解并掌握该库的使用。

安装

Typeshed 本身不需要单独安装。通常，它作为类型检查工具（如 mypy）的一部分被自动包含和使用。然而，可以手动克隆 typeshed 库以便查阅或修改类型注解。

使用 git 克隆 typeshed 库

git clone https://github.com/python/typeshed.git

使用 mypy 安装

如果还没有安装 mypy，可以通过 pip 安装：

pip install mypy

特性

1. 类型注解：包含 Python 标准库和常用第三方库的类型注解。
2. 社区驱动：由社区贡献和维护，持续更新和扩展。
3. 兼容性：支持多种 Python 版本和环境。
4. 集成工具：与 mypy、PyCharm 等工具无缝集成，提升类型检查和代码补全功能。
5. 开放源代码：所有类型注解都是开源的，开发者可以查阅、修改和贡献。

基本功能

查看类型注解

在 typeshed 库中，可以查看标准库和第三方库的类型注解文件。

以下是 typeshed/stdlib/2and3/builtins.pyi 文件的一部分示例：

# builtins.pyi

from typing import Any, TypeVar, Optional, Union, Tuple, List

T = TypeVar('T')

class object:
    def __init__(self) -> None: ...
    def __new__(cls: type[T], *args: Any, **kwargs: Any) -> T: ...

class int(object):
    @overload
    def __init__(self, x: Union[str, bytes, bytearray]) -> None: ...
    @overload
    def __init__(self, x: float) -> None: ...
    @overload
    def __init__(self, x: int = ...) -> None: ...
    @overload
    def __init__(self, x: Union[bytes, bytearray], base: int = ...) -> None: ...

使用 mypy 进行类型检查

在项目中添加类型注解，并使用 mypy 进行类型检查：

# example.py

def add(a: int, b: int) -> int:
    return a + b

print(add(1, 2))
print(add("1", "2"))  # 这行代码会引发类型错误

运行 mypy 进行类型检查：

mypy example.py

高级功能

添加自定义类型注解

在项目中添加自定义类型注解文件：

# 创建 stubs 目录，并在其中创建自定义注解文件
mkdir -p stubs/myproject
touch stubs/myproject/__init__.pyi

# 在 __init__.pyi 中添加类型注解
# stubs/myproject/__init__.pyi

def my_function(a: int, b: str) -> None: ...

使用自定义类型注解

在项目中使用自定义类型注解：

# example.py

from myproject import my_function

my_function(1, "hello")
my_function(1, 2)  # 这行代码会引发类型错误

运行 mypy 并指定自定义注解路径：

mypy --custom-typeshed-dir stubs example.py

贡献类型注解

Typeshed 是一个开源项目，开发者可以贡献自己的类型注解。以下是贡献类型注解的基本步骤：

1. 克隆 typeshed 仓库：

    git clone https://github.com/python/typeshed.git
    cd typeshed

2. 创建新分支：

    git checkout -b add-new-types

3. 添加类型注解文件：

在 third_party 目录下添加新的类型注解文件。例如，为一个名为 mynewlib 的第三方库添加类型注解：

    # third_party/3/mynewlib/__init__.pyi

    def new_function(x: int) -> str: ...

4. 提交并推送更改：

    git add .
    git commit -m "Add type annotations for mynewlib"
    git push origin add-new-types

5. 创建 Pull Request：

在 GitHub 上为你的更改创建一个 Pull Request，等待社区审核和合并。

实际应用场景

提高代码质量

在开发过程中，通过使用类型检查工具和 typeshed 库的类型注解，提高代码质量，减少运行时错误。

# example.py

from typing import List

def average(numbers: List[int]) -> float:
    return sum(numbers) / len(numbers)

print(average([1, 2, 3, 4]))
print(average(["1", "2", "3", "4"]))  # 这行代码会引发类型错误

运行 mypy 进行类型检查：

mypy example.py

改进 IDE 支持

通过 typeshed 提供的类型注解，改进 IDE（如 PyCharm、VS Code）的代码补全和类型检查功能，提升开发体验。

# example.py

import json

data = '{"name": "John", "age": 30}'
parsed = json.loads(data)

# IDE 会根据 typeshed 提供的类型注解，提供代码补全和类型检查
print(parsed["name"])

维护大型项目

在大型项目中，通过引入类型注解和使用 typeshed 提供的类型信息，提升代码可维护性和可读性。

# example.py

from typing import Dict

def process_data(data: Dict[str, int]) -> None:
    for key, value in data.items():
        print(f"{key}: {value}")

process_data({"a": 1, "b": 2})
process_data({"a": "1", "b": "2"})  # 这行代码会引发类型错误

运行 mypy 进行类型检查：

mypy example.py

总结

Typeshed 库是一个功能强大且易于使用的资源库，提供了 Python 标准库和常用第三方库的类型注解。通过支持类型注解、社区驱动、兼容性、集成工具和开放源代码，typeshed 提供了强大的功能和灵活的扩展能力。本文详细介绍了 typeshed 库的安装方法、主要特性、基本和高级功能，以及实际应用场景。希望本文能帮助大家全面掌握 typeshed 库的使用，并在实际项目中发挥其优势。无论是在提高代码质量、改进 IDE 支持还是维护大型项目中，typeshed 库都将是一个得力的工具。