Python でエポックを datetime に変換する

Unix エポック時刻は、UTC の 1970-01-01 00:00:00 からの経過秒数です。1606262400 のようなタイムスタンプは特定の瞬間を表します。読みやすい日付に変換するには、タイムゾーンを選ぶ必要があります。日付と時刻を表すオブジェクトが必要なら datetime を、struct_time の値が適している処理なら time を使います。

エポック秒を datetime.fromtimestamp() で変換する

Python の datetime モジュールには、タイムスタンプを受け取り、datetime オブジェクトを返す datetime.fromtimestamp() があります。既定では、実行環境のローカルタイムゾーンでタイムスタンプを解釈し、タイムゾーン情報を持たない naive な datetime を返します。UTC を表す aware な datetime を得るには、timezone.utc を渡します。

次の例を実行します。

このセクションのコードと表示されるラベルや出力は英語のままです。

from datetime import datetime, timezone

timestamp = 1606262400
utc_datetime = datetime.fromtimestamp(timestamp, timezone.utc)
print(utc_datetime)

クラスを繰り返し使う場合は、from datetime import datetime とインポートすると記述を短くでき、datetime.fromtimestamp(...) と呼び出せます。fromtimestamp() のリファレンスでは、引数とプラットフォームごとの動作を確認できます。このロケールに対応する日本語のリンク先は提供されていないため、リンク先は元の英語版のままです。システム間で時点をやり取りするときはタイムスタンプを UTC のまま保ち、アプリケーションの境界で表示用のタイムゾーンに変換します。

エポック秒を time モジュールで変換する

Python の time モジュールには、用途に応じて使える変換方法が2つあります。time.localtime() は、ホストのローカルタイムゾーンで解釈した9フィールドの struct_time を返します。time.gmtime() は、対応する UTC 基準の struct_time を返します。どちらも構造化された時刻の値であり、datetime オブジェクトではありません。

このセクションのコードと表示されるラベルや出力は英語のままです。

import time

timestamp = 1554723620
local_value = time.localtime(timestamp)
utc_value = time.gmtime(timestamp)
print("Local:", local_value)
print("UTC:", utc_value)

ローカル時刻の行はシステムのタイムゾーン設定に左右されるため、UTC の行とは時刻の各フィールドが異なることがあります。UTC のフィールドを一定にしたい場合は time.gmtime() を、ホストのローカル時刻で表したい場合は time.localtime() を使います。コード例に表示される Local: と UTC: のラベルは英語のままです。

変換した日付と時刻を書式設定する

time の値と datetime オブジェクトのどちらにも、書式設定用の strftime() があります。%Y、%m、%d、%H、%M、%S などのディレクティブは、それぞれ年、月、日、時、分、秒を表します。%d は日をゼロ埋めして表す、移植性の高い指定です。%-d は一部のプラットフォームで先頭のゼロを省きますが、どこでも使えるわけではありません。

このセクションのコードと表示されるラベルや出力は英語のままです。

import time

timestamp = 1554723620
utc_value = time.gmtime(timestamp)
print(time.strftime("%Y-%m-%d %H:%M:%S", utc_value))

同じ数値ディレクティブは datetime.strftime() でも使えます。曜日や月の名前を出力する %A や %B、ロケールに応じた形式を使う %c は、システムのロケールによって結果が変わることがあります。機械処理用のデータでは、こうした表記に依存しないでください。書式指定の一覧は strftime.org を参照してください。

UTC、タイムゾーン、ミリ秒単位のタイムスタンプを扱う

タイムスタンプは UTC のエポックからの経過秒数を表しますが、ローカル時刻への変換には実行環境で設定されたタイムゾーンが使われます。実際の時点を表す値を保存したり計算したりする場合は、タイムゾーン対応の UTC 値を使うのが適切です。別の地域で表示するには、aware な値を astimezone() で変換します。既定の datetime.fromtimestamp() が返す naive な値からはタイムゾーンを特定できません。UTC として解釈する意図が確認できない限り、UTC の値として扱わないでください。

API によっては、秒ではなくミリ秒を返します。ミリ秒単位のタイムスタンプは、現在の秒単位のタイムスタンプより通常かなり大きな値です。どちらの変換 API に渡す場合も、先に 1000 で割って秒に直してください。1秒未満の精度が必要なら、小数部分を保持します。

このセクションのコードと表示されるラベルや出力は英語のままです。

from datetime import datetime, timezone

timestamp_ms = 1606262400123
timestamp_seconds = timestamp_ms / 1000
utc_datetime = datetime.fromtimestamp(timestamp_seconds, timezone.utc)
print(utc_datetime)

変換後の値には、入力で表された小数秒も含まれます。ローカル時刻で表示するには utc_datetime.astimezone() を呼び出します。変換後の時刻はホストに設定されたタイムゾーンによって変わります。表示形式に左右されず同じ時点を保つ必要がある場合は、元の数値のタイムスタンプも保持してください。