Python資料塑形與管理：Pydantic 與 SQLAlchemy 的完美結合：深入解析 Pydantic 的序列化與資料型別 (第1集)

– 15 分鐘閱讀
  
現代軟體開發中，高效的資料管理至關重要，它直接影回應用程式的效能、可擴充套件性和可維護性。良好的資料管理確保資料完整性、一致性，以及資料的高效檢索和操作。本文將探討資料管理的重要性，並深入研究如何結合 Pydantic 和 SQLAlchemy，構建一個穩健與高效的解決方案。

## 資料管理的重要性

資料是所有應用程式的核心，資料處理方式的好壞直接影響專案的成敗。資料管理不善會導致資料不一致、資料損壞和效能瓶頸，最終損害使用者經驗，甚至埋下安全漏洞。相反，適當的資料管理能提升資料完整性，確保應用程式各元件間的一致性，並實作資料的高效查詢和操作。

資料管理包含幾個關鍵導向：資料驗證、解析、序列化和儲存。資料驗證確保資料符合預定義的規則和約束，防止無效或不一致的資料在應用程式中傳播。資料解析是將資料從一種格式（例如 JSON、XML）轉換為結構化表示，以便應用程式輕鬆處理。資料序列化則是將應用程式資料轉換為適合儲存或傳輸的格式，例如 JSON 或資料函式庫友善的表示。

有效的資料管理不僅確保資料完整性和一致性，還能提升應用程式效能，減少處理無效或不一致資料的開銷。此外，它透過明確區分應用程式邏輯和資料管理操作，提高可維護性，使應用程式更易於發展和修改。

## Pydantic 簡介

Pydantic 是一個 Python 函式庫，提供強大的資料驗證和解析功能，是應用程式資料管理的利器。它允許使用嚴格的型別註解和驗證規則定義資料模型，確保應用程式只處理有效與一致的資料。

Pydantic 的一個關鍵特性是在執行時進行資料驗證。透過為資料模型定義驗證規則和約束，Pydantic 能及早發現錯誤，防止無效資料在應用程式中傳播。這不僅增強了資料完整性，還簡化了除錯過程，提供清晰與資訊豐富的錯誤訊息。

除了資料驗證，Pydantic 還擅長資料解析和序列化。它可以將來自各種來源的資料（例如 JSON、請求主體和資料函式庫）解析為 Python 物件，確保資料一致性，無需手動解析和驗證。反之，Pydantic 也能將 Python 物件轉換回其他格式（例如 JSON、資料函式庫友善的表示）以便儲存或傳輸。

Pydantic 的彈性和可擴充套件設計允許定義具有巢狀結構的複雜資料模型，準確表示應用程式資料中的關係和層次結構。此外，它與 FastAPI 和 Django 等熱門 Python 網頁框架無縫整合，簡化了網頁應用程式中處理和驗證輸入資料的過程。

## SQLAlchemy 簡介

SQLAlchemy 是一個 Python SQL 工具包和物件關聯對映（ORM）函式庫，提供一組高階 API，用於與資料函式庫互動。它抽象化了底層資料倉管理系統（DBMS），允許編寫適用於各種資料函式庫引擎（例如 PostgreSQL、MySQL、SQLite）的 Python 程式碼，而無需修改應用程式碼。

SQLAlchemy 的核心特性之一是它的 ORM 層，它提供資料函式庫的抽象層，允許使用 Python 物件操作資料函式庫，無需編寫原始 SQL 查詢。這種抽象簡化了與資料函式庫互動的過程，並提高了程式碼可重用性和可維護性。

SQLAlchemy 的表示式查詢語言允許使用 Python 程式碼建構複雜的資料函式庫查詢，更易於管理和維護應用程式的資料存取邏輯。這種方法不僅提高了程式碼可讀性，還透過將查詢邏輯與資料值分離，降低了 SQL 注入攻擊的風險。

除了 ORM 功能外，SQLAlchemy 還提供強大的資料函式庫遷移工具，協助管理和演進資料函式庫結構描述。這些工具允許對資料函式庫結構描述進行版本控制，並以受控與一致的方式套用結構描述變更，確保應用程式資料保持一致性和最新狀態。

SQLAlchemy 還支援多種資料函式庫引擎，包括 PostgreSQL、MySQL、SQLite 和 Oracle 等熱門選項。這種靈活性允許選擇最符合專案需求的資料倉管理系統，而無需大幅修改應用程式碼。


## Pydantic 與 SQLAlchemy 的整合

Pydantic 和 SQLAlchemy 可以結合使用，為 Python 應用程式建立強大與穩健的資料管理解決方案。透過利用兩個函式庫的優勢，可以在整個應用程式生命週期中確保資料完整性、一致性和高效的資料管理。

整合過程通常包含以下步驟：

1. 使用 Pydantic 定義資料模型：使用 Pydantic 定義應用程式的資料模型，指定資料型別、驗證規則和約束。這些模型作為應用程式資料的藍圖，定義將要處理的資料的結構和驗證規則。

2. 將資料模型對映到資料函式庫表格：SQLAlchemy 的 ORM 層允許將 Pydantic 資料模型對映到資料函式庫表格，在應用程式資料結構和底層資料函式庫結構描述之間建立明確的關係。此對映過程通常透過建立繼承自 Pydantic 模型的 SQLAlchemy 模型來實作，確保在資料函式庫層級強制執行 Pydantic 中定義的資料驗證規則。

3. 使用 Pydantic 驗證和解析資料：從資料函式庫檢索資料時，使用 Pydantic 解析和驗證資料，確保資料符合預定義的規則和約束。此步驟對於維護資料完整性至關重要，可防止無效或不一致的資料在應用程式中傳播。

4. 使用 SQLAlchemy 持續化資料：儲存或更新資料時，使用 SQLAlchemy 與資料函式庫互動，利用其查詢建構功能和資料函式庫抽象層。SQLAlchemy 的表示式查詢語言和 ORM 抽象簡化了與資料函式庫互動的過程，降低了錯誤風險，並提高了程式碼可維護性。


透過結合 Pydantic 和 SQLAlchemy，可以受益於兩個函式庫的優勢，確保在整個應用程式生命週期中實作資料完整性、一致性和高效的資料管理。Pydantic 確保應用程式資料符合預定義的規則和約束，而 SQLAlchemy 簡化了資料函式庫互動，並提供一個強大的抽象層，用於與各種資料倉管理系統協作。


本文介紹了正確資料管理的重要性，以及如何結合 Pydantic 和 SQLAlchemy 的強大功能來處理軟體開發中的這個關鍵導向。Pydantic 透過其穩健的驗證和解析功能確保資料完整性和一致性，而 SQLAlchemy 簡化了資料函式庫互動，並提供一個強大的抽象層，用於與各種資料倉管理系統協作。透過整合這兩個函式庫，開發者可以構建更可靠、高效與易於維護的資料驅動應用程式。

Pydantic 與資料模型的深度解析

在 Python 開發中，資料的有效性驗證和序列化至關重要。Pydantic 作為一個強大的 Python 函式庫，恰好能簡化這些流程。我將探討 Pydantic 的核心概念和功能，並分享我在實際專案中使用 Pydantic 的經驗和技巧。

Pydantic：資料驗證和序列化的利器

Pydantic 主要用於資料驗證和序列化，它提供了一種簡潔的方法來定義資料模型、驗證輸入資料，並在不同格式之間轉換資料（例如 Python 資料結構、JSON 等）。我發現 Pydantic 的優勢主要體現在以下幾個方面：

  • 資料模型： 使用 Python 型別註解定義資料模型，提升程式碼可讀性和可維護性。這點在大型專案中尤其重要，清晰的資料模型定義可以減少很多溝通成本。
  • 資料驗證： 自動驗證輸入資料是否符合模型定義，確保資料的完整性和一致性。這可以有效避免許多資料相關的錯誤，提升程式碼的健壯性。
  • 資料解析和序列化： 解析來自各種來源的資料（例如 JSON、Python 字典），並將資料序列化為不同格式。這簡化了資料處理流程，尤其是在處理 API 資料時非常方便。

Pydantic 模型的建立與應用

Pydantic 模型使用 Python 型別註解定義，易於閱讀和維護。這些模型可以定義各種資料型別，包括基本型別（例如整數、字串）、複雜資料結構（例如列表、字典），甚至自定義型別。

