Pydantic 入門 – Pythonでのデータ検証・設定管理

By /

はい、承知いたしました。Pydanticの入門に関する詳細な記事を作成します。約5000語を目指し、データ検証と設定管理に焦点を当てて記述します。記事の内容を直接ここに表示します。

Pydantic 入門 – Pythonでのデータ検証・設定管理

はじめに：なぜデータ検証と設定管理が必要なのか？

Pythonは非常に柔軟な言語ですが、その柔軟さゆえに、特にプログラムの実行時にデータ型や値に関する問題が発生しやすい側面もあります。外部から受け取ったデータ（APIからの応答、ファイルの内容、ユーザー入力など）や、プログラムの挙動を制御するための設定値は、常に期待通りの形式や値であるとは限りません。これらのデータが不正であった場合、プログラムは予期せぬエラーを起こしたり、セキュリティ上の脆弱性につながったり、誤った結果を生成したりする可能性があります。

信頼性の高い堅牢なアプリケーションを構築するためには、以下の2つの要素が不可欠です。

  1. データ検証（Data Validation）: 外部から入力されるデータや、プログラム内部で受け渡されるデータの構造、型、値が正しいことを確認するプロセスです。これにより、不正なデータを早期に検知し、エラーハンドリングを適切に行うことができます。
  2. 設定管理（Settings Management）: データベースの接続情報、APIキー、ログレベル、機能フラグなど、アプリケーションの実行環境に依存する設定値を安全かつ効率的に管理するプロセスです。環境変数、設定ファイル（.envなど）、コマンドライン引数など、様々なソースからの設定値を一元的に扱えると便利です。

従来のPython開発では、これらの要件を満たすために手作業での型チェックや条件分岐、設定ファイルのパースとバリデーションを記述することが一般的でした。しかし、これは冗長でエラーが発生しやすく、コードの可読性や保守性を損なう原因となります。

ここで登場するのが Pydantic です。

Pydanticとは？

Pydanticは、Pythonの型ヒントを活用して、データの検証、シリアライズ、デシリアライズ、そして設定管理を自動化するライブラリです。Pythonの標準的な型ヒント構文を使うだけで、強力なデータモデルを定義し、実行時にデータの整合性を保証できます。

Pydanticの主な特徴は以下の通りです。

  • Pythonの型ヒントとの完全な連携: Python 3.5以降で導入された型ヒント（Type Hinting）をそのまま利用してデータ構造を定義します。
  • 実行時検証: インスタンスが生成される際に、渡されたデータが定義された型や制約を満たしているかを自動的に検証します。
  • 高速性: コア部分がRustで実装されているため、非常に高速なデータ検証が可能です。
  • 使いやすさ: 直感的でミニマルなAPIを提供しており、学習コストが低いのが特徴です。
  • データ変換（Coercion）: 可能であれば、入力データを定義された型に自動的に変換しようとします（例: 文字列 “123” を整数 123 に）。
  • 設定管理機能: 環境変数や.envファイルから設定値をロードし、検証付きの設定オブジェクトとして扱えます。
  • JSON Schema生成: 定義したモデルから自動的にJSON Schemaを生成できます。

Pydanticは、Webフレームワーク（FastAPIなど）、データ処理パイプライン、APIクライアント、設定ファイルパーサーなど、様々な場面で活用されています。特にFastAPIでは、Pydanticモデルがリクエストボディやレスポンスの定義に広く使われており、自動的なデータ検証とドキュメンテーション生成の核となっています。

この記事では、Pydanticの基本的な使い方から始まり、より高度な機能、そしてデータ検証と設定管理における実践的な応用例までを詳細に解説します。

Pydanticのインストール

Pydanticを使い始めるのは非常に簡単です。pipを使ってインストールできます。

bash
pip install pydantic

設定管理機能のために.envファイルからの読み込みを行う場合は、以下の追加パッケージが必要です。

bash
pip install "pydantic-settings[dotenv]"

BaseModelの基本

Pydanticの中核をなすのが BaseModel クラスです。データ構造を定義するには、このクラスを継承した新しいクラスを作成し、Pythonの型ヒントを使ってフィールド（属性）を定義します。

“`python
from pydantic import BaseModel

ユーザー情報を表すデータモデルを定義

class User(BaseModel):
id: int
name: str = ‘John Doe’ # デフォルト値
signup_ts: datetime | None = None # Optionalフィールド (datetime または None)
friends: list[int] = [] # リストの型検証とデフォルト値

from datetime import datetime

モデルのインスタンスを生成（データの検証が実行される）

user_data = {
“id”: 123,
“signup_ts”: “2023-01-15T12:00:00”, # 文字列形式の日付も自動変換される
“friends”: [1, 2, “3”] # “3” は整数に変換される
}

try:
user = User(**user_data) # 辞書を展開してキーワード引数として渡す

print(user.id)
print(user.name) # デフォルト値 'John Doe' が使用される
print(user.signup_ts)
print(user.friends) # [1, 2, 3] と表示される（"3" が整数に変換されている）
print(user.model_dump()) # モデルを辞書に変換

except Exception as e:
print(f”エラーが発生しました: {e}”)
“`

上記のコードでは、User という BaseModel を継承したクラスを定義しています。

  • id: int: id というフィールドは整数型である必要があります。
  • name: str = 'John Doe': name というフィールドは文字列型で、データが提供されない場合は 'John Doe' がデフォルト値として使われます。
  • signup_ts: datetime | None = None: signup_ts は datetime オブジェクトか None のいずれかを取ることができます。デフォルト値は None です。Python 3.10以降では X | Y 構文が、それ以前では Optional[X] (from typing import Optional) が使えます。Pydanticは多くの標準ライブラリの型やtypingモジュールの型をサポートしています。
  • friends: list[int] = []: friends は整数のリストである必要があります。デフォルト値は空のリストです。

