Python3.5 版本引入了型別提示（Type Hints），它允許開發者在程式碼中顯式地宣告變數、函式、方法等的型別資訊。這種型別宣告不會影響 Python 直譯器的執行，但可以讓 IDE 和靜態分析工具更好地理解程式碼，同時提高程式碼的可讀性和可維護性。然而，由於 Python 支援動態型別，型別提示並不能完全確保程式碼的正確性。本文僅介紹 Python 型別提示的初步使用。如果需要更詳細的使用說明，請參考以下文章：typing、Python 型別提示簡介和Type Hints 入門教程。
型別提示的語法格式為：
- 對於變數：{變數名}:{型別名} =
- 對於函式引數：{引數名}:{型別名} =
- 對於函式返回值：->
1 型別提升
型別提示的引入主要有以下幾個方面的用途：
1 提高程式碼可讀性
型別提示可以幫助其他開發人員更好地理解程式碼，特別是在處理大型程式碼庫時。透過清晰地指定變數、函式引數和返回值的資料型別，開發人員可以更快地理解程式碼的含義和用途，從而更容易維護和修改程式碼。
如下所示。我們有一個名為 add 的函式，用於將兩個數字相加並返回結果。以下是該函式的原始程式碼：
def add(a, b):
return a + b
我們發現，該函式沒有任何型別提示，因此在呼叫該函式時，我們必須自己去了解和檢查每個引數的型別。這樣會導致程式碼的可讀性和可維護性變差，特別是在程式碼規模較大、涉及多個檔案的情況下。為了改善這種情況，我們可以使用型別提示來明確指定每個引數的型別。以下是新增型別提示後的 add 函式的程式碼：
def add(a: int, b: int) -> int:
return a + b
現在，我們可以清楚地看到函式 add 的引數和返回值都是整數型別。這使得程式碼更易於理解，也提高了程式碼的可靠性。
2 檢測型別錯誤
Python 是一種動態語言，因此變數和函式引數的型別可以在執行時進行更改。但是，這也意味著開發人員容易在程式碼中引入型別錯誤。透過使用型別提示，開發人員可以在編譯時檢測到這些型別錯誤，並更早地發現和修復它們，從而減少程式碼錯誤和除錯時間。
mypy是一個用於檢查Python型別的靜態型別檢查器。它可以檢測型別註釋中的錯誤以及其他型別的錯誤。mypy使用說明可以參考：mypy簡易教程。mypy需要首先輸入以下命令安裝：
pip install mypy
然後，在程式碼中標註變數、函式引數和返回值的型別。執行以下命令：
mypy your_script.py
在上面的示例中，your_script.py是要檢查的Python指令碼。執行mypy工具後，它將檢查Python指令碼中的型別錯誤，並輸出錯誤資訊。
3 提供自動補全和文件
許多整合開發環境（IDE）和編輯器都可以使用型別提示來提供自動補全和程式碼文件。這可以幫助開發人員更快地編寫程式碼，並提供關於函式引數和返回值的資訊，以便更好地理解程式碼。要使用Python型別提示提供自動補全和文件，需要使用一個支援該功能的Python編輯器。比如一些流行的Python編輯器包括vscode、PyCharm和Sublime Text等。
以vscode為例，考慮一個整數相加函式，將結果儲存在變數c中。如果加上型別提示，vscode外掛將推斷變數c的型別為 int，並提供程式碼補全和程式碼提示等功能。
此外，還可以使用vscode的autoDocstring生成帶有型別提示的文件和註釋。
autoDocstring註釋程式碼使用方法如下所示：
按照以上方法，對於有無型別提示的註釋結果如下：
def add(a, b):
"""_summary_
Args:
a (_type_): _description_
b (_type_): _description_
Returns:
_type_: _description_
"""
c = a + b
return c
def add(a: int, b: int) -> int:
"""_summary_
Args:
a (int): _description_
b (int): _description_
Returns:
int: _description_
"""
c = a + b
return c
2 型別宣告
2.1 基本型別
對於Python的內建基本型別 int、float、str 和 byte等，可以直接使用型別本身進行型別提示。如下所示：
# 直接定義
age: int = 1
# 宣告後定義
num: float
num = 2.0
def greet(name: str) -> str:
return f"Hello, {name}!"
def is_even(x: int) -> bool:
return x % 2 == 0
def encode_data(data: str) -> bytes:
return data.encode('utf-8')
2.2 巢狀型別
對於容器資料結構，例如 list、tuple、dict 等，也可以直接使用型別本身進行型別提示。如下所示：
items: list = [1, 4.0, "3"]
info: dict = {"name":"john", "age":24}
在Python的容器資料結構中，每個元素都具有其自己的型別。雖然這種方法提供了靈活性，但是內部元素的型別無法受到限制，因此內部元素可以是任何型別（Any）。可以透過Python的typing標準庫來宣告這些型別及其元素型別。
from typing import List, Tuple, Dict, Set
# 指定my_list變數是一個整數列表
my_list: List[int] = [1, 2, 3, 4]
# 指定my_tuple變數應該是一個按順序包含整數、字串和布林值的元組
my_tuple: Tuple[int, str, bool] = (1, "hello", True)
# 指定了my_dict變數是一個所有鍵為str型別，所有值為int型別的字典
my_dict: Dict[str, int] = {"apple": 1, "banana": 2, "orange": 3}
# 指定了my_set變數應該是一個浮點數集合
my_set: Set[float] = {1.0, 2.0, 3.0}
2.3 自定義型別
Python也支援對自定義類進行型別提示。下面是一個自定義類的型別提示示例：
class Person:
def __init__(self, name: str, age: int):
self.name = name
self.age = age
def say_hello(person: Person) -> str:
return f"Hello, {person.name}!"
在上面的程式碼中，我們定義了一個 Person 類，它有兩個屬性：name 和 age。在初始函式中，我們使用型別提示指定了這兩個屬性的型別。接下來，我們定義了一個 say_hello 函式，這個函式的引數是一個 Person 型別的物件，並且返回值是一個字串。
對於numpy和pandas這種第三方庫，也可以透過同樣的方法進行型別提示：
import numpy as np
import pandas as pd
import cv2
# numpy
def add_arrays(a: np.ndarray, b: np.ndarray) -> np.ndarray:
return np.add(a, b)
# pandas
def filter_dataframe(df: pd.DataFrame, column: str, value: float) -> pd.DataFrame:
return df[df[column] > value]
# opencv，opencv影像本身就是一個numpy陣列結構
def resize_image(img: np.ndarray, height: int, width: int) -> np.ndarray:
return cv2.resize(img, (width, height))
2.4 複合型別
2.4.1 Union和Optional
Python的typing庫也提供了Union型別用於表示多種型別中的一種，Optional型別用於表示可選型別。它們可以結合使用，以便更好地表示變數的型別。
例如，如果一個變數可以是整數或字串型別，那麼可以這樣定義它的型別：
from typing import Union
def func(x: Union[int, str]) -> None:
pass
上面的程式碼中，x的型別為Union[int, str]，表示x可以是整數或字串型別。
如果一個變數可以是整數型別或None型別，那麼可以這樣定義它的型別：
from typing import Optional
def func(x: Optional[int] = None) -> None:
pass
Union和Optional型別可以結合使用。例如，如果一個變數可以是整數型別、字串型別或None型別，那麼可以這樣定義它的型別：
from typing import Optional, Union
def func(x: Optional[Union[int, str]]) -> None:
pass
上面的程式碼中，x的型別為Optional[Union[int, str]]，表示x可以是整數型別、字串型別或None型別。
此外，在Python中，Union[X, Y] 表示變數的型別可以是 X 或 Y。因此，Optional[X] 實際上是 Union[X, None] 的簡寫形式。這種語法的好處是它可以使程式碼更簡潔，因為我們只需要寫一個型別而不是兩個。
from typing import Optional, Union
def greet(name: Optional[str]) -> str:
if name is None:
return "Hello, stranger!"
else:
return f"Hello, {name}!"
def greet2(name: Union[str, None]) -> str:
if name is None:
return "Hello, stranger!"
else:
return f"Hello, {name}!"
在上面程式碼中，greet和greets函式是等價的。在第一個函式中，我們使用了 Optional[str] 來表示 name 可以是一個字串或者是 None。在第二個函式中，我們使用了 Union[str, None] 來達到相同的效果。
2.4.2 Generator和Iterator
在Python中，Generator和Iterator是非常常見的資料型別。Generator是一種函式，可以透過yield語句生成一個迭代器，而Iterator是一種物件，可以用於迭代元素序列。為了提高程式碼的可讀性和可維護性，我們可以使用型別提示來指定Generator和Iterator的型別。
Generator型別提示使用Generator[ReturnType, SendType, ReturnType]語法，其中ReturnType指定返回值型別，SendType指定傳送值型別，ReturnType指定生成器的型別。例如，下面是一個簡單的Generator型別提示示例：
from typing import Generator
def even_numbers(n: int) -> Generator[int, None, None]:
for i in range(n):
if i % 2 == 0:
yield i
上面的程式碼中，even_numbers是一個Generator函式，返回型別是Generator[int, None, None]，該函式生成一個整數序列，其中每個偶數都是透過yield語句生成的。
Iterator型別提示使用Iterator[ElementType]語法，其中ElementType指定迭代器元素型別。例如，下面是一個簡單的Iterator型別提示示例：
from typing import Iterator
class MyIterator:
def __init__(self):
self.current: int = 0
self.max: int = 5
def __iter__(self) -> Iterator[int]:
return self
def __next__(self) -> int:
if self.current >= self.max:
raise StopIteration
else:
self.current += 1
return self.current
在上面的程式碼中，我們對MyIterator類進行了註釋。使用了typing模組中的Iterator類來註釋__iter__()方法的返回值型別。同時，我們對current和max屬性也進行了註釋，指定了它們的型別為int。在__next__()方法中，我們指定了返回值型別為int。
2.4.3 Callable
Callable型別提示用於表示一個可呼叫物件，例如函式、類或物件等。從形式上來看，Callable型別提示接受兩個或三個型別提示引數：第一個參數列示函式的引數型別，第二個參數列示函式的返回型別。下面是一個Callable型別提示的例子：
from typing import Callable
def apply(func: Callable[[int, int], int], a: int, b: int) -> int:
return func(a, b)
def add(a: int, b: int) -> int:
return a + b
result = apply(add, 3, 4)
print(result) # 輸出7
在上面的例子中，apply函式接受一個名為func的引數，該引數是一個Callable型別，它指定了函式的兩個整數引數和一個整數返回值。add函式滿足這個條件，因此可以傳遞給apply函式，它會返回add(3, 4)的結果7。
2.4.4 Any和NoReturn
Any型別表示一個任意型別，它可以用於函式引數、函式返回值和變數等。使用Any型別時，我們可以省略型別註釋，使變數型別更加靈活。下面是一個使用Any型別的例子：
from typing import Any
def print_value(value: Any) -> None:
print(value)
print_value("Hello World") # 輸出 "Hello World"
print_value(123) # 輸出 123
在上面的例子中，我們定義了一個print_value函式，它接受一個任意型別的引數value，並將其列印出來。我們可以看到，我們可以將任何型別的值傳遞給print_value函式，包括字串和整數。這使得我們的程式碼更加靈活。
NoReturn型別表示函式不會返回任何值。這個型別通常用於標識那些沒有返回值的函式。下面是一個使用NoReturn型別的例子：
from typing import NoReturn
def print_message(message: str) -> NoReturn:
print(message)
raise Exception("Error occurred")
print_message("Hello World") # 輸出 "Hello World"，然後丟擲異常
在上面的例子中，我們定義了一個print_message函式，它接受一個字串型別的引數message，並將其列印出來。然後，我們手動丟擲了一個異常，這意味著函式不會返回任何值。我們可以使用NoReturn型別來明確地表示這一點。
2.4.5 其他
Python還支援更高階的型別提示。例如，可以使用Sequence來指定一個列表，使用TypedDict來指定一個帶有特定鍵和值型別的字典。此外，Python還支援Literal型別提示，可以限制變數只能取特定的常量值。最近，Python3.8版本還增加了Protocol型別提示，允許指定類需要實現哪些方法和屬性。這些型別提示用的不多，但是如果需要更精細的型別控制，可以參考官方文件：typing。
2.5 型別提示的別名
在型別提示中使用了過於複雜的型別，可以考慮將其定義為一個型別別名，然後在函式引數、返回值等處使用該型別別名。例如，如果你需要傳遞一個包含多個欄位的字典作為函式引數，你可以使用Dict[str, Union[int, str, List[int]]]來表示該字典的型別。但是，這個型別過於複雜，不易於理解。你可以將其定義為一個型別別名，如下所示：
from typing import Dict, Union, List
MyDict = Dict[str, Union[int, str, List[int]]]
def my_function(my_dict: MyDict) -> int:
# Function body
return 1
這樣，你就可以在函式引數、返回值等處使用MyDict這個型別別名，使程式碼更加易讀、易懂。