from pydantic import BaseModel

class User(BaseModel):
    name: str
    age: int
    email: str

這個例子定義了一個 User 模型，包含 name（字串）、age（整數）和 email（字串）三個欄位。即使是這樣一個基本的模型，Pydantic 也提供了型別驗證、資料解析和序列化等功能。相較於使用 dataclass，Pydantic 模型的功能更強大、更靈活。

模型繼承與初始化的技巧

Pydantic 支援模型繼承，可以透過繼承現有模型來建立新模型，促程式式碼重用。

from pydantic import BaseModel

class BaseUser(BaseModel):
    name: str
    email: str

class Student(BaseUser):
    grade: int

這個例子中，Student 模型繼承了 BaseUser 模型，並新增了一個 grade 欄位。

Pydantic 提供多種初始化模型的方式，方便處理來自不同來源的資料。

  • 從 Python 字典初始化：
user_data = {'name': 'John Doe', 'age': 30, 'email': 'john@example.com'}
user = User(**user_data)
  • 從 JSON 資料初始化：
import json
from pydantic import BaseModel

class User(BaseModel):
    name: str
    age: int
    email: str

json_data = '{"name": "John Doe", "age": 30, "email": "john@example.com"}'
user = User.parse_raw(json_data)
  • 從物件例項初始化：
from pydantic import BaseModel

class OtherUserModel:
    def __init__(self, name, age, email):
        self.name = name
        self.age = age
        self.email = email

class User(BaseModel):
    name: str
    age: int
    email: str

other_user = OtherUserModel('John Doe', 30, 'john@example.com')
user = User.parse_obj(other_user)
  • 使用預設值：
from pydantic import BaseModel, Field

class User(BaseModel):
    name: str
    age: int = Field(default=18, ge=18)
    email: str = 'default@example.com'

user = User(name='John Doe')

Pydantic 的實戰應用與延伸思考

在我過去的專案經驗中，Pydantic 在處理 API 資料、組態檔案讀取、資料函式庫模型定義等方面都展現了強大的實用性。它可以有效減少程式碼量，提高開發效率，並提升程式碼的可靠性和可維護性。

我認為 Pydantic 的價值不僅在於其本身的功能，更在於它倡導的一種程式設計理念：型別安全和資料驗證優先。這種理念可以幫助我們寫出更健壯、更易於維護的程式碼。

  graph LR
    D[D]
    F[F]
    A[Python 字典] --> B(Pydantic Model);
    C[JSON 資料] --> D{parse_raw};
    D --> B;
    E[物件例項] --> F{parse_obj};
    F --> B;
    B --> G[資料驗證];
    B --> H[序列化];

圖表說明： 此圖表展示了 Pydantic 模型的初始化過程和主要功能。可以從 Python 字典、JSON 資料或物件例項建立 Pydantic 模型，模型建立後可以進行資料驗證和序列化。

我建議在 Python 開發中積極採用 Pydantic，它可以幫助你更好地管理資料，減少錯誤，提升程式碼品質。

Pydantic 模型的進階應用：初始化、巢狀結構與驗證

理解 Pydantic 模型的初始化方法，能讓您更靈活地處理來自不同來源的資料，並以更便捷的方式建立模型例項。本文將探討模型初始化的技巧、巢狀模型的建立，以及如何使用驗證器來確保資料的正確性。

模型初始化方法

Pydantic 提供多種模型初始化方法，方便處理不同資料來源：

  • 直接使用建構函式：這是最常見的方式，直接傳入欄位值即可。
  • 使用 parse_obj：從 Python 物件建立模型例項。
  • 使用 parse_raw：從原始資料（例如 JSON 字串）建立模型例項。
  • 使用 parse_file：從檔案載入資料並建立模型例項。

類別方法

Pydantic 模型可以包含類別方法，可用於對模型本身或其例項執行操作。

from pydantic import BaseModel

class User(BaseModel):
    name: str
    age: int
    email: str

    @classmethod
    def create_dummy(cls):
        return cls(name="John Doe", age=30, email="john@example.com")

這個例子定義了一個 create_dummy 類別方法，用於建立並傳回一個虛擬的 User 例項。然而，通常建議將模型的重點放在資料表示和驗證上，並將通用方法和工具函式移到單獨的模組或類別中。

