利用Stub File标注Python文件

在升级到 Python 3.5+ 版本之后，最大的项目管理优化来自于 PEP-484 Type Hint 的引入。借助 Type Hint ，我们可以进一步提升 Python 代码的类型标注，保障在重构过程中避免出现一些低级失误。

我们可以通过高版本 Python 新加的新语法启用这项特性，然后通过 mypy 等 工具 检查：

def greeting(name: str) -> str:
    return 'Hello ' + name

然而，在实际实践过程中，也往往存在一些问题，这些问题来自于很多方面：

• 你难免有一些历史性代码，这些代码需要同时支持 Python2 和 Python3 。
• 你使用的 Python 3 Only 的第三方库没有 Type Hint 定义，作者看起来并不打算近期支持或者某些原因（比如你正在用的某个老版本不维护了）导致你不能贡献代码。

这些时候你往往是不能直接使用 Type Hint 带来的便利的，不过 PEP-484 中也考虑到了这种情况，包含了一种 stub file 的定义形式，可以通过第三方文件 .pyi 文件，定义函数参数类型与返回值类型。

比如官方文档中就定义了一个比较简单的 stub 例子。假设我们对一个名叫 HttpRequest 的类进行类型标记：

# request.py


class HttpRequest:
    """A basic HTTP request."""

    def __init__(self):
        self.META = {"SERVER_NAME": "hello.com"}

    def get_raw_host(self):
        """
        Return the HTTP host using the environment or request headers. Skip
        allowed hosts protection, so may return an insecure host.
        """
        # Reconstruct the host using the algorithm from PEP 333.
        host = self.META["SERVER_NAME"]
        return host

接下来，我们可以在当前文件的文件夹下新建一个名叫 bytes.pyi 的文件，填写如下内容：

# request.py


class HttpRequest:
    def get_raw_host(self) -> str: ...

让我们先构建一个存在类型混淆的例子，如果你使用了 mypy 之类的工具进行检查，则可以快速发现下面例子中本来为 int 型的 i 被重新赋值了 str 类型。

通过这样的方法，可以快速将已有的代码库快速添加类型。不过实际中并不是这么简单。我们之前也说过，很多项目并不是由我们自行维护的，这个时候，我们很难去修改上游仓库时，应该如何做呢？

这里，我们以 mypy 工具和 Django 这个 Python 常用为例去演示一下如何配置 Django 项目的类型检查。

这里有一个第三方提供的 Django 类型标注库 django-stubs ，我们可以通过 pip 命令进行安装：

pip install django-stubs

在安装完成之后，因为这个标注文件时单独发布的包，因此我们需要修改 mypy 的指向，让 mypy 使用这个包的标注。需要修改 mypy.ini 文件用于定义。关于这个文件的具体配置，则可以参考 mypy 工具的 官方文档 。

[mypy]
plugins =
     mypy_django_plugin.main

接下来就可以使用 mypy 针对 Django 部分进行检查了。