Python函数 — 类型提示和存根文件

1、类型提示

类型提示（Type Hints）也叫函数标注，函数注解，元数据（元数据是用来描述数据的数据）。详见 PEP 3107 和 PEP 484

Python中，自定义函数的时候，可以为函数添加一些额外的信息来限制参数类型和返回值类型，方便他人读懂你的代码，这些额外信息就是函数标注。

元数据以字典的形式存放在函数的 __annotations__ 属性中。

Python解释器不会对这些标注添加任何语义，也不会使用标注对传入的变量进行类型检查，标注并且不会影响函数的功能，和没有添加标注的函数完全没有区别。

添加标注：

形参标注的定义方式是在形参名后加冒号，后面跟一个表达式，该表达式会被求值为标注的值。
返回值标注的定义方式是加组合符号 ->，后面跟一个表达式，该标注位于形参列表和表示 def 语句结束的冒号之间。

（1）给函数添加标注示例如下

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

说明，这里的name: str 表示参数name的类型为str，-> str 表示函数返回值类型为str。

（2）打印函数的元数据信息

print(greeting.__annotations__)
---------------------------------------------------------------------------------
{'name': <class 'str'>, 'return': <class 'str'>}

（3）调用函数，传入的实参跟函数标注的参数类型一致

print(greeting('tom'),type(greeting('tom')))
---------------------------------------------------------------------------
Hello tom <class 'str'>

（4）调用函数，传入的实参跟函数标注的参数类型不一致

这里是由于pycharm这一类的IDE工具自带了类型静态检查器，在编写代码的时候就给出了错误提示！

2、存根文件

存根文件可以简单的理解为一个函数参数类型的静态类型检查器，在编写代码的时候就给出提示。由于Python本身是动态语言，不像静态语言可以在编译的时候进行类型检查，所以通过存根文件、注解这些东西可以辅助用户在编写代码时给出建议的类型提示，不仅可以用IDE更快速地进行开发，还能减少运行时的类型报错。

（1）Python解释器内置函数的存根文件

鼠标放到内置函数左侧的"*"，提示：Has stub item in builtins.pyi

鼠标点击*跳转到存根文件中

（2）存根文件中的@overload装饰器

函数装饰器`@overload`是Python 3.5版本引入的。它允许在一个函数中定义多个签名，这些签名对应于不同的参数类型和返回值类型。在运行时，根据函数参数类型的具体实例选择正确的签名进行调用。

下面是一个@overload装饰器的例子：

from typing import overload@overload
def create_account(username: str, password: str) -> int:pass@overload
def create_account(username: str, password: str, email: str) -> str:pass

此示例中，`create_account()`函数有两个不同的签名，对应于不同的参数类型和返回值类型。在运行时，如果调用函数带有两个参数，则第一个签名将被调用，如果带有三个参数，则第二个签名将被调用。

（3）Pycharm中给我们自定义的函数新建存根文件

Stubs | PyCharm Documentation

首先新建.py文件如下：

def my_function(name):return "Hello " + name

同目录下，新建.pyi文件，文件名要跟.py文件名一致。

存根文件内容如下：

def my_function(name: str) -> str: ...

注意，-> str: 后面的...是语法固定写法。

文件目录结构如下：

测试一下存根文件：

很容易发现Pycharm提示了：Expected type 'str', got 'int' instead，这是由于Pycharm内置了静态的类型检查器，在代码没有运行的时候就检查出来了类型错误！！这在维护大型的项目的时候是非常有用的。

3、PEP文档

PEP 484 是存根文件中类型提示的官方文档，强烈建议一读。

PEP 484是Python Enhancement Proposal中的一份提案，提出了用于类型注释的语法标准。该提案规定了Python中可用的语法和语义约定，以定义函数参数和返回类型的注释。

PEP 484提案的主要目的是增加代码的可读性和可维护性。类型注释使代码更易于理解，并且可以提供有关函数参数和返回值的有用信息，从而帮助程序员避免错误。此外，类型注释还可以使代码更易于自动化重构和重构，以及使IDE工具能够提供有关变量和函数类型的有用提示。

PEP484 官方文档译文

什么是PEP？

reference：

函数标注 — Python 3.8.16 文档

Python 类型提示