Python 代码智能感知类型标注与特殊注释详解

一、代码智能感知

二、类型标注

函数返回值的类型标注

变量的类型标注

三、特殊的注释

四、特殊的类型

一个不会写好的类型标注和注释的Python程序员，是让使用TA的代码的人都痛苦无比的事情……

—— 某某大佬

一、代码智能感知

想必大部分现代的集成开发环境（IDE）都有代码智能感知功能吧！

智能感知（IntelliSense），就是在我们写代码的时候，代码编辑器自动弹出我们代码中需要补全的部分，而这些补全的部分就是代码编辑器通过智能感知得到的，最重要的是，代码编辑器智能地感知补全的部分是通过代码中的变量的类型来得到的。

一般的智能感知

说了这么多之后，大家一定都清楚智能感知是什么了，但有些时候，代码却没有智能感知（如下）

智能感知失效

当代码量很大的时候，代码的智能感知是十分重要的，它可以帮你迅速了解到这个变量那个变量是个什么东西，以减少你生产BUG！

写一个好的注释（或者类型标注），不仅仅是方便未来复用你代码的人，也是为了自己，实际上，“为了自己”可不只是简单的方便自己了解代码，更多的是让IDE智能地感知到你的代码，IDE理解了你的代码，它就会为你提供对应的信息（如代码补全和提示作用），这对程序员是极其友好的！

通过了解后面的类型标注和特殊的注释，你将解决几乎所有的智能感知失效的问题！

二、类型标注

Python的类型标注有几种，在下面我给出我所知道的一些

函数参数的类型标注【简单操作】

def function(num: int, string: str):
    pass

在上面的代码中，函数参数的后面跟了一个冒号和一个类名，代表参数的数据类型，这个类名可以是内置的类，如str、int、float等，也可以是自己定义的类、也可以是模块、库中的类，如tkinter.Tk

num参数是int类型的，string参数是str类型的，这些类型标注不仅仅在函数被定义的地方可以被看见，在调用该函数的时候也能通过IDE的智能感知而被看见（如下）

函数参数的类型标注

这个类型标注之后，并不会强制该参数使用该类型，它只是起提示作用，相当于注释，同时，IDE会通过智能感知该类型标注，给出相应的代码提示

代码提示作用

【高级操作】

import typing
def function(num: int,
             lis: list[int],
             key: typing.Literal[4, 5, 6],
             string: str | None = '123'):
    pass

上面的代码中：

list[int] 的意思是，lis参数的数据类型为一个内含整数数据的列表类型

typing是一个官方的内置模块，专门用于类型标注，typing.Literal[4, 5, 6] 表示参数key的预期值只能为4或者5或者6，也就是说，该函数接收的key参数，它只希望它是4、5或者6这三个值中的一个

str | None 的意思是，string参数的数据类型可以为str或者是None类型，此处说明一下，类型标注中用 “|” 代表或者的这种操作是在 Python3.10 的时候才加入的，在之前的版本中，这种用法只在 pyi 文件（Python存根文件）中可以用

下面的代码提示中，我们就能看到类似于上面的类型标注的作用

高级操作

顺便一提，那个省略号（三个连续的小数点）的意思的默认值（一般用于pyi存根文件中）

函数返回值的类型标注

def pow(m: int, n: int) -> int:
    return m**n

函数返回值的类型标注类似于上面所说的参数类型标注，只不过这里标注的类型只的是函数的返回值的数据类型，同样的，只起提示作用，没有强制效果

这个标注也有高级用法，与上面的完全，一样，此处不再赘述

顺便一提，list[int, int, int] 表示一个含有三个整数数据的列表类型

变量的类型标注

传言有一种从天而降的写法，不知大家见过没有

key: int
key = 3
"""
或者这样写：
key: int = 3
"""
print(key) # 输出3

这个变量名后面加一个冒号、再加一个类名的写法也是类型标注的一种，只不过它不是函数的参数，而是一般变量而已，用法同上

那么，这个类型标注有什么用呢？直接赋值给该变量一个列表，那么IDE不也能识别它么？

这对于一般的变量确实没啥用，但是，下面的这种操作，你可看好了

变量的类型标注

上面的这种情况，当变量没有提前做好类型标注时，后面写代码就因为没有IDE的提示而极其麻烦

变量的类型标注还有一种方法，将在后面的 特殊的注释 中讲到

三、特殊的注释

一段看似普通的注释，实际也有着特殊的作用，就像C#中的特殊注释一样（三条斜杠“///”），Python也有着它特殊的注释

【三引号注释】

想必一个合格的Python程序员，都知道三引号注释的特殊作用吧

它不仅仅是一段普通的注释，它可以换行（都知道的），它写在函数和类下面表示帮助文档等等……这里就不再赘述了

【特殊的 # 注释】

它只能单行注释……除此之外难道它还有别的特性？？？对！别的特性！

当 # 注释以这样一种格式写的时候，它有着和类型标注同样的效果！！！

key = [] # type: list[float]

# 注释后面写上 type，再加一个冒号、然后加上数据类型，它就成了类型标注！！！

特殊的 # 注释

是不是大多数人都不知道这个特性呢？

四、特殊的类型

有一些比较特别的数据类型，有些不是内置的但又算是内置的，但你又不容易找到它，比如迭代器类型、生成器类型、函数类型（Python里函数实际也是个对象，也有类型）等等，下面给出一个表格方便大家进行类型的标注

类型名称	数据类型	引用方式
函数	function	function types.FunctionType
方法	method	types.MethodType
迭代器	Iterator	typing.Iterator collections.abc.Iterator
生成器	Generator	typing.Generator collections.abc.Generator
序列	Sequence	typing.Sequence collections.abc.Sequence