Python函数 — 函数标注和存根文件

1、函数标注

函数标注也叫函数注解，元数据（元数据是用来描述数据的数据）。

在Python中自定义函数的时候，参数不需要指明类型，我们可以为函数的参数添加一些额外的信息来指明变量类型，以方便其他人使用，这些额外信息就是函数标注。

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

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

添加标注：

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

给函数添加标注示例如下：

def fun(ham: str, eggs: str = 'egg') -> str:
    """
    函数标注；
    
    ham，位置参数，类型str
    eggs，关键字参数，类型str，默认值 'egg'
    函数返回值类型str
    """
    return ham + ' and ' + eggs

# 打印函数的元数据信息
print(fun.__annotations__)
---------------------------------------------------------------------------------
{'ham': , 'eggs': , 'return': }

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

print(fun('tom'))
print(type(fun('tom')))
---------------------------------------------------------------------------
tom and egg

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

 执行函数报错信息：TypeError: unsupported operand type(s) for +: 'int' and 'str'

2、存根文件

前面我们知道了可以给自定义函数添加标注来限制参数类型，实际项目中并不会使用这种方法，更多的是使用stub存根文件（.pyi文件）。stub存根文件可以简单的理解为一个函数参数类型的静态类型检查器，在编写代码的时候就给出提示。由于Python本身是动态语言，不像静态语言可以在编译的时候进行类型检查，所以通过存根文件、注解这些东西可以辅助用户在编写代码时给出建议的类型提示，不仅可以用IDE更快速地进行开发，还能减少运行时的类型报错。

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

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

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

（2）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 就是存根文件的官方文档，提供这些标准定义和工具，以及一些用于注释不可用情况的约定，帮助用户进行类型检查。 

PEP484 官方文档译文

什么是PEP？

---

reference：

函数标注 — Python 3.8.16 文档

Python进阶 — PEP_笃行之.kiss的博客-CSDN博客