PythonでのOptionalおよびNullable JSONフィールドの処理

PythonでのOptionalフィールド

JSONフィールドは null であったり、完全に不在であったりする場合があります。Pythonではこれを Optional[T]（typing モジュールから）または新しい T | None 構文（Python 3.10+）で表現します。

JSONの例

{
  "id": 1,
  "name": "Alice",
  "bio": null,
  "avatar_url": null,
  "phone": "555-1234"
}

生成されるPython

from dataclasses import dataclass
from typing import Optional

@dataclass
class User:
    id: int
    name: str
    bio: Optional[str]
    avatar_url: Optional[str]
    phone: Optional[str]

Optional vs Required

• 必須フィールド — 常に存在し、決して null にならない。型：str、int 等。
• Nullableフィールド — 存在するが null の可能性がある。型：Optional[str]（str | None と同義）。
• オプショナルフィールド — 完全に不在の可能性がある。型：Optional[str] でデフォルト値 None。

Python 3.10+の構文

@dataclass
class User:
    id: int
    name: str
    bio: str | None = None
    avatar_url: str | None = None
    phone: str | None = None

X | None 構文はより簡潔で、モダンなPythonでの推奨スタイルです。

実行時のNone処理

if user.bio is not None:
    print(user.bio.upper())  # 安全 — mypyはbioがstrであることを認識
else:
    print("No bio provided")

mypyなどの型チェッカーは if ブランチ内で型を絞り込み、None での AttributeError を防ぎます。

複数のJSONサンプル

コンバーターが複数のJSONサンプルを分析し、あるフィールドが存在したりしなかったりする場合、そのフィールドをデフォルト付きの Optional としてマークします：

@dataclass
class User:
    id: int
    name: str
    bio: Optional[str] = None  # 一部のサンプルで不在

ベストプラクティス

1. None が有効な値である場合にのみ Optional を使用する — 「念のため」ですべてをoptionalにしないこと。
2. JSONペイロードからフィールドが不在の可能性がある場合、デフォルト値 None を提供する。
3. 厳格なmypy設定（--strict）を使用して、処理されていない None 値を検出する。