巢狀模型

Pydantic 允許您定義包含其他模型例項的欄位，從而建立具有巢狀資料結構的複雜物件模式。

from pydantic import BaseModel

class Address(BaseModel):
    street: str
    city: str
    zipcode: str

class User(BaseModel):
    name: str
    age: int
    email: str
    address: Address

此例中，我們定義了一個 Address 模型，並將其作為 User 模型的一個欄位。這種方法在定義和驗證複雜資料結構的同時，保持了關注點的清晰分離。

簡單的驗證器範例

Pydantic 也支援自定義驗證器，以應對更進階的驗證場景。以下是一個簡單的驗證器範例，用於檢查使用者的年齡是否在特定範圍內：

from pydantic import BaseModel, validator

class User(BaseModel):
    name: str
    age: int
    email: str

    @validator('age')
    def validate_age(cls, age):
        if age < 18 or age > 65:
            raise ValueError("年齡必須介於 18 到 65 之間")
        return age

此例中，我們使用 @validator('age') 裝飾器定義了 validate_age 方法。每當設定 age 欄位時，都會呼叫此方法，如果年齡超出指定範圍，則會引發 ValueError。

Pydantic 驗證器：深入理解與應用

驗證器是 Pydantic 的核心功能，允許您對資料模型強制執行自定義規則和約束。本章將探討驗證器的型別、使用方法以及與傳統驗證器的區別。

什麼是 Pydantic 驗證器？

Pydantic 驗證器是函式或方法，用於對照模型驗證的資料執行額外檢查或轉換。它們超越了 Pydantic 模型定義提供的基本型別驗證，允許您實作更複雜的驗證邏輯。

Pydantic 驗證器與傳統驗證器有以下幾個主要區別：

  1. 與模型整合：Pydantic 驗證器與模型定義緊密整合，易於定義和維護。
  2. 執行順序：Pydantic 強制執行驗證器的特定執行順序，確保不同驗證場景下的行為一致性。
  3. 錯誤處理：Pydantic 提供統一的錯誤處理機制，允許您自定義錯誤訊息並輕鬆處理驗證失敗。

Field 方法

Field 方法是 Pydantic 中一個強大的工具，允許您為各個模型欄位指定額外的中繼資料和約束。它可以用於定義預設值、驗證等等。

以下是如何使用 Field 指定最小值約束的範例：

from pydantic import BaseModel, Field

class User(BaseModel):
    name: str
    age: int = Field(..., gt=18)

此例中，age 欄位使用 Field 方法的 gt（大於）引數定義了最小值約束。

Pydantic 驗證方法

Pydantic 提供多種方法來協助驗證活動：

  • parse_obj：從 Python 物件驗證並建立模型例項。
  • parse_raw：從原始資料（例如 JSON 字串）驗證並建立模型例項。
  • validate：驗證模型例項而不建立新例項。

這些方法在各種場景下都很有用，例如驗證使用者輸入或處理來自外部來源的資料。

定義驗證器

Pydantic 提供多種定義驗證器的方式，每種方式都有其自身的使用案例和優勢。

欄位級驗證器

欄位級驗證器使用 @validator 裝飾器定義，並應用於單個模型欄位。

from pydantic import BaseModel, validator

class User(BaseModel):
    name: str
    email: str

    @validator('email')
    def email_validator(cls, value):
        if '@' not in value:
            raise ValueError('無效的電子郵件格式')
        return value

此例中，email_validator 函式使用 @validator('email') 裝飾，確保在設定或驗證 email 欄位時呼叫它。

根驗證器

根驗證器應用於整個模型例項，可用於驗證跨多個欄位的複雜關係或約束。

from pydantic import BaseModel, root_validator

class User(BaseModel):
    name: str
    password: str
    confirm_password: str

    @root_validator
    def passwords_match(cls, values):
        password = values.get('password')
        confirm_password = values.get('confirm_password')
        if password != confirm_password:
            raise ValueError('密碼不符')
        return values

此例中，passwords_match 函式使用 @root_validator 裝飾，並檢查 password 和 confirm_password 欄位是否比對。

根據註解的驗證器

Pydantic 也支援使用 Python 的型別註解定義驗證器。這種方法更簡潔易讀，尤其適用於簡單的驗證邏輯。

