Python 模組教學 - 方便又實用的 dataclasses

Posted on  Feb 1, 2023  in  Python 程式設計 - 中階  by  Amo Chen  ‐ 5 min read

Python dataclasses 是 Python 3.7 新增的 1 個模組(module),主要用途是將結構化的資料定義成類別(class)的形式。

dataclasses 模組提供了一些方便的功能幫助自動產生常用的類別方法,如 __init__ , __repr__ , __eq__ 等,節省開發者撰寫重複程式碼的時間成本。

使用 dataclasses 可以讓 Python 程式更加簡潔,並且提高程式碼的可讀性。

準備好在你的 Python 程式碼中大秀一手使用 dataclasses 的技巧了嗎?

本文環境

  • Python 3.10

為什麼需要 data class?

很多時候,我們會將具有固定結構的資料,以類別(class)的形式進行表達(representation),除了增加可讀性之外,也能夠將與該類別相關的操作封裝(encapsulation)在同一個類別內增加可維護性(maintainability)。

這種專門用以儲存結構化資料的類別就稱為 data class, 可以將該類別簡單想像成是資料的容器即可。

以座標點為例,如果以類別形式進行表達,可能像下列範例:

class Point(object):
    def __init__(self, x, y):
        self.x = x
        self.y = y

從上述範例可以看到 __init__ 方法僅是將各個資料指派(assign)給類別內的屬性而已,隨著資料屬性或者 data class 越來越多,我們就可能一直重複在寫類似的程式碼。

這種情況,可以試著使用看看 Python 的 dataclasses 模組,只要使用 dataclass 裝飾子(decorator)並且定義類別的屬性以及 Python 型別註釋(type annonation) 即可,例如前述的 Point 類別可以簡化成:

from dataclasses import dataclass


@dataclass
class Point:
    x: int
    y: int

改成使用 dataclass 之後是否看起來簡潔多了?

使用方法也與一般使用類別的方式無異:

p = Point(x=1, y=2)
# 或等同
p = Point(1, 2)

Python 的 dataclass 裝飾子做了什麼事?

以下列未使用 dataclass 的類別為例:

class Point(object):
    def __init__(self, x, y):
        self.x = x
        self.y = y

如果是未使用 dataclass 的情況下,單純列印該類別的話:

p1 = Point(1, 2)
print(p1)

其結果將會如下所示,會列印出該類別的記憶體位址:

<__main__.Point object at 0xffff8ffcca90>

但絕大多數情況該資訊對我們開發除錯(debug)並沒有幫助,對於資料類別,我們關注其儲存的值的程度遠遠大於其記憶體位址。

如果要讓類別被列印出來時的資訊更加豐富,就必須實做 __repr__ 方法,例如:

class Point(object):
    def __init__(self, x, y):
        self.x = x
        self.y = y
        
    def __repr__(self):
        return f'Point(x={self.x}, y={self.y})'

這樣在列印該類別時,其輸出結果變成,顯得有意義多了:

Point(x=1, y=2)

不過這也造成當我們每增加一個屬性,就得同時修改 __init____repr__ 2 個地方,實在不夠偷懶。

只要使用 dataclass, 預設就會幫我們把 __init____repr__ 以及 __eq__ 都自動產生,開發者只要專注在定義屬性以及資料型別即可,所以使用 dataclass 後就不需要再特別實作 __init____repr__ 囉,如下列範例:

@dataclass
class Point:
    x: int
    y: int


p1 = Point(1, 2)
print(p1)

其列印結果為:

Point(x=1, y=2)

現在是否為使用 dataclass 感到愉悅呢?

為 dataclass 設定預設值

為 dataclass 設定預設值的方法也很簡單,就像在定義 class level 的屬性值一樣。

下列範例為 Point 設定 x, y 座標預設值為 0:

@dataclass
class Point:
    x: int = 0
    y: int = 0

field 方法

特別需要注意的是,當預設值為 list, dict 等 mutable 的資料型態時,就不可以單純使用前述所提到的預設值設定方法,例如下列範例:

from typing import List


@dataclass
class Point:
    x: int = 0
    y: int = 0
    tags: List[str] = []

上述執行結果會拋出 ValueError 的錯誤,並且提示你應該使用 default_factory 的方式提供預設值:

ValueError: mutable default <class 'list'> for field tags is not allowed: use default_factory

此種錯誤就需要使用 field 進行修正:

from dataclasses import dataclass
from dataclasses import field


@dataclass
class Point:
    x: int = 0
    y: int = 0
    tags: List[str] = field(default_factory=list)

為什麼要使用 field 才能修正呢?

Python stores default member variable values in class attributes.

其原因在於 dataclass 設定預設值的方式,會讓 Python 將預設值放在類別屬性(class variables)層級,也就是說不需要實例化即可存取:

print(Point.x)  # 會輸出 0

