Pydanticモデルのメソッド一覧


## **1. Pydanticモデルの概要**

### **Pydanticモデルとは？**

Pydanticモデルは、Pythonの型ヒントを利用してデータの検証や変換を行うクラスです。`BaseModel` を継承して作成されるこのモデルは、以下のような特徴を持ちます。

- **型に基づくデータ検証:** 型ヒントに基づき、入力データの正確性を保証します。
- **自動変換:** データ型が異なる場合でも、自動的に変換を試みます（例: 文字列→日時）。
- **直感的なAPI:** 使いやすいメソッドで、辞書やJSON形式との相互変換が可能です。
- **カスタムバリデーション:** フィールドごとに詳細なバリデーションロジックを実装可能です。

例えば、以下のようにモデルを定義できます:

```python
from pydantic import BaseModel
from datetime import datetime

class User(BaseModel):
    id: int
    name: str
    email: str
    created_at: datetime
```

このモデルを使うことで、安全にデータを検証し、操作することが可能になります。

## **2. Pydanticモデルの主要メソッド一覧**

### **2.1 データ操作関連のメソッド**

#### **`model_dump()`**

- **概要:** モデルを辞書形式 (`dict`) に変換します。
- **詳細:** このメソッドは、モデルのすべてのフィールドとその値を辞書形式で返します。`exclude_none=True` や `include={"field_name"}` などのオプションで、出力をカスタマイズ可能です。
- **活用ポイント:** 外部ライブラリと連携する場合や、JSON形式で保存する前のデータ処理に便利です。
- **使用例:**
  ```python
  user = User(id=1, name="Alice", email="alice@example.com", created_at="2024-01-01T10:00:00")
  user_dict = user.model_dump()
  print(user_dict)
  ```
- **出力:**
  ```json
  {"id": 1, "name": "Alice", "email": "alice@example.com", "created_at": "2024-01-01T10:00:00"}
  ```

#### **`model_dump_json()`**

- **概要:** モデルをJSON文字列に変換します。
- **詳細:** `model_dump()` と似ていますが、出力がJSON文字列形式です。APIレスポンスやファイル保存時にそのまま利用できます。
- **使用例:**
  ```python
  user_json = user.model_dump_json()
  print(user_json)
  ```
- **出力:**
  ```json
  {"id": 1, "name": "Alice", "email": "alice@example.com", "created_at": "2024-01-01T10:00:00"}
  ```

#### **`model_copy()`**

- **概要:** モデルのコピーを作成します。
- **詳細:** 元のモデルを変更せず、独立したコピーを作成します。オプション引数で特定のフィールドを上書きすることも可能です。
- **使用例:**
  ```python
  user_copy = user.model_copy()
  print(user_copy)
  ```

#### **`model_rebuild()`**

- **概要:** クラスの再構築を行います。フィールドの変更などに対応できます。
- **詳細:** 動的にモデルの構造を変更する必要がある場合に使用します。

---

### **2.2 データ検証・変換関連のメソッド**

#### **`validate()`**

- **概要:** 入力データを検証し、Pydanticモデルのインスタンスを生成します。
- **詳細:** データが正しい形式でない場合は、`ValidationError` をスローします。
- **使用例:**
  ```python
  user = User.validate({"id": 2, "name": "Bob", "email": "bob@example.com", "created_at": "2024-02-01T10:00:00"})
  print(user)
  ```

#### **`parse_obj()`**

- **概要:** 辞書型データからモデルを生成します。
- **詳細:** 主に外部から取得した辞書データをPydanticモデルに変換する際に利用します。
- **使用例:**
  ```python
  user = User.parse_obj({"id": 3, "name": "Charlie", "email": "charlie@example.com", "created_at": "2024-03-01T10:00:00"})
  ```

#### **`parse_raw()`**

