Python JSON 실전 가이드: Datetime 직렬화와 대용량 파일 스트리밍 처리

Python 백엔드와 데이터 파이프라인에서 JSON은 사실상 기본 포맷입니다. 하지만 운영 환경에서는 datetime, 비ASCII 문자, 대용량 파일 때문에 문제가 자주 발생합니다.

이 글에서는 실무에서 바로 적용 가능한 패턴을 중심으로 다음을 다룹니다.

• • loads/dumps와 load/dump의 정확한 경계

• • datetime 직렬화 오류를 안정적으로 처리하는 방법

• • ensure_ascii=False로 다국어 텍스트를 읽기 좋게 출력하는 방법

• • GB급 JSON을 메모리 폭주 없이 처리하는 스트리밍 전략

• • json, orjson, ujson의 선택 기준

---

1) loads/dumps vs 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": "\uc548\ub155\ud558\uc138\uc694, \uc138\uacc4"}

가독성을 원하면:

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. datetime 변환 정책을 인코더 하나로 통일

1. 다국어 서비스는 ensure_ascii=False 기본 적용

1. 로그/이벤트 파이프라인은 JSON Lines 우선

1. 직렬화 라이브러리 교체 전 벤치마크 수행

---

JSON Work 관련 도구

• • JSON 검증기

• • JSON 뷰티파이어

• • JSON to YAML

모든 도구는 브라우저 로컬에서 실행되며, 입력 데이터는 서버로 업로드되지 않습니다.

---

참고 자료

• • Python json 공식 문서

• • ijson (PyPI)

• • orjson (PyPI)