那麼對於 list, dict, set 等 mutable 的資料型態來說,所有的 data class 會使用同一組資料,也就導致改了 1 個,其他也會跟著被更動,詳細可以玩看看以下範例,下列範例改了 t1 的 data 屬性,導致 t2 的 data 也跟著變動,進一步檢查會 t1 的 data 與 t2 的 data 的記憶體位置其實是相同的,這也是我們在定義 Python 類別屬性需要特別注意的地方:

from typing import List


class TagList(object):
    data: List[str] = []


t1 = TagList()
t1.data.append('t1')
t2 = TagList()
print('t2.data =>', t2.data)
print('t1.data is t2.data =>', t1.data is t2.data)

上述執行結果如下:

t2.data => ['t1']
t1.data is t2.data => True

為了避免 mutable 資料型態所造成可能的錯誤,所以 dataclasses 才額外設計 field 方法進行修正,所以前述的 Point 類別可以進一步修正為下列形式:

from dataclasses import dataclass
from dataclasses import field


@dataclass
class Point:
    x: int = 0
    y: int = 0
    tags: List[str] = field(default_factory=list)

如果試著修改 tags 屬性,也可以發現不會再有改了 1 個之後,其他也跟著改變的情況:

p1 = Point()
p1.tags.append('p1')
p2 = Point()
print('p2.tags =', p2.tags)
print('p1.tags is p2.tags =', p1.tags is p2.tags)

上述範例執行結果如下:

p2.tags = []
p1.tags is p2.tags = False

field 方法也提供不少參數可以設定,有興趣的話可以詳閱官方文件。

後初始化 (Post-init processing)

The generated __init__() code will call a method named __post_init__(), if __post_init__() is defined on the class.

Python 的 dataclass 所自動產生的 __init__() 方法會在初始化屬性值後,試著呼叫 __post_init__() 方法(如果有實作該方法的話)。

這個相當適合某些需要先初始化之後,才能夠進一步產生的屬性,譬如座標點與原點的距離,就很適合使用 __post_init__() 產生,因為計算與原點距離需要等到 x, y 座標值確定之後方能計算。

下列範例使用 field(init=False) 定義一個不需要在 __init__() 方法傳入的 dist_from_origin 屬性,並且實作 __post_init__() 方法計算並指派(assign) dist_from_origin 屬性的值:

from dataclasses import dataclass
from dataclasses import field


@dataclass
class Point:
    x: int = 0
    y: int = 0
    dist_from_origin: float = field(init=False)
    
    def __post_init__(self):
        self.dist_from_origin = (self.x ** 2 + self.y ** 2) ** 0.5


p1 = Point(3, 4)
print(p1)

上述範例執行結果如下,可以發現我們成功透過 __post__init__() 方法指定 dist_from_origin 的值:

Point(x=3, y=4, dist_from_origin=5.0)

Frozen dataclass

如果希望 dataclass 在實例化之後就不要被任何程式碼更動其值,例如某些唯讀(readonly)的資料,我們可以為 dataclass 裝飾子代入 frozen=True 參數,將 dataclass 的值進行凍結以防止後續更動,例如:

from dataclasses import dataclass


@dataclass(frozen=True)
class Point:
    x: int = 0
    y: int = 0

如此一來,當我們試圖更改其值時:

p1 = Point(3, 4)
p1.x = 5
print(p1)

Python 就會拋出 FrozenInstanceError 的錯誤:

FrozenInstanceError: cannot assign to field 'x'

另外,值得注意的是 Frozen dataclass 跟 __post__init__() 方法不能一起使用,否則也會拋出 FrozenInstanceError 錯誤,例如下列範例:

from dataclasses import dataclass
from dataclasses import field


@dataclass(frozen=True)
class Point:
    x: int = 0
    y: int = 0
    dist_from_origin: float = field(init=False)
    
    def __post_init__(self):
        self.dist_from_origin = (self.x ** 2 + self.y ** 2) ** 0.5


p = Point(3, 4)

上述範例執行結果:

FrozenInstanceError: cannot assign to field 'dist_from_origin'

使用 slots 參數增加效能

由於 Python 預設以 dictionary 儲存類別內的資料與方法,所以在記憶體以及存取的效率上都會有些影響。

因此 Python 提供 slots 類別屬性,供開發者明確指定類別內有哪些屬性,以節省記憶體、讓存取速度較快,因此 dataclass 也同樣可以帶入 slots=True 參數,以明確指定 slots 的方式增加效能:

from dataclasses import dataclass


@dataclass(slots=True)
class Point:
    x: int = 0
    y: int = 0

總結

dataclass 運用得宜的話,可以增加 Python 程式碼的可讀性與可維護性,如果使用需求相當單純,那麼使用 dataclass 是一個相當輕便的選擇。

不過 dataclass 並不具備驗證資料型態的功能,如果有資料型態驗證與檢查的需求的話,建議可以使用 pydantic

以上。

Happy Coding!

References

dataclasses — Data Classes — Python 3.11.1 documentation

對抗久坐職業傷害

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

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

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

贊助我們的創作

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

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