Python 的 typing.Protocol 怎麼使用?

Posted on  Sep 25, 2023  in  Python 程式設計 - 中階  by  Amo Chen  ‐ 4 min read

Python 3.8 之後 typing 模組 新增 1 個 typing.Protocol 的 class 可以使用,這個 class 很適合用來給一些有實作特定方法的 class 們做 type annotation 。

舉個常見的交通工具作為例子,假設我們有 1 個函數接受任何有實作 move() 方法的 instance:

def move(x):
    x.move()

這時候可以用 typing.Protocol 將參數 x 加上 1 個 type hint, 讓彼此知道此處不管型別,只管是否有實作 move() 方法:

from typing import Protocol

class Movable(Protocol):
    def move(self):
        ...

def move(x: Movable):
    x.move()

加上 typing.Protocol 是否看起來清晰很多?

本文環境

  • Python 3.8 以上

typing.Protocol

Python 3.8 之後, Python 開發者可以使用 typing.Protocol 作為有實作規定方法、屬性(members/attributes)的 type annotation, 這些統一規定好的方法、屬性就稱為 Protocol 。

方法 Protocol

舉需實作 json() 方法的 Protocol 為例,下列 class JSONAble(Protocol) 就代表這是 1 個 type annotation, 被標註 JSONAble 的參數、變數都應該有實作 json() 方法,且該方法回傳型別為 str

p.s. def json(self) -> str: ... 中的 ... 是合法的, ... 用在表 method 或 function 內等同於 no operation 的意思,不具任何行為

from typing import Protocol


class JSONAble(Protocol):
    def json(self) -> str:
        ...


def jsonify(x: JSONAble) -> str:
    return x.json()


class J:
    def json(self) -> str:
        return '{}'


class A: pass


jsonify(J())


jsonify(A())

上述範例執行結果如下,可以看到 A 類別並沒有實作 json() 方法,因此被 mypy 給掃到 jsonify(A()) 不符合規定的 JSONAble type annotation:

test.py:24: error: Argument 1 to "jsonify" has incompatible type "A"; expected "JSONAble"  [arg-type]
Found 1 error in 1 file (checked 1 source file)

屬性 Protocol

如果是規定類別內需有規定的屬性的話,也只需要在繼承 Protocol 的類別內指明屬性名稱與型別即可,例如下列範例中的 RawValue 類別代表,遵從這個 Protocol 的變數都需要有 raw_value 這個屬性,這個屬性可以用 @property 實作,也可以用一般的方式實作:

from typing import Protocol


class RawValue(Protocol):
    raw_value: dict = dict()


def print_raw_value(x: RawValue):
    return x.raw_value


class R:
    @property
    def raw_value(self) -> dict:
        return {}

    @raw_value.setter
    def raw_value(self, d: dict):
        self.value = d


class V:
    raw_value: dict = dict()


print_raw_value(R())  // ok
print_raw_value(V())  // ok

多重 Protocol

如果 1 個 type annotation 需要實作多個 Protocol, 可以用 Union 進行表達,例如:

from typing import Union

a: Union[JSONAble, RawValue] = ...(skipped)...

泛型(Generic) Protocol

typing.Protocol 也支援泛型的用法,下列範例實作 1 個 Box 類別,這個類別在 __add__ 方法中會接受 Box 型別的參數,並回傳 Box 型別的回傳值,我們試圖將 Box(1)Box(2) 放進 sum() 函數中執行:

from typing import Protocol


class Addable(Protocol):
    def __add__(self, other: "Addable") -> "Addable":
        ...

class Box:
    def __init__(self, v: int):
        self.v = v
    def __add__(self, y: "Box") -> "Box":
        return Box(self.v + y.v)


def sum(a: Addable, b: Addable) -> Addable:
    return a + b


sum(Box(1), Box(2))

執行結果雖然正常,但如果用 mypy 掃描,就會出現類似以下的錯誤,原來 Box 並沒有遵循 Addable Protocol, 它的傳入與傳出型別皆是 Box :

test.py:19: error: Argument 1 to "sum" has incompatible type "Box"; expected "Addable"  [arg-type]
test.py:19: error: Argument 2 to "sum" has incompatible type "Box"; expected "Addable"  [arg-type]
Found 2 errors in 1 file (checked 1 source file)

