Python 中如何編寫型別提示

哈嘍大家好，我是鹹魚

我們知道 Python 是一門具有動態特性的語言，在編寫 Python 程式碼的時候不需要顯式地指定變數的型別

這樣做雖然方便，但是降低了程式碼的可閱讀性，在後期 review 程式碼的時候容易對變數的型別產生混淆，需要查閱大量上下文，導致後期維護困難

為了提高程式碼的可讀性、可維護性，Python 在 PEP 484 中引入了型別提示（ type hinting）。型別提示是 Python 中一個可選但非常有用的功能，可以使程式碼更易於閱讀和偵錯

關於型別提示的介紹可以看：

https://realpython.com/python-type-hints-multiple-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 None

tuple[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, "[email protected]")
('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("[email protected]")
('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 可以接受任何可迭代物件，而不僅僅是像以前那樣的列表

from collections.abc import Iterable

def parse_emails(emails: Iterable[str]) -> Iterable[tuple[str, str]]:
    for email in emails:
        if "@" in email:
            username, domain = email.split("@")
            yield username, domain