Python 的 typing.Protocol 怎麼使用？

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 的範例一樣，需要修改 Addable 與 sum 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