- **概要:** JSON文字列からモデルを生成します。
- **詳細:** JSON形式のデータを直接モデルに変換するのに便利です。
- **使用例:**
  ```python
  user = User.parse_raw('{"id": 4, "name": "Daisy", "email": "daisy@example.com", "created_at": "2024-04-01T10:00:00"}')
  ```

#### **`parse_file()`**

- **概要:** JSONファイルからモデルを生成します。
- **詳細:** ファイルから直接データを読み込んでモデルを生成します。
- **使用例:**
  ```python
  user = User.parse_file("user.json")
  ```

#### **`construct()`**

- **概要:** データ検証をスキップしてモデルを生成します。
- **詳細:** 信頼できるデータソースからの入力を高速に処理する場合に使用します。
- **使用例:**
  ```python
  user = User.construct(id=5, name="Eve", email="eve@example.com", created_at="2024-05-01T10:00:00")
  ```

---

### **2.3 型情報関連のメソッド**

#### **`model_fields()`**

- **概要:** モデルのフィールド情報を辞書形式で取得します。
- **詳細:** 各フィールドの型、デフォルト値、追加オプションを確認できます。
- **使用例:**
  ```python
  print(User.model_fields())
  ```

#### **`model_json_schema()`**

- **概要:** モデルのJSONスキーマを取得します。
- **詳細:** API仕様やフロントエンドとの連携で、データ構造を共有する際に役立ちます。
- **使用例:**
  ```python
  print(User.model_json_schema())
  ```

---

## **3. 活用例: モデルメソッドを使った実践的なコード**


### **3.1 入力データの検証と変換**

**説明:** 外部から取得したデータを検証し、Pydanticモデルのインスタンスとして安全に取り扱います。入力データが不正な場合は、詳細なエラー情報を提供します。

```python
from pydantic import ValidationError

data = {"id": "invalid", "name": "Frank", "email": "frank@example.com", "created_at": "2024-06-01T10:00:00"}

try:
    user = User.parse_obj(data)
    print(user)
except ValidationError as e:
    print("Validation failed:", e.json())
```

**詳細:**
- `parse_obj` メソッドを使用して辞書型データを検証し、インスタンスを生成します。
- エラーが発生した場合、`ValidationError` をキャッチし、`e.json()` でエラー詳細をJSON形式で取得できます。

**出力例:**
```json
{
  "loc": ["id"],
  "msg": "value is not a valid integer",
  "type": "type_error.integer"
}
```

---

### **3.2 モデルのJSONシリアライズ**

**説明:** PydanticモデルをJSON形式に変換して、APIレスポンスやデータ保存に利用します。

```python
user = User(id=6, name="Grace", email="grace@example.com", created_at="2024-07-01T10:00:00")
user_json = user.model_dump_json()
print(user_json)
```

**詳細:**
- `model_dump_json` メソッドは、モデルの内容をJSON文字列として出力します。
- このJSON文字列は、そのままHTTPレスポンスやファイル保存に利用可能です。

**出力例:**
```json
{"id": 6, "name": "Grace", "email": "grace@example.com", "created_at": "2024-07-01T10:00:00"}
```

---

### **3.3 複数データの処理**

**説明:** モデルのリストを効率的に処理し、すべてのモデルを辞書形式に変換します。

```python
users = [
    User(id=7, name="Hank", email="hank@example.com", created_at="2024-08-01T10:00:00"),
    User(id=8, name="Ivy", email="ivy@example.com", created_at="2024-09-01T10:00:00"),
]

user_dicts = [user.model_dump() for user in users]
print(user_dicts)
```

**詳細:**
- リスト内の各Pydanticモデルに対して `model_dump` を適用し、辞書形式に変換します。
- この手法は、大量のデータを一括で処理する際に非常に有用です。

**出力例:**
```json
[
  {"id": 7, "name": "Hank", "email": "hank@example.com", "created_at": "2024-08-01T10:00:00"},
  {"id": 8, "name": "Ivy", "email": "ivy@example.com", "created_at": "2024-09-01T10:00:00"}
]
```