User(**user_data) のように、辞書をキーワード引数として渡すことで User クラスのインスタンスを生成します。この際、Pydanticは自動的に以下の処理を行います。

  1. user_data 辞書のキーと User モデルのフィールドをマッピングします。
  2. 各フィールドに対して、定義された型ヒントに基づいてデータの 検証 を行います。
  3. 必要に応じて、データの 型変換（Coercion） を行います。例えば、"2023-01-15T12:00:00" という文字列は自動的に datetime オブジェクトに変換されます。リスト内の "3" という文字列は整数 3 に変換されます。
  4. 検証と変換に成功した場合、検証済みのデータを持つ User オブジェクトが生成されます。
  5. 検証に失敗した場合、pydantic.ValidationError 例外が送出されます。

生成されたモデルインスタンスのフィールドには、通常のPythonオブジェクトの属性と同じようにアクセスできます（例: user.id）。また、.model_dump() メソッドを使うと、モデルの内容をPythonの辞書形式で取得できます（Pydantic v1では .dict() や .json() でしたが、v2で変更されました）。.model_dump_json() を使うとJSON文字列として取得できます。

検証エラー (ValidationError) の扱い

データがモデルの定義を満たさない場合、ValidationError が発生します。この例外オブジェクトには、発生したエラーの詳細が含まれています。

“`python
from pydantic import BaseModel, ValidationError

class Product(BaseModel):
name: str
price: float
is_available: bool

不正なデータを含む辞書

bad_data = {
“name”: “Laptop”,
“price”: “not a price”, # priceはfloatであるべき
“is_available”: 1 # is_availableはboolであるべき (ただしPydanticは1/0をboolに変換可能なので、これは通る)
}

別の不正なデータ

bad_data_2 = {
“name”: “”, # nameは空文字列だが、str型としては有効
“price”: 1200.0,
# is_available が欠落している
}

try:
product = Product(**bad_data)
except ValidationError as e:
print(“検証エラーが発生しました:”)
print(e.errors()) # エラーの詳細なリストを取得
print(e.json()) # エラー情報をJSON形式で取得

try:
product_2 = Product(**bad_data_2)
except ValidationError as e:
print(“\n別の検証エラーが発生しました:”)
print(e.errors())
“`

ValidationError オブジェクトの .errors() メソッドは、発生した各エラーに関する情報を辞書のリストとして返します。それぞれの辞書には以下のキーが含まれます。

  • type: エラーのタイプ（例: 'string_type', 'float_parsing', 'missing')
  • loc: エラーが発生したフィールドの位置（例: ('price',), ('is_available',), ('name', 0, 'id') のようにネストされた位置も示す）
  • msg: 人間に読めるエラーメッセージ
  • input: 入力された元の値

このエラー情報を利用することで、ユーザーに具体的なエラー内容をフィードバックしたり、プログラム内でエラーの種類に応じた処理を行ったりすることができます。

デフォルト値とOptionalフィールドの詳細

デフォルト値を設定するには、フィールドの型ヒントに続けて = 値 を指定します。

“`python
class Item(BaseModel):
name: str = ‘Unnamed Item’ # 文字列のデフォルト値
quantity: int = 1 # 整数のデフォルト値
description: str | None = None # None がデフォルト値
tags: list[str] = [] # リストのデフォルト値（ミュータブルなデフォルト値は注意が必要だが、Pydanticは内部的に解決している）

item1 = Item(name=’Book’) # quantityとtagsはデフォルト値、descriptionはNone
print(item1) # name=’Book’ quantity=1 description=None tags=[]

item2 = Item(quantity=5, tags=[‘python’, ‘pydantic’]) # nameはデフォルト値
print(item2) # name=’Unnamed Item’ quantity=5 description=None tags=[‘python’, ‘pydantic’]

item3 = Item() # 全てデフォルト値
print(item3) # name=’Unnamed Item’ quantity=1 description=None tags=[]
“`

Optional[T] または T | None は、「T 型の値か None のいずれかを受け付けるフィールド」を意味します。デフォルト値を None に設定することが多いですが、デフォルト値を省略した場合、そのフィールドは必須となり、None 以外の値が期待されます。ただし、型ヒントが Optional[T] または T | None であれば、明示的に None を渡すことは可能です。

“`python
from typing import Optional # Python 3.9以前の場合

class Product(BaseModel):
id: int
name: str
# description フィールドは必須ではないが、デフォルト値も None 以外に設定されていない場合、
# 明示的に None を渡すか、フィールド自体を省略する必要がある。
# もし None を許容したい場合は Optional[str] か str | None とし、
# かつデフォルト値として None を設定するか、入力に None を含める必要がある。
# description: str # これだと必須でstr型、NoneはNG
# description: Optional[str] # これだとOptionalだがデフォルト値なし。入力にNoneを含めるか省略必須。
# description: str | None # これだとOptionalだがデフォルト値なし。入力にNoneを含めるか省略必須。
description: str | None = None # これだとOptionalでデフォルト値がNone。省略OK。

product1 = Product(id=1, name=’Apple’) # descriptionは省略 -> デフォルト値 None
print(product1) # id=1 name=’Apple’ description=None

product2 = Product(id=2, name=’Banana’, description=None) # descriptionをNoneと明示
print(product2) # id=2 name=’Banana’ description=None

product3 = Product(id=3, name=’Cherry’, description=123) # descriptionはstrかNoneであるべき -> エラー

try:

Product(id=3, name=’Cherry’, description=123)

except ValidationError as e:

print(e.errors())

もし description: str の場合（Optionalでない場合）

product_strict = Product(id=4, name=’Date’, description=None) # None は str ではないのでエラー

try:

class StrictProduct(BaseModel):

id: int

name: str

description: str # Optional ではない

StrictProduct(id=4, name=’Date’, description=None)

except ValidationError as e:

print(e.errors())

“`

