파이썬 자동화에서 날짜가 하루 어긋나면 먼저 시간을 더하거나 빼지 마세요. 저장은 aware UTC로 통일하고, 화면이나 리포트에서만 ZoneInfo("Asia/Seoul")로 변환하는 구조인지 확인하는 것이 출발점입니다. datetime에 시간대 정보가 없는 naive 객체가 섞였는지도 함께 봐야 합니다.
먼저 확인할 것: naive와 aware
Python 문서는 datetime을 시간대 정보가 있는 aware 객체와 그렇지 않은 naive 객체로 구분합니다. naive 값은 그 숫자가 UTC인지 서버의 현지 시간인지 값만으로 결정할 수 없습니다. 그래서 datetime.now()처럼 시간대 인자를 생략한 값이 API 응답, 로그, 보고서 계산에 들어가면 실행 환경에 따라 날짜 판단이 달라질 수 있습니다.
운영 중인 코드는 다음처럼 값의 상태부터 확인합니다.
from datetime import datetime
def describe(value: datetime) -> str:
kind = "aware" if value.tzinfo is not None and value.utcoffset() is not None else "naive"
return f"{kind}: {value.isoformat()}"
tzinfo가 있다고 해서 항상 충분한 것은 아닙니다. 실제 offset을 계산할 수 있는지까지 확인해야 합니다.
저장 기준은 UTC로 고정하기
현재 UTC 시각은 datetime.now(timezone.utc)처럼 aware 객체로 만듭니다. 이 값은 어느 서버에서 만들었는지와 관계없이 기준 시각을 분명하게 남기는 데 유리합니다.
from datetime import datetime, timezone
created_at = datetime.now(timezone.utc)
stored_value = created_at.isoformat()
여기서 중요한 점은 UTC 문자열을 한국 시간 문자열로 바꿔 저장하는 것이 아닙니다. 원본 기준 시각은 UTC로 남기고, 사용자가 읽는 단계에서 표시 시간대를 선택합니다. API 응답, 작업 로그, 데이터베이스의 저장 규칙을 이 원칙으로 맞추면 서로 다른 서버의 시간을 비교하기도 쉽습니다.
한국 시간으로 표시할 때 ZoneInfo 사용하기
ZoneInfo("Asia/Seoul")는 IANA 시간대 이름을 사용하는 객체입니다. UTC aware 값을 한국 시간으로 표현하려면 astimezone을 사용합니다. 이 메서드는 순간 자체를 바꾸지 않고 다른 시간대의 시각으로 표현합니다.
from datetime import datetime, timezone
from zoneinfo import ZoneInfo
created_at = datetime.now(timezone.utc)
seoul_time = created_at.astimezone(ZoneInfo("Asia/Seoul"))
print(seoul_time.isoformat())
날짜만 필요하다면 변환한 뒤 .date()를 호출합니다. UTC 시각의 날짜를 먼저 잘라낸 뒤 한국 날짜로 바꾸면 자정 전후에 날짜가 달라질 수 있으므로 순서를 바꾸지 않는 것이 좋습니다.
하루 어긋남을 좁히는 확인 순서
다음 순서로 로그를 남기면 단순한 시간대 혼동과 실제 데이터 오류를 구분하기 쉽습니다.
- 입력 문자열에
Z또는 시간대 offset이 있는지 확인합니다. - 파싱 직후 값이 naive인지 aware인지 출력합니다.
- 저장 직전 값의
isoformat()과 UTC 기준 값을 함께 확인합니다. - 한국 날짜가 필요한 지점에서만
astimezone(ZoneInfo("Asia/Seoul"))을 적용합니다. - 예약 실행기나 운영체제의 시간대가 코드의 기대와 같은지 별도로 확인합니다.
Windows처럼 시스템 시간대 데이터가 충분하지 않은 환경에서는 zoneinfo가 사용할 시간대 데이터가 있는지도 점검해야 합니다. Python 공식 문서는 시스템 데이터가 없을 때 tzdata를 사용할 수 있다고 설명합니다.
정리
핵심은 시간을 무작정 더하거나 빼는 것이 아니라 저장과 표시의 시간대를 분리하는 것입니다. 날짜가 어긋나면 먼저 값에 시간대 정보가 있는지 확인하고, 그다음 저장 기준과 표시 변환 지점을 나눠 보세요. 저장은 UTC, 표시는 Asia/Seoul, 날짜 추출은 변환 뒤라는 세 가지 규칙이 기본 점검선입니다.
다음 점검에서는 API가 보내는 ISO 형식의 offset과 예약 실행기가 사용하는 시간대를 함께 확인하세요.
출처: