Python 程式碼智慧感知 —— 類型標註與特殊的注釋（獻給所有的Python人）

• 2022 年 9 月 19 日
• 筆記
• Python

【原文地址：//xiaokang2022.blog.csdn.net/article/details/126936985】

​

一個不會寫好的類型標註和注釋的Python程式設計師，是讓使用TA的程式碼的人都痛苦無比的事情……

—— 某某大佬

一、程式碼智慧感知

        想必大部分現代的集成開發環境（IDE）都有程式碼智慧感知功能吧！

        智慧感知（IntelliSense），就是在我們寫程式碼的時候，程式碼編輯器自動彈出我們程式碼中需要補全的部分，而這些補全的部分就是程式碼編輯器通過智慧感知得到的，最重要的是，程式碼編輯器智慧地感知補全的部分是通過程式碼中的變數的類型來得到的。

​

說了這麼多之後，大家一定都清楚智慧感知是什麼了，但有些時候，程式碼卻沒有智慧感知（如下）

當程式碼量很大的時候，程式碼的智慧感知是十分重要的，它可以幫你迅速了解到這個變數那個變數是個什麼東西，以減少你生產BUG！

        寫一個好的注釋（或者類型標註），不僅僅是方便未來複用你程式碼的人，也是為了自己，實際上，「為了自己」可不只是簡單的方便自己了解程式碼，更多的是讓IDE智慧地感知到你的程式碼，IDE理解了你的程式碼，它就會為你提供對應的資訊（如程式碼補全和提示作用），這對程式設計師是極其友好的！

通過了解後面的類型標註和特殊的注釋，你將解決幾乎所有的智慧感知失效的問題！ 

二、類型標註

Python的類型標註有幾種，在下面我給出我所知道的一些

函數參數的類型標註 

【簡單操作】

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

在上面的程式碼中，函數參數的後面跟了一個冒號和一個類名，代表參數的數據類型，這個類名可以是內置的類，如str、int、float等，也可以是自己定義的類、也可以是模組、庫中的類，如tkinter.Tk

num參數是int類型的，string參數是str類型的，這些類型標註不僅僅在函數被定義的地方可以被看見，在調用該函數的時候也能通過IDE的智慧感知而被看見（如下）

​

這個類型標註之後，並不會強制該參數使用該類型，它只是起提示作用，相當於注釋，同時，IDE會通過智慧感知該類型標註，給出相應的程式碼提示

​

【高級操作】

1 import typing
2 
3 def function(num: int,
4              lis: list[int],
5              key: typing.Literal[4, 5, 6],
6              string: str | None = '123'):
7     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存根文件中）

函數返回值的類型標註

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

函數返回值的類型標註類似於上面所說的參數類型標註，只不過這裡標註的類型只的是函數的返回值的數據類型，同樣的，只起提示作用，沒有強制效果

這個標註也有高級用法，與上面的完全，一樣，此處不再贅述

順便一提，list[int, int, int] 表示一個含有三個整數數據的列表類型

變數的類型標註

傳言有一種從天而降的寫法，不知大家見過沒有

1 key: int
2 key = 3
3 
4 """
5 或者這樣寫：
6 key: int = 3
7 """
8 
9 print(key) # 輸出3

這個變數名後面加一個冒號、再加一個類名的寫法也是類型標註的一種，只不過它不是函數的參數，而是一般變數而已，用法同上

那麼，這個類型標註有什麼用呢？直接賦值給該變數一個列表，那麼IDE不也能識別它么？

這對於一般的變數確實沒啥用，但是，下面的這種操作，你可看好了

​

上面的這種情況，當變數沒有提前做好類型標註時，後面寫程式碼就因為沒有IDE的提示而極其麻煩

變數的類型標註還有一種方法，將在後面的 特殊的注釋 中講到

三、特殊的注釋

一段看似普通的注釋，實際也有著特殊的作用，就像C#中的特殊注釋一樣（三條斜杠「///」），Python也有著它特殊的注釋

【三引號注釋】

想必一個合格的Python程式設計師，都知道三引號注釋的特殊作用吧

它不僅僅是一段普通的注釋，它可以換行（都知道的），它寫在函數和類下面表示幫助文檔等等……這裡就不再贅述了

【特殊的 # 注釋】

它只能單行注釋……除此之外難道它還有別的特性？？？對！別的特性！

當 # 注釋以這樣一種格式寫的時候，它有著和類型標註同樣的效果！！！

1 key = [] # type: list[float]

# 注釋後面寫上 type，再加一個冒號、然後加上數據類型，它就成了類型標註！！！

​

是不是大多數人都不知道這個特性呢？

四、特殊的類型

有一些比較特別的數據類型，有些不是內置的但又算是內置的，但你又不容易找到它，比如迭代器類型、生成器類型、函數類型（Python里函數實際也是個對象，也有類型）等等，下面給出一個表格方便大家進行類型的標註

【看了這麼多，是不是感覺又漲知識了呢？那麼，你的贊呢？】