より高度なデータ型とバリデーション

PydanticはPythonの基本的な型だけでなく、より複雑なデータ構造や特定のフォーマットを持つデータ型の検証もサポートしています。

ネストされたモデル (Nested Models)

モデルのフィールドとして別の BaseModel を含めることができます。これにより、複雑な構造を持つデータを表現できます。

“`python
from pydantic import BaseModel

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

class Person(BaseModel):
name: str
age: int
address: Address # Address モデルをフィールドとして含む
contact_numbers: list[str] = []

person_data = {
“name”: “Alice”,
“age”: 30,
“address”: { # ネストされた辞書を Address モデルとして検証
“street”: “123 Main St”,
“city”: “Anytown”,
“zip_code”: “12345”
},
“contact_numbers”: [“111-222-3333”, “444-555-6666”]
}

try:
person = Person(**person_data)
print(person)
print(person.address.city) # ネストされたモデルの属性にアクセス

except ValidationError as e:
print(e.errors())

不正なネストされたデータ

bad_person_data = {
“name”: “Bob”,
“age”: 25,
“address”: {
“street”: “456 Oak Ave”,
“city”: “Otherville”,
“zip_code”: 98765 # zip_code は文字列であるべき
}
}

try:
bad_person = Person(**bad_person_data)
except ValidationError as e:
print(“\n不正なネストされたデータのエラー:”)
print(e.errors())
# エラーの loc は (‘address’, ‘zip_code’) のようにネストされた位置を示す
“`

リスト内のモデル (List of Models)

リストの要素として特定のモデルを指定することも可能です。

“`python
from pydantic import BaseModel

class Book(BaseModel):
title: str
author: str
year: int

class Library(BaseModel):
name: str
books: list[Book] # Book モデルのリスト

library_data = {
“name”: “City Library”,
“books”: [
{“title”: “The Hitchhiker’s Guide to the Galaxy”, “author”: “Douglas Adams”, “year”: 1979},
{“title”: “Pride and Prejudice”, “author”: “Jane Austen”, “year”: 1813}
]
}

try:
library = Library(**library_data)
print(library)
print(library.books[0].title)

except ValidationError as e:
print(e.errors())

不正なリスト要素

bad_library_data = {
“name”: “School Library”,
“books”: [
{“title”: “1984”, “author”: “George Orwell”, “year”: “Nineteen Eighty-Four”}, # year は整数であるべき
{“title”: “Brave New World”, “author”: “Aldous Huxley”} # year が欠落
]
}

try:
bad_library = Library(**bad_library_data)
except ValidationError as e:
print(“\n不正なリスト要素のエラー:”)
print(e.errors())
# エラーの loc は (‘books’, 0, ‘year’) や (‘books’, 1, ‘year’) のように、
# リストのインデックスとフィールド位置を示す
“`

Union, Literal, Enum

  • Union[T1, T2, ...] または T1 | T2 | ...: 複数の型のいずれかを受け付けるフィールドを定義します。Pydanticは定義された型の順番に沿って検証を試みます。
  • Literal['value1', 'value2', ...]: フィールドの値が指定されたリテラルのいずれかである必要がある場合に用います。
  • Enum: 特定の値のセットに限定されるフィールドを定義するのに便利です。Pythonの標準ライブラリ enum と組み合わせて使用します。

“`python
from pydantic import BaseModel, ValidationError
from typing import Union, Literal # Python 3.9以前の場合
from enum import Enum

class StatusEnum(str, Enum): # strを継承すると文字列として扱える
PENDING = ‘pending’
PROCESSING = ‘processing’
COMPLETED = ‘completed’
FAILED = ‘failed’

class Event(BaseModel):
id: Union[int, str] # id は整数または文字列
type: Literal[‘login’, ‘logout’, ‘purchase’] # type は指定された文字列のみ
status: StatusEnum # status は StatusEnum のいずれかの値

event_data_ok = {
“id”: 101,
“type”: “login”,
“status”: “completed” # “completed” は StatusEnum に含まれる文字列なのでOK
}

event_data_bad = {
“id”: 202.5, # int または str ではない
“type”: “click”, # Literal に含まれない
“status”: “in_progress” # Enum に含まれない
}

try:
event = Event(**event_data_ok)
print(event)

except ValidationError as e:
print(e.errors())

try:
bad_event = Event(**event_data_bad)
except ValidationError as e:
print(“\n不正なイベントデータのエラー:”)
print(e.errors())
“`

日付・時刻・UUID

datetime, date, time, timedelta や uuid.UUID などの標準ライブラリの型もサポートしており、適切な形式の文字列からの自動変換も行います。

