Python JSON 実践ガイド：Datetime のシリアライズと大容量ファイルのストリーミング処理

Python の API 開発やデータ基盤では、JSON は最も一般的な交換形式です。ですが本番では、datetime、日本語を含む多言語文字列、巨大ファイルといった要件でつまずきやすくなります。

このガイドでは、実務で再利用しやすい形で次を整理します。

• • loads/dumps と load/dump の使い分け

• • datetime シリアライズの安定実装

• • ensure_ascii=False による可読な出力

• • GB級 JSON のストリーミング戦略

• • json / orjson / ujson の選定基準

---

1) loads/dumps と load/dump

• • json.dumps(obj): Python オブジェクト -> JSON 文字列

• • json.loads(text): JSON 文字列 -> Python オブジェクト

• • json.dump(obj, file): Python オブジェクト -> ファイルへ出力

• • json.load(file): ファイル -> Python オブジェクト

覚え方は、s 付きは string です。

---

2) datetime がシリアライズできない問題

よくあるエラー:

from datetime import datetime
import json

json.dumps({"now": datetime.now()})
# TypeError: Object of type datetime is not JSON serializable

実務ではエンコーダを一箇所にまとめると保守しやすくなります。

from datetime import datetime, date
import json

class DateTimeEncoder(json.JSONEncoder):
    def default(self, obj):
        if isinstance(obj, datetime):
            return obj.isoformat()
        if isinstance(obj, date):
            return obj.isoformat()
        return super().default(obj)

payload = {"now": datetime.now(), "today": date.today()}
print(json.dumps(payload, cls=DateTimeEncoder, ensure_ascii=False, indent=2))

固定フォーマットが必要なら strftime(...) に置き換えます。

---

3) \uXXXX になる理由

json.dumps() は既定で非 ASCII 文字をエスケープします。

import json
print(json.dumps({"message": "こんにちは、世界"}))
# {"message": "\u3053\u3093\u306b\u3061\u306f\u3001\u4e16\u754c"}

可読性を優先する場合:

import json
print(json.dumps({"message": "こんにちは、世界"}, ensure_ascii=False))

ファイル出力は UTF-8 指定をセットで行います。

with open("data.json", "w", encoding="utf-8") as f:
    json.dump({"message": "こんにちは、世界"}, f, ensure_ascii=False)

---

4) GB級 JSON を安全に処理する

巨大配列を json.load() で一括読み込みすると、メモリ圧迫が起きやすくなります。

A. JSON Lines（.jsonl）を優先

import json

def read_jsonl(path):
    with open(path, "r", encoding="utf-8") as f:
        for line in f:
            line = line.strip()
            if line:
                yield json.loads(line)

for obj in read_jsonl("events.jsonl"):
    pass

B. 巨大配列ドキュメントは ijson

pip install ijson

import ijson

def iter_huge_array(path):
    with open(path, "rb") as f:
        for item in ijson.items(f, "item"):
            yield item

---

5) json / orjson / ujson の使い分け

• • json（標準ライブラリ）: 互換性重視、依存追加なし

• • orjson: 高速性重視のホットパス向け

• • ujson: 置換しやすいが、境界ケースの検証は必要

orjson の最小例:

import orjson
from datetime import datetime

data = {"name": "Alice", "now": datetime.now()}
raw = orjson.dumps(data)  # bytes
obj = orjson.loads(raw)

---

6) 実務チェックリスト

1. 文字列は loads/dumps、ファイルは load/dump

1. 日時変換ポリシーをエンコーダで統一

1. 多言語プロダクトは ensure_ascii=False を基本に

1. ログ基盤は JSON Lines 形式を優先

1. シリアライザ差し替え前にベンチマークを実施

---

JSON Work の関連ツール

• • JSON バリデーター

• • JSON ビューティファイア

• • JSON to YAML

いずれもブラウザ内ローカル処理のため、入力データはサーバーに送信されません。

---

参考資料

• • Python json 公式ドキュメント

• • ijson（PyPI）

• • orjson（PyPI）