這種情況下要修好它可以把 Addable Protocol 改為傳入與回傳型別都是 Box:

from typing import Protocol


class Addable(Protocol):
    def __add__(self, other: "Box") -> "Box":
        ...

class Box:
    def __init__(self, v: int):
        self.v = v
    def __add__(self, y: "Box") -> "Box":
        return Box(self.v + y.v)


def sum(a: Box, b: Box) -> Addable:
    return a + b


sum(Box(1), Box(2))

但是這種改法就喪失彈性,如果有新的類別也實作 __add__ 方法就又要新增一個新的 Protocol ……沒完沒了。

這時候泛型(Generic)就派上用場了,可以使用 typing.TypeVar 製作 1 個可以代表任何型別的變數,然後放進去 Protocol 中,例如下列代表 Addable Protocol 接受 1 個型別做為參數,其方法 __add__ 的傳入與傳出型別會自動換成 Protocol 所接受的型別參數:

T = TypeVar("T")


class Addable(Protocol[T]):
    def __add__(self, other: T) -> T:

上述範例可以這樣使用:

a: Addable[int] = 1

上述寫法代表 a 變數的Addable Protocol 如下,這種泛型的用法讓我們不用像先前 Box 的範例一樣,需要修改 Addablesum 2 個地方才能修正 type checker 的錯誤:

class Addable(Protocol[int]):
    def __add__(self, other: int) -> int:

結合 TypeVar 與 Protocol 之後,就可以把先前 Box 範例修正為下列形式:

from typing import Protocol, TypeVar


T = TypeVar("T")


class Addable(Protocol[T]):
    def __add__(self, other: T) -> T:
        ...

def sum(a: Addable, b: Addable) -> Addable:
    return a + b


class Box:
    def __init__(self, v: Addable):
        self.v = v
    def __add__(self, y: "Box") -> "Box":
        return Box(self.v + y.v)


a: Addable[Box] = Box(1)
b: Addable[Box] = Box(2.1)

sum(a, b)

如此就能夠通過 type checker 的檢查,也不必修改 sum() 函數的 type annotation 了!

噢對,有人可能會疑問 def __add__(self, y: "Box") -> "Box": 中的傳入與傳出會用雙引號包起來變成 "Box" ,這是因為如果不用雙引號包起來, Python 解析程式碼時會出現 NameError: name 'Box' is not defined ,代表 Python 在解析 Box class 的階段還不認識 Box`` 這個型別,因此可以用 “Box”` 代替,這是被稱為 Forward References 的用法。

Forward references When a type hint contains names that have not been defined yet, that definition may be expressed as a string literal, to be resolved later.

總結

Python 的 typing 模組越來越強大,很多以往不方便標註型別的問題,隨著版本演進越來越方便,如果你是單人開發寫興趣的,其實可以不必使用這個模組,但如果是團隊開發或者是開源專案,建議使用 typing 模組會對彼此更好!

如果想知道更多 typing 模組的教學,也歡迎詳閱使用 Python typing 模組對你的同事好一點 一文。

以上!

Happy Coding!

References

PEP 544 – Protocols: Structural subtyping (static duck typing)

PEP 484 – Type Hints

FOLLOW US

對抗久坐職業傷害

研究指出每天增加 2 小時坐著的時間,會增加大腸癌、心臟疾病、肺癌的風險,也造成肩頸、腰背疼痛等常見問題。

然而對抗這些問題,卻只需要工作時定期休息跟伸展身體即可!

你想輕鬆改變現狀嗎?試試看我們的 PomodoRoll 番茄鐘吧! PomodoRoll 番茄鐘會根據你所設定的專注時間,定期建議你 1 項辦公族適用的伸展運動,幫助你打敗久坐所帶來的傷害!

贊助我們的創作

看完這篇文章了嗎? 休息一下,喝杯咖啡吧!

如果你覺得 MyApollo 有讓你獲得實用的資訊,希望能看到更多的技術分享,邀請你贊助我們一杯咖啡,讓我們有更多的動力與精力繼續提供高品質的文章,感謝你的支持!