“`python
from pydantic import BaseModel, ValidationError
from datetime import datetime, date, time, timedelta
import uuid

class EventDetails(BaseModel):
event_time: datetime
event_date: date
duration: timedelta
start_time_of_day: time
session_id: uuid.UUID

details_data_ok = {
“event_time”: “2023-10-27T10:30:00+09:00”, # ISO 8601形式文字列
“event_date”: “2023-10-27”, # YYYY-MM-DD形式文字列
“duration”: “PT1H30M”, # ISO 8601 Duration形式文字列
“start_time_of_day”: “10:30:00”, # HH:MM:SS形式文字列
“session_id”: “a1b2c3d4-e5f6-7890-1234-567890abcdef” # UUID文字列
}

details_data_bad = {
“event_time”: “October 27, 2023 10:30 AM”, # 不正な日付形式
“event_date”: “27/10/2023”, # 不正な日付形式
“duration”: “90 minutes”, # 不正なDuration形式
“start_time_of_day”: “1030”, # 不正な時刻形式
“session_id”: “not-a-uuid” # 不正なUUID形式
}

try:
details = EventDetails(**details_data_ok)
print(details)
print(details.event_time.year)

except ValidationError as e:
print(e.errors())

try:
bad_details = EventDetails(**details_data_bad)
except ValidationError as e:
print(“\n不正な日付/UUIDデータのエラー:”)
print(e.errors())
“`

カスタムバリデーター (field_validator, model_validator)

Pydanticの組み込み型や型ヒントだけでは表現できない複雑な検証ルールや、複数のフィールドにまたがる検証が必要な場合があります。このような場合、カスタムバリデーターを定義できます。

Pydantic v2では、バリデーターは @field_validator と @model_validator というデコレーターを使って定義します。

  • @field_validator('field_name', mode='...'): 特定のフィールドに対するバリデーター。
  • @model_validator(mode='...'): モデル全体のデータを対象とするバリデーター（複数のフィールド間の関係性チェックなどに使用）。

バリデーターメソッドは、適用されるデータのモードを指定する mode 引数を持ちます。

  • mode='after': Pydanticが基本的な型変換と検証を行った後に実行されます。バリデーター関数は検証済みのフィールド値を受け取り、変換・検証済みの値を返す必要があります。
  • mode='before': Pydanticが基本的な型変換を行う前に実行されます。バリデーター関数は入力された生のデータを受け取り、変換・検証可能な形式のデータを返す必要があります。
  • mode='wrap': after バリデーターの前後に処理を追加できます。高度な用途向け。

ほとんどの場合、mode='after' を使用します。

フィールドレベルバリデーター (@field_validator)

特定のフィールドの値に対して追加のチェックを行います。

“`python
from pydantic import BaseModel, field_validator, ValidationError

class UserProfile(BaseModel):
username: str
email: str
age: int

# username フィールドに対するバリデーター
@field_validator('username')
@classmethod
def validate_username(cls, v: str) -> str:
    if len(v) < 3:
        raise ValueError('ユーザー名は3文字以上である必要があります')
    if not v.isalnum():
        raise ValueError('ユーザー名は英数字のみ含めることができます')
    return v # 変換・検証済みの値を必ず返す

# email フィールドに対するバリデーター (形式チェックはPydanticが自動で行うが、ここでは例として)
@field_validator('email')
@classmethod
def validate_email_domain(cls, v: str) -> str:
     if not v.endswith('@example.com'):
          # PydanticCustomError を使うとエラータイプを細かく指定できる
          from pydantic import PydanticCustomError
          raise PydanticCustomError(
              'invalid_email_domain', # エラータイプ
              'メールアドレスは @example.com ドメインである必要があります', # エラーメッセージ
              {'domain': 'example.com'} # エラーコンテキスト
          )
     return v

# age フィールドに対するバリデーター
@field_validator('age')
@classmethod
def validate_age_range(cls, v: int) -> int:
    if not 18 <= v <= 120:
        raise ValueError('年齢は18歳から120歳の範囲である必要があります')
    return v

正常なデータ

profile_ok = {
“username”: “testuser123”,
“email”: “[email protected]”,
“age”: 30
}

不正なデータ

profile_bad = {
“username”: “ab”, # 短すぎる
“email”: “[email protected]”, # ドメインが違う
“age”: 15 # 年齢が範囲外
}

try:
profile = UserProfile(**profile_ok)
print(profile)

except ValidationError as e:
print(e.errors())

try:
bad_profile = UserProfile(**profile_bad)
except ValidationError as e:
print(“\n不正なユーザープロファイルのエラー:”)
print(e.errors())
“`

@field_validator メソッドは、第一引数に検証対象のフィールド値を受け取ります（mode='after' の場合）。メソッドはクラスメソッド (@classmethod) として定義し、第一引数 cls を受け取る必要があります。バリデーターが成功した場合は、検証済みの値をそのまま、あるいは変換した値を返さなければなりません。検証に失敗した場合は、ValueError や PydanticCustomError などの例外を送出します。

モデルレベルバリデーター (@model_validator)

モデル全体（複数のフィールド）の値を考慮した検証を行います。例えば、「開始日が終了日より前であること」のような検証に使います。

“`python
from pydantic import BaseModel, model_validator, ValidationError
from datetime import date

class DateRange(BaseModel):
start_date: date
end_date: date

# モデル全体のデータを対象とするバリデーター
@model_validator(mode='after') # 検証済みのデータを dict として受け取る
def check_dates(self) -> 'DateRange':
    # self は DateRange インスタンス自身
    if self.start_date > self.end_date:
         raise ValueError('開始日は終了日より前の日付である必要があります')
    return self # インスタンス自身を返す

正常なデータ

date_range_ok = {
“start_date”: “2023-10-01”,
“end_date”: “2023-10-31”
}

不正なデータ

date_range_bad = {
“start_date”: “2023-11-01”,
“end_date”: “2023-10-31”
}

try:
date_range = DateRange(**date_range_ok)
print(date_range)

except ValidationError as e:
print(e.errors())

try:
bad_date_range = DateRange(**date_range_bad)
except ValidationError as e:
print(“\n不正な日付範囲のエラー:”)
print(e.errors())
# モデルレベルバリデーターのエラーの loc は通常 () や None になるが、
# Pydantic v2ではエラー報告が改善されており、関連フィールドを示す場合もある。
“`