from pydantic import BaseModel, EmailStr

class User(BaseModel):
    name: str
    email: EmailStr

此例中，EmailStr 註解用於驗證 email 欄位，確保其符合有效的電子郵件格式。

類別方法驗證器

Pydantic 允許您將驗證器定義為類別方法，這對於在多個模型之間共用驗證邏輯或更複雜的驗證場景非常有用。

from pydantic import BaseModel, validator

class User(BaseModel):
    name: str
    email: str

    @validator('email', pre=True)
    def normalize_email(cls, value):
        return value.lower().strip()

此例中，normalize_email 類別方法用作驗證器，在驗證之前標準化 email 欄位。pre=True 引數確保在任何其他驗證器或型別檢查之前執行驗證器。

Pydantic 還支援 typing_extensions 模組中的 Annotated 型別，它允許您將中繼資料或約束附加到型別註解。這對於在模型欄位上定義更複雜的驗證器或約束非常有用。

以下是如何使用 Annotated 的範例：

from typing import Annotated
from pydantic import BaseModel, validator

class StrMaxLength:
    def __init__(self, max_length: int):
        self.max_length = max_length

    def __call__(self, value: str):
        if len(value) > self.max_length:
            raise ValueError(f'字串長度超過最大值 {self.max_length} 個字元')
        return value

class User(BaseModel):
    name: Annotated[str, StrMaxLength(20)]
    email: str

    @validator('name')
    def validate_name(cls, value, values, config, field):
        max_length = field.annotation.max_length
        if len(value) > max_length:
            raise ValueError(f'名稱長度不能超過 {max_length} 個字元')
        return value

這個例子定義了一個自定義的 StrMaxLength 類別，作為字串長度的驗證器。然後，我們使用 Annotated 將 StrMaxLength 的例項附加到 name 欄位，限制其最大長度為 20 個字元。

透過靈活運用這些驗證器，您可以更精確地控制資料驗證過程，確保資料的完整性和一致性。

視覺化 Pydantic 模型

Mermaid 圖表可以清晰地展現 Pydantic 模型的結構和關係。以下是一個使用 Mermaid 類別圖 (classDiagram) 描述 User 和 Address 模型關係的示例：

  classDiagram
    class User {
        name: str
        age: int
        email: str
        address: Address
    }
    class Address {
        street: str
        city: str
        zipcode: str
    }
    User -- Address : has

圖表說明: 此圖表顯示 User 模型擁有一個 Address 模型的例項作為其屬性。

這個圖表清晰地展示了 User 和 Address 模型之間的關係，讓讀者更容易理解巢狀模型的概念。

藉由結合 Pydantic 的強大功能和 Mermaid 圖表的視覺化呈現，您可以更有效地設計、驗證和檔案化您的資料模型。

深入理解 Pydantic 的進階功能，能讓您更有效地處理資料驗證和模型管理，提升程式碼的可靠性和可維護性。

  
在現代軟體開發中，資料驗證和序列化是確保資料完整性和互通性的關鍵步驟。Pydantic 作為 Python 中一個強大的資料驗證和序列化函式庫，提供了豐富的功能和彈性的組態選項，可以幫助開發者輕鬆構建高效能與易於維護的應用程式。本文將探討 Pydantic 的進階技巧，包含客製化驗證器、資料轉換、內建驗證器的使用，以及錯誤處理和格式化。此外，我們還將深入研究如何利用客製化序列化器來處理日期時間物件，使其更易於閱讀和理解。

## Pydantic 驗證器：確保資料品質的守門員

Pydantic 的驗證器功能允許開發者對資料模型中的欄位進行各種驗證和轉換操作。以下是一些進階的驗證器使用技巧：

### 利用 `Annotated` 建立更具表達力的驗證器

