Python 中如何編寫類型提示
哈嘍大家好，我是咸魚。
我們知道 Python 是一門具有動態特性的語言，在編寫 Python 代碼的時候不需要顯式地指定變量的類型，這樣做雖然方便，但是降低了代碼的可閱讀性，在后期 review 代碼的時候容易對變量的類型產生混淆，需要查閱大量上下文，導致后期維護困難。
為了提高代碼的可讀性、可維護性，Python 在 PEP 484 中引入了類型提示（ type hinting）。類型提示是 Python 中一個可選但非常有用的功能，可以使代碼更易于閱讀和調試。
關于類型提示的介紹可以看：https://realpython.com/python-type-hints-multiple-types/#use-pythons-type-hints-for-one-piece-of-data-of-alternative-types
在編寫函數的時候，我們通常指定其返回值是一種數據類型，但是在下面這些情況下可以指定返回不同類型的數據：
- 當函數使用條件語句返回不同類型結果時
- 函數有時返回值，有時不返回值
- 當函數遇到錯誤時，可能需要返回與正常結果的返回類型不同的特定錯誤對象
- 想要設計更靈活更通用的代碼
那么這時候該如何編寫類型提示呢？
為常規函數編寫類型提示
def parse_email(email_address: str) -> str | None:
if "@" in email_address:
username, domain = email_address.split("@")
return username
return None上面的函數中有一個條件判斷語句，用于檢查參數 email_address 電子郵箱地址里面是否包含 @ 符號。如果有，則返回用戶名 username ，沒有則返回 None，表示電子郵箱地址不完整。
所以該函數的返回值要么是包含用戶名的字符串，要么是 None。那么我們可以用管道符（|） 來表示函數返回單個值的可選類型：
# 要么返回 str ，要么返回 None
str | None:在 Python 3.10 之前，我們還可以使用 typing 模塊中的 Union 來表示函數返回的是str 還是 None：
from typing import Union
def parse_email(email_address: str) -> Union[str, None]:
if "@" in email_address:
username, domain = email_address.split("@")
return username
return None那如果單個返回值里面包含多個對象的話，該如何編寫類型提示呢？
比如說上面的函數，我希望它：
- 如果是有效的郵箱，則返回用戶名和域名
- 如果不是有效的郵箱，返回 None
PS： 當返回值里有多個對象時，默認是以元組的形式返回。
所以我們可以這么寫類型提示：
def parse_email(email_address: str) -> tuple[str, str] | None:
if "@" in email_address:
username, domain = email_address.split("@")
return username, domain
return Nonetuple[str, str]| None ，表示返回值可以是兩個字符串的元組或None。
如果使用 typing 模塊中的 Union來編寫類型提示的話，如下：
from typing import Tuple, Union
def parse_email(email_address: str) -> Union[Tuple[str, str], None]:
if "@" in email_address:
username, domain = email_address.split("@")
return username, domain
return None
舉三反一，如果單個返回值包含三個對象，可以這么寫：
# 函數返回值里面包含了字符串、整數、布爾值
def get_user_info(user: User) -> tuple[str, int, bool]:
...為回調函數編寫類型提示
在 Python 中，函數可以作為另一個函數的參數或者返回其他函數。這種函數被稱為高階函數。
比如說 Python內置函數（例如sorted()、map()和filter()）可以接受一個函數作為參數。
這個作為參數傳遞的函數通常被稱為回調函數（callback function），因為它在另一個函數中被調用（"回調"），回調函數是一種可調用對象（callable objects）。
可調用對象指的是可以像函數一樣調用的對象。Python 中可調用對象包括常規函數、lambda 表達式或實現了__call__()方法的類）。
那么我們在調用回調函數的時候，該如何編寫類型注釋呢？
比如說下面的例子：
>>> from collections.abc import Callable
>>> def apply_func(
... func: Callable[[str], tuple[str, str]], value: str
... ) -> tuple[str, str]:
... return func(value)
...
>>> def parse_email(email_address: str) -> tuple[str, str]:
... if "@" in email_address:
... username, domain = email_address.split("@")
... return username, domain
... return "", ""
...
>>> apply_func(parse_email, "claudia@realpython.com")
('claudia', 'realpython.com')在函數 apply_func 的類型提示中，將回調函數 func作為第一個參數，將字符串 value 作為第二個參數，返回值是一個包含兩個 str 的 tuple，而 Callable[[str], tuple[str, str]]：表示回調函數 func 接收參數是一個 str，返回值是一個包含兩個 str 的 tuple。
在函數 parse_email 的類型提示中，接受一個 str 類型的參數 email_address ，返回值類型是一個包含兩個 str 的 tuple，那如果我希望函數 apply_func 能夠接收具有多種輸入類型的不同函數作為參數（比如說回調函數有多個輸入參數）并有多種返回類型，該怎么辦?
我們可以用省略號... 來表示可調用對象（例如回調函數）可以接受多個參數，這樣就不需要依次列出接受參數的類型：
def apply_func(
func: Callable[...,tuple[str, str]], value: str) -> tuple[str, str]：
return func(value)或者使用 typing 模塊中的類型來指定任何返回 Any 類型：
from collections.abc import Callable
from typing import Any
def apply_func(
func: Callable[...,Any], *args: Any, **kwargs: Any) -> tuple[str, str]：
return func(*args, **kwargs)我們還可以在類型提示中把回調函數的返回值類型寫成 T ，這是一個類型變量type variable,可以代表任何類型：
from collections.abc import Callable
from typing import Any, TypeVar
T = TypeVar("T")
def apply_func(func: Callable[..., T], *args: Any, **kwargs: Any) -> T:
return func(*args, **kwargs)而 apply_func 的返回值類型也是 T，*args: Any, **kwargs: Any 表示 apply_func 可以接受任意數量的參數（包括 0）。
為生成器編寫類型提示
在 Python 中，生成器（Generators）是一種特殊的迭代器，它們允許按需生成值，而無需提前生成所有值并將其存儲在內存中，生成器逐個產生并返回值，這對于處理大量數據或無限序列非常有用。
生成器可以通過函數與 yield 語句創建。yield 語句在生成器函數內部被用來產生一個值，并在暫停生成器的同時返回該值給調用者，每次調用生成器的 next()方法或使用 for循環時，生成器函數會從上一次yield語句的位置恢復執行，并繼續執行到下一個yield語句或函數結束。
繼續上面的例子，我現在有大量的郵箱需要判斷是否有效，與其將每個解析的結果存儲在內存中并讓函數一次返回所有內容，不如使用生成器一次生成一個解析結果：
>>> from collections.abc import Generator
>>> def parse_email() -> Generator[tuple[str, str], str, str]:
# 定義初始的 sent 值為元組 ("", "")
... sent = yield ("", "")
... while sent != "":
... if "@" in sent:
... username, domain = sent.split("@")
... sent = yield username, domain
... else:
... sent = yield "invalid email"
... return "Done"Generator[tuple[str, str], str, str]類型提示里面有三個參數（后面兩個是可選的），其中：
- yield 類型：第一個參數是生成器生成的結果。例子中它是一個元組，包含兩個字符串，一個表示用戶名，另一個表示域名
- send 類型：第二個參數表示使用 send 方法發送給生成器的內容。例子中是一個字符串，表示發送的郵箱地址
- return 類型：第三個參數表示生成器生成值后返回的內容。例子中函數返回字符串“Done”
然后調用該生成器：
>>> generator = parse_email()
>>> next(generator)
('', '')
#使用 send 方法向生成器發送參數
>>> generator.send("claudia@realpython.com")
('claudia', 'realpython.com')
>>> generator.send("realpython")
'invalid email'
>>> try:
... generator.send("")
... except StopIteration as ex:
... print(ex.value)
...
Done首先調用生成器函數，該函數將返回一個新的 parse_email() 生成器對象。然后，通過調用內置 next() 函數將生成器推進到第一個 yield 語句，之后開始向生成器發送電子郵件地址進行解析。當發送空字符串或不帶 @ 符號的字符串時，生成器將終止。
又因為生成器也是迭代器，因此也可以使用 collections.abc.Iterator 而不是 Generator 來進行類型提示，但是如果使用了 collections.abc.Iterator 類型提示，就不能指定 send 類型和 rerurn 類型，因此只有當生成器只生成值時 collections.abc.Iterator 才起作用：
from collections.abc import Iterator
def parse_emails(emails: list[str]) -> Iterator[tuple[str, str]]:
for email in emails:
if "@" in email:
username, domain = email.split("@")
yield username, domain我們還可以在接收參數里面使用 Iterable 類型提示，這樣表示函數 parse_emails 可以接受任何可迭代對象，而不僅僅是像以前那樣的列表。