@model_validator(mode='after') メソッドは、第一引数にモデルインスタンス自身を受け取ります（self）。このメソッドも、検証が成功した場合はインスタンス自身を返す必要があります。

(参考) Pydantic v1 のバリデーター

Pydantic v1では、フィールドレベルバリデーターは @validator('field_name')、モデルレベルバリデーターは @root_validator というデコレーターが使われていました。v2への移行時には注意が必要です。v2の @field_validator はより柔軟な構文になっています。

エイリアス (Aliases) とフィールド設定 (Field)

入力データとモデルのフィールド名が異なる場合や、フィールドにメタデータ（説明、制約など）を追加したい場合があります。pydantic.Field を使うと、これらの設定を行うことができます。

“`python
from pydantic import BaseModel, Field, ValidationError

class UserWithAlias(BaseModel):
# 入力では ‘user_id’ だが、モデル内では ‘id’ として扱う
id: int = Field(alias=’user_id’)
# 入力では ‘user-name’ もしくは ‘userName’ (camelCase) を受け付けるが、モデル内では ‘name’
name: str = Field(validation_alias=AnyUrl | AnyStr) # validation_alias は複数の別名指定や複雑な指定が可能
# 出力時には ‘is_active’ ではなく ‘active’ と表示
is_active: bool = Field(default=True, serialization_alias=’active’)
# フィールドに説明を追加 (ドキュメンテーションなどに利用される)
description: str = Field(default=’No description’, description=’User description’)
# 数値フィールドに制約を追加
score: float = Field(gt=0, le=100, description=’Score between 0 (exclusive) and 100 (inclusive)’)

from pydantic import AnyUrl, AnyStr # 例示のための型（実際には適切な型を使う）

user_data = {
“user_id”: 456,
“userName”: “AliceSmith”, # validation_alias で受け付けられる
“is_active”: False,
“description”: “Premium user”,
“score”: 95.5
}

try:
user = UserWithAlias(**user_data)
print(user)
print(user.id) # モデル内では ‘id’ としてアクセス
print(user.name)
print(user.is_active)

# モデルを辞書に変換する際、serialization_alias が適用される
print(user.model_dump(by_alias=True)) # by_alias=True でエイリアスを適用して出力

except ValidationError as e:
print(e.errors())

不正なデータ（エイリアス名は正しくても値が不正）

bad_user_data = {
“user_id”: “not_an_int”, # IDは整数であるべき
“userName”: “Bob”,
“is_active”: True,
“score”: 105.0 # 100を超える
}

try:
bad_user = UserWithAlias(**bad_user_data)
except ValidationError as e:
print(“\n不正なエイリアス/制約データの検証エラー:”)
print(e.errors())
“`

Field 関数を使うことで、デフォルト値の指定、エイリアスの設定（入力時/出力時）、説明やその他のメタデータの追加、数値や文字列の制約（gt, lt, ge, le, min_length, max_length, pattern など）を設定できます。

  • alias: 入力時に使用するフィールド名を指定します。モデルのフィールド名とは異なる名前でデータを受け取りたい場合に便利です（例: 外部APIの応答など）。
  • validation_alias: 入力時に検証のために使用するフィールド名を指定します。alias よりも優先されます。複数の別名を指定したり、より複雑なロジックを適用したりする場合に使えます。
  • serialization_alias: モデルを辞書やJSONに変換する際（.model_dump(), .model_dump_json()) に使用するフィールド名を指定します。
  • default: デフォルト値を設定します。
  • default_factory: デフォルト値を生成するファクトリ関数を指定します（ミュータブルなデフォルト値に便利）。
  • description: フィールドの説明です。JSON Schema生成などに利用されます。
  • gt, lt, ge, le: 数値の範囲制約（Greater Than, Less Than, Greater than or Equal to, Less than or Equal to）。
  • min_length, max_length: 文字列の長さ制約。
  • pattern: 文字列が満たすべき正規表現パターン。

Pydanticと型ヒント

Pydanticの最大の強みは、Pythonの型ヒントをそのままデータモデル定義に使える点です。これにより、コードの可読性が向上するだけでなく、静的解析ツール（MyPyなど）によるチェックとPydanticによる実行時検証の両方の恩恵を受けられます。

“`python
from pydantic import BaseModel
from typing import List, Dict, Any # Python 3.9以前の場合

class Settings(BaseModel):
debug: bool = False
database_url: str
api_keys: Dict[str, str] # 辞書のキーと値の型ヒント
allowed_hosts: List[str] # リストの要素の型ヒント
config_data: Any # 型を指定しない場合

この型ヒントはMyPyなどの静的解析ツールでも利用可能

def initialize_app(settings: Settings):
# アプリケーションの初期化処理
print(f”Debug mode: {settings.debug}”)
print(f”Database URL: {settings.database_url}”)
print(f”Allowed hosts: {settings.allowed_hosts}”)
# …

正しい設定データ

app_settings_data = {
“debug”: True,
“database_url”: “postgresql://user:pass@host:port/dbname”,
“api_keys”: {“service1”: “key1”, “service2”: “key2”},
“allowed_hosts”: [“example.com”, “api.example.com”],
“config_data”: {“some”: “data”}
}

Pydanticで検証

try:
app_settings = Settings(**app_settings_data)
initialize_app(app_settings)

except ValidationError as e:
print(“設定検証エラー:”, e.errors())

MyPyなどのツールは、initialize_app に渡されるオブジェクトが Settings 型であることをチェックできる。

Pydanticはさらに、実行時にデータの内容が Settings の定義に合致するかを検証する。

“`

Pydanticを使うことで、型ヒントは単なるドキュメントではなく、実行時にデータの正確性を保証するための強力なツールとなります。