```python
from typing import Annotated
from pydantic import BaseModel, Field, validator
from typing_extensions import Annotated as Ann

class Model(BaseModel):
    name: Annotated[str, Field(max_length=10)]

    @validator('name')
    def validate_name(cls, value, field):
        if len(value) > field.annotation.max_length:
            raise ValueError(f"名稱長度不能超過 {field.annotation.max_length}")
        return value

內容解密：

這段程式碼展示瞭如何使用 Annotated 和 typing_extensions 模組來建立更具表達力和宣告式的驗證器。我們將 max_length 限制直接附加到 name 欄位的型別註解中，並在 validate_name 方法中透過 field.annotation.max_length 讀取此限制。

不同型別驗證器的使用時機

  • 欄位級驗證器：適用於驗證單個欄位或執行簡單的欄位值轉換。
  • 根驗證器：適用於驗證跨多個欄位的複雜關係或限制。
  • 根據註解的驗證器：適用於簡單的驗證邏輯，程式碼簡潔易讀。
  • 類別方法驗證器：適用於在多個模型之間共用驗證邏輯，或處理需要額外上下文或狀態的複雜驗證場景。

使用驗證器轉換資料

驗證器不僅可以驗證資料，還可以將資料轉換為可用的格式。

from pydantic import BaseModel, validator
import datetime

class Event(BaseModel):
    name: str
    date: datetime.date

    @validator('date', pre=True)
def parse_date(cls, value):
        return datetime.datetime.strptime(value, '%Y-%m-%d').date()

內容解密：

這段程式碼示範瞭如何使用 parse_date 驗證器在驗證 date 欄位之前，將日期字串轉換為 datetime.date 物件。

內建驗證器的活用

Pydantic 提供了許多內建驗證器，例如 gt、ge、lt、le、max_length、min_length、regex、email_validator 和 url_validator 等，可以滿足常見的驗證需求。

客製化錯誤處理和格式化

當驗證失敗時，Pydantic 會引發 ValidationError 異常。開發者可以透過提供自定義錯誤訊息字串或可呼叫的函式來自定義錯誤訊息。

from pydantic import BaseModel, ValidationError

class User(BaseModel):
    name: str
    age: int

    @validator('age')
    def age_validator(cls, value):
        if value < 18:
            raise ValueError('您必須年滿 18 歲')
        return value

def custom_error_formatting(errors):
    # ... (錯誤格式化邏輯)

內容解密：

這段程式碼示範瞭如何使用 custom_error_formatting 函式覆寫預設的錯誤格式化邏輯，以及如何在 age_validator 中引發帶有自定義錯誤訊息的 ValueError。

Pydantic 序列化器：資料交換的橋樑

內建序列化器的限制

Pydantic 的內建序列化器雖然功能強大，但在某些情況下可能不夠用，例如將日期時間物件序列化為更易讀的格式。

客製化序列化器：解決日期時間格式問題

為了將日期時間物件序列化為更易讀的格式，我們可以建立客製化序列化器。

from pydantic import BaseModel, Field
import datetime

class Event(BaseModel):
    name: str
    date: datetime.datetime = Field(..., serialize_format="%Y年%m月%d日 %H:%M:%S")

event = Event(name="研討會", date=datetime.datetime(2024, 4, 27, 9, 30))
print(event.json())  # 輸出：{"name": "研討會", "date": "2024年04月27日 09:30:00"}

內容解密：

這段程式碼示範瞭如何使用 serialize_format 引數將日期時間物件序列化為指定的格式。

本文探討了 Pydantic 的進階技巧，包括客製化驗證器、資料轉換、內建驗證器的使用、錯誤處理和格式化，以及客製化序列化器。透過靈活運用這些技巧，開發者可以更好地控制資料驗證和序列化的過程，從而提升應用程式的效能、可讀性和可維護性。

  

Mermaid 圖表範例：

```mermaid
graph LR
    A[輸入資料] --> B{驗證器};
    B -- 驗證透過 --> C[模型例項];
    B -- 驗證失敗 --> D[ValidationError];

圖表說明：此流程圖展示了 Pydantic 的資料驗證流程。輸入資料經過驗證器處理，如果驗證透過則建立模型例項，否則引發 ValidationError。

  classDiagram
    class BaseModel {
        +json()
    }
    class Event {
        -name: str
        -date: datetime
    }
    Event --|> BaseModel

圖表說明：此類別圖展示了 Event 類別繼承自 Pydantic 的 BaseModel 類別，並包含 name 和 date 兩個屬性。

玄貓

玄貓

技術愛好者，專注於分享程式開發、雲端技術與 AI 應用的心得體會。