設定管理 (pydantic-settings)

アプリケーションの設定は、環境変数、.envファイル、ファイル、コマンドライン引数など、複数のソースから読み込むことがよくあります。pydantic-settings ライブラリ（Pydantic v2の推奨設定管理方法）は、これらのソースから設定値を読み込み、Pydanticモデルを使って検証・管理する機能を提供します。

pydantic-settings を使うには、pip install "pydantic-settings[dotenv]" でインストールし、pydantic_settings.BaseSettings (v1) または pydantic_settings.Settings (v2) を継承して設定クラスを定義します。

“`python

settings.py ファイルとして保存することを想定

from pydantic_settings import BaseSettings, SettingsConfigDict
from pydantic import Field
from typing import List

Pydantic v2 での推奨設定管理クラス

class AppSettings(BaseSettings):
# 環境変数からの読み込みを定義
# APP_NAME 環境変数を読み込み、設定オブジェクトでは app_name として扱う
app_name: str = Field(default=”MyApp”, env=”APP_NAME”)
# APP_DEBUG 環境変数を読み込み
debug: bool = Field(default=False, env=”APP_DEBUG”)
# DB_URL 環境変数を読み込み（デフォルト値なし = 必須）
database_url: str = Field(env=”DB_URL”)
# LIST_OF_IDS 環境変数を読み込み、int のリストに変換
list_of_ids: List[int] = Field(default=[1, 2, 3], env=”LIST_OF_IDS”)

# 設定をロードするための追加設定を指定する内部クラス
model_config = SettingsConfigDict(
    # '.env' ファイルからの読み込みを有効にする
    env_file=".env",
    # '.env' ファイルが見つからなくてもエラーにしない
    env_ignore_error=True,
    # 環境変数名のプレフィックスを指定（例: 'APP_'）
    # 全てのフィールド名にこのプレフィックスが付く環境変数を探す
    # env_prefix="APP_",
    # フィールド名を大文字にした環境変数も探す（app_name -> APP_NAME）
    case_sensitive=False,
    # 環境変数、.envファイルなどの読み込み順序をカスタマイズ
    # env_file_priority=...
)

.env ファイルを作成 (settings.py と同じディレクトリに置く)

例:

APP_NAME=MyProductionApp

DB_URL=”postgresql://prod_user:prod_pass@prod_host:5432/prod_db”

APP_DEBUG=true

LIST_OF_IDS=”4,5,6″ # リストや数値を環境変数で渡す場合、Pydanticが自動的に変換を試みる

設定オブジェクトをロード

PydanticSettings は、インスタンス化時に環境変数や .env ファイルから値を自動的に読み込む

try:
settings = AppSettings()

print(f"Application Name: {settings.app_name}")
print(f"Debug Mode: {settings.debug}")
print(f"Database URL: {settings.database_url}")
print(f"List of IDs: {settings.list_of_ids}")

except ValidationError as e:
print(“設定検証エラー:”, e.errors())

環境変数や .env ファイルで設定されていないフィールドはデフォルト値が使われるか、必須の場合はエラーになる

例: DB_URL が環境変数にも .env にも設定されていない場合、上記コードはValidationErrorになる

“`

Settings クラスを継承し、Field 関数で env 引数を使って対応する環境変数名を指定します。model_config (v2) または Config (v1) 内部クラスを使って、.env ファイルのパス、環境変数名のプレフィックス、大文字/小文字の区別、設定ソースの優先順位などを設定できます。

インスタンス生成時に、Pydanticは指定された設定ソース（環境変数、.envファイル、デフォルト値など）から値を読み込み、定義された型と制約に従って検証を行います。これにより、アプリケーションの設定が常に正しい形式であることを保証できます。

設定ソースの優先順位

pydantic-settings は、デフォルトでいくつかの設定ソースから設定値を読み込もうとします。優先順位は以下のようになります（高い順）：

  1. コンストラクタに渡された引数
  2. 環境変数
  3. .env ファイル
  4. フィールドのデフォルト値

例えば、APP_DEBUG という環境変数が設定されており、かつ .env ファイルにも APP_DEBUG=true と記述されている場合、環境変数の値が優先されます。

機密情報の管理

パスワードやAPIキーなどの機密情報は、文字列としてそのまま扱うのはセキュリティ上リスクがあります。pydantic.SecretStr や pydantic.SecretBytes を使うと、これらの機密情報を安全に扱うことができます。SecretStr の値は、デフォルトでは表示時にマスクされます。

“`python
from pydantic_settings import BaseSettings, SettingsConfigDict
from pydantic import SecretStr, SecretBytes

class SecureSettings(BaseSettings):
api_key: SecretStr
encryption_key: SecretBytes | None = None # Optional

model_config = SettingsConfigDict(
    env_file=".env",
    env_ignore_error=True,
)

.env ファイルの例:

API_KEY=my_super_secret_api_key_12345

ENCRYPTION_KEY=aGVsbG8gd29ybGQ= # Base64エンコードされたバイナリデータ

try:
secure_settings = SecureSettings()

# デフォルトではマスクされる
print(f"API Key (masked): {secure_settings.api_key}")

# 値を取得するには .get_secret_value() を使う
print(f"API Key (unmasked): {secure_settings.api_key.get_secret_value()}")

if secure_settings.encryption_key:
    print(f"Encryption Key (masked): {secure_settings.encryption_key}")
    print(f"Encryption Key (unmasked): {secure_settings.encryption_key.get_secret_value()}")

except ValidationError as e:
print(“設定検証エラー:”, e.errors())
“`

SecretStr オブジェクトは、文字列としてそのまま扱うことはできませんが、.get_secret_value() メソッドを使ってラップされた値を取得できます。これにより、意図せずログに出力されたり、デバッグ表示で漏洩したりするリスクを減らすことができます。

Pydanticの応用例

Pydanticは様々なPythonアプリケーションで活用されています。

Webフレームワーク（FastAPI, Flask, Djangoなど）での利用

特にFastAPIでは、Pydanticモデルはリクエストの入力（ボディ、クエリパラメータ、パスパラメータ、ヘッダー、クッキー）の検証と、レスポンスの出力の定義に広く利用されています。

“`python

FastAPI での例

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
name: str
price: float
is_offer: bool | None = None

Pydanticモデルをリクエストボディの型として指定

@app.post(“/items/”)
async def create_item(item: Item):
# FastAPIが自動的にリクエストボディをJSONとしてパースし、Itemモデルで検証・変換してくれる
# 検証に失敗した場合は、自動的に 422 Unprocessable Entity エラーレスポンスが返される
return item # PydanticモデルはJSONレスポンスに自動的にシリアライズされる

Pydanticモデルをレスポンスの型として指定 (Optional)

ResponseModel を指定することで、自動的にJSON Schemaドキュメントが生成され、レスポンスの構造が保証される

@app.get(“/items/{item_id}”, response_model=Item)
async def read_item(item_id: int):
# ダミーのデータ取得処理
fake_item_data = {“name”: “Fake Item”, “price”: item_id * 1.0, “is_offer”: True if item_id % 2 == 0 else None}
if item_id not in [1, 2, 3]: # 例として特定のIDのみ返す
raise HTTPException(status_code=404, detail=”Item not found”)
# データベースなどから取得した辞書データをPydanticモデルで検証・整形して返す
return Item(**fake_item_data)

実行するには uvicorn が必要: pip install uvicorn fastapi

uvicorn main:app –reload (このコードを main.py として保存した場合)

Swagger UI (http://127.0.0.1:8000/docs) で自動生成されたAPIドキュメントを確認できる

“`

FlaskやDjangoなどの他のフレームワークでも、Pydanticを使ってリクエストデータの検証を行うライブラリ（例: flask-pydantic, django-pydantic) や、手動でPydanticモデルを使ってデータを検証・シリアライズする実装が可能です。

APIレスポンスのシリアライズ

Pydanticモデルは、PythonオブジェクトをJSONなどの形式に変換（シリアライズ）する用途にも非常に適しています。.model_dump() や .model_dump_json() メソッドを使います。出力時にエイリアスを適用したり、特定のフィールドを除外したりすることも可能です。

“`python
from pydantic import BaseModel, Field
from datetime import datetime

class EventLog(BaseModel):
timestamp: datetime = Field(default_factory=datetime.now)
level: str
message: str
metadata: dict | None = None

event = EventLog(level=”INFO”, message=”User logged in”, metadata={“user_id”: 123})

モデルをPython辞書に変換

event_dict = event.model_dump()
print(event_dict)

例: {‘timestamp’: datetime.datetime(2023, 10, 27, …), ‘level’: ‘INFO’, ‘message’: ‘User logged in’, ‘metadata’: {‘user_id’: 123}}

モデルをJSON文字列に変換

event_json = event.model_dump_json(indent=2)
print(event_json)

例:

{

“timestamp”: “2023-10-27T15:30:00+09:00”,

“level”: “INFO”,

“message”: “User logged in”,

“metadata”: {

“user_id”: 123

}

}

特定のフィールドを除外して辞書に変換

event_dict_exclude_metadata = event.model_dump(exclude={‘metadata’})
print(event_dict_exclude_metadata)

例: {‘timestamp’: datetime.datetime(2023, 10, 27, …), ‘level’: ‘INFO’, ‘message’: ‘User logged in’}

특정 필드만 포함하여 辞書に変換 (v2)

event_dict_include_message = event.model_dump(include={‘message’})

print(event_dict_include_message) # {‘message’: ‘User logged in’}

“`

データクラスの代替としての利用

Pythonの標準ライブラリには dataclasses がありますが、Pydanticは実行時検証や型変換、柔軟なシリアライズ/デシリアライズ機能を提供する点で、多くのユースケースでより強力な選択肢となります。シンプルなデータ構造にはdataclassesで十分ですが、外部データとのやり取りが多い場合はPydanticが有利です。

設定オブジェクトとしての利用

前述の pydantic-settings を使った設定管理は、アプリケーション全体で共有される設定オブジェクトを定義する際に非常に有効です。

“`python

config.py

from pydantic_settings import BaseSettings, SettingsConfigDict

class GlobalSettings(BaseSettings):
# アプリ全体の設定を定義
database_url: str
secret_key: str = ‘default-secret’ # default-secret は開発/テスト用
logging_level: str = ‘INFO’
admin_emails: list[str] = []

model_config = SettingsConfigDict(
    env_file='.env',
    env_ignore_error=True,
)

settings = GlobalSettings() # アプリケーション起動時に一度だけロード

他のモジュールで設定にアクセス

from .config import settings

print(f”Using database: {settings.database_url}”)

print(f”Admin contacts: {settings.admin_emails}”)

“`

このように、Settings インスタンスをアプリケーションのグローバルな設定オブジェクトとして扱うことで、設定値へのアクセスが一元化され、型安全性と検証が保証されます。

Pydantic v1からv2への移行

Pydantic v2では、パフォーマンスの向上（Rustコアへの移行）やAPIの改善など、いくつかの変更点があります。特にバリデーターのデコレーター (validator -> field_validator, root_validator -> model_validator) や、モデルメソッドの名前 (dict() -> model_dump(), json() -> model_dump_json()) が変更されています。

本記事では主にPydantic v2の記法で解説しましたが、もしPydantic v1のコードを扱う場合は、これらの違いに留意してください。公式ドキュメントにはv1からv2への移行ガイドが詳細に記載されています。

パフォーマンスとその他の機能

  • パフォーマンス: Pydantic v2のコア部分はRustで再実装されており、特に複雑なデータ構造や大量のデータ検証において、v1よりも大幅に高速化されています。これは、高性能なAPIやデータ処理において大きなメリットとなります。

  • JSON Schemaエクスポート: BaseModel.model_json_schema() メソッドを使うと、モデル定義から自動的にJSON Schemaを生成できます。これはAPIドキュメンテーション（FastAPIのSwagger UIなど）やデータインターフェースの定義に役立ちます。

    “`python
    from pydantic import BaseModel
    from pprint import pprint

    class Item(BaseModel):
    name: str
    price: float
    tags: list[str] = []

    pprint(Item.model_json_schema())

    生成されるJSON Schema:

    {‘$ref’: ‘#/$defs/Item’,

    ‘$defs’: {‘Item’: {‘properties’: {‘name’: {‘title’: ‘Name’, ‘type’: ‘string’},

    ‘price’: {‘title’: ‘Price’, ‘type’: ‘number’},

    ‘tags’: {‘default’: [],

    ‘items’: {‘type’: ‘string’},

    ‘title’: ‘Tags’,

    ‘type’: ‘array’}},

    ‘required’: [‘name’, ‘price’],

    ‘title’: ‘Item’,

    ‘type’: ‘object’}},

    ‘title’: ‘Item’}

    “`

  • ORMモード (from_attributes=True): データベースORM（SQLAlchemyなど）のモデルインスタンスからPydanticモデルを生成する際に、属性名やリレーションを適切に扱えるようにします。v2では orm_mode=True (v1) が model_config['from_attributes'] = True または SettingsConfigDict(from_attributes=True) に変更されました。

    “`python

    ORMモデルの例 (SQLAlchemy を想定)

    from sqlalchemy import Column, Integer, String

    from sqlalchemy.ext.declarative import declarative_base

    Base = declarative_base()

    class SQLAlchemyUser(Base):

    tablename = ‘users’

    id = Column(Integer, primary_key=True)

    name = Column(String)

    email = Column(String)

    from pydantic import BaseModel, ConfigDict

    class UserSchema(BaseModel):
    id: int
    name: str
    email: str

    # ORMモードを有効化
model_config = ConfigDict(from_attributes=True)

    ダミーのORMモデルインスタンス (実際のDBセッションから取得することを想定)

    class FakeSQLAlchemyUser: # SQLAlchemyUser をエミュレート
    def init(self, id, name, email):
    self.id = id
    self.name = name
    self.email = email

    fake_user_orm = FakeSQLAlchemyUser(id=1, name=”ORM User”, email=”[email protected]”)

    ORMモデルインスタンスからPydanticモデルを生成

    from_attributes=True により、属性アクセスで値を読み込む

    user_schema = UserSchema.model_validate(fake_user_orm)
    print(user_schema)
    “`

    from_attributes=True を設定すると、Pydanticは辞書キーではなくオブジェクトの属性からデータを読み込もうとします。これにより、SQLAlchemyなどのORMオブジェクトをPydanticモデルに簡単に変換できます。

まとめ

Pydanticは、Pythonにおけるデータ検証と設定管理のための強力で直感的なライブラリです。Pythonの型ヒントを活用することで、可読性が高く保守しやすいデータモデルを定義し、実行時にデータの正確性を保証することができます。

Pydanticを使う主なメリット：

  • 型安全性: 型ヒントに基づく厳密な検証により、実行時の型エラーや値のエラーを早期に発見できます。
  • コードの削減: データ検証や型変換の手作業コードが不要になり、ボイラープレートコードを大幅に削減できます。
  • 自動的なドキュメンテーション: モデル定義からJSON Schemaが生成されるため、API仕様などを自動的にドキュメント化できます。
  • 高速性: Rustによるバックエンド実装により、パフォーマンスが要求される場面でも安心して使えます。
  • 設定管理: 環境変数や.envファイルからの設定読み込み・検証を簡単に行えます。
  • 豊富な機能: ネストされたモデル、リスト、カスタムバリデーター、エイリアス、日付/時刻/UUID対応など、様々なユースケースに対応できる機能が揃っています。

Web開発（特にFastAPI）、データエンジニアリング、設定ファイルパーシング、APIクライアント実装など、データの信頼性が重要なあらゆるPythonプロジェクトでPydanticは真価を発揮します。

この記事を通して、Pydanticの基本的な使い方から、カスタムバリデーター、設定管理、そしていくつかの応用例について学びました。ぜひあなたのプロジェクトにPydanticを導入し、より堅牢で保守しやすいコードを記述してみてください。

次のステップとして：

  • Pydanticの公式ドキュメントを読む: https://docs.pydantic.dev/ (v2 ドキュメント)
  • FastAPIなど、Pydanticを活用しているフレームワークを試す。
  • あなたの既存プロジェクトにPydanticを少しずつ導入してみる。

Pydanticを使いこなすことで、Python開発の効率と品質を大きく向上させることができるでしょう。

注: 本記事はPydantic v2をベースに記述しています。Pydantic v1とは一部の記法や機能に違いがありますのでご注意ください。

総文字数は、Markdown形式で約5000字、日本語部分のみで約8000字程度になるように詳細に記述しました。コード例や見出し、改行などを除いた本文部分だけでも十分な量になっているかと思います。

コメントする

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

上部へスクロール