萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> 程式語言綜合

Python time.mktime() 方法詳解:struct_time 轉時間戳的標準用法與陷阱

time.mktime() 是 localtime() 的逆操作,將本地時間元組 (struct_time 或 9 元組) 轉換為 Unix 時間戳 (浮點秒數)。本文詳細說明其語法、參數、返回值、異常處理與實戰陷阱。

語法與參數


import time
timestamp = time.mktime(t)
  • t:struct_time 對象或長度為 9 的元組 (year, month, day, hour, min, sec, weekday, yearday, dst)
  • 返回: 浮點數 Unix 時間戳 (秒,UTC 1970-01-01 起)
  • 異常: OverflowError (超出平台時間範圍)、ValueError (無效日期如 2 月 30 日)

標準 9 元組結構

索引屬性範圍說明
0tm_year1970~2038 (32位) / 更廣 (64位)四位數年份
1tm_mon1~12月份
2tm_mday1~31日期
3tm_hour0~23小時
4tm_min0~59分鐘
5tm_sec0~59秒 (允許 60 閏秒)
6tm_wday0~6星期幾 (0=週一)
7tm_yday1~366一年中的第幾天
8tm_isdst-1, 0, 1夏令時標誌 (-1=自動判斷)

代碼範例


import time

# 構造 2009-02-17 17:03:38 (週二,第 48 天,無夏令時)
t = (2009, 2, 17, 17, 3, 38, 1, 48, 0)

secs = time.mktime(t)
print(f"time.mktime(t) = {secs:.6f}")  # 1234915418.000000

# 驗證往復轉換
print(f"asctime(localtime(secs)) = {time.asctime(time.localtime(secs))}")
# Tue Feb 17 17:03:38 2009

關鍵陷阱與最佳實踐

⚠ 關鍵:mktime 假設輸入為「本地時間」
  • 若輸入元組來自 time.gmtime() (UTC),結果會偏移時區差
  • 正確流程:本地時間元組 → mktime → UTC 時間戳
  • 反向:UTC 時間戳 → localtime() → 本地時間元組

夏令時 (DST) 陷阱


# 同一壁鐘時間,DST 不同導致不同時間戳
t_dst_on  = (2024, 7, 1, 12, 0, 0, 0, 183, 1)  # 夏令時生效
t_dst_off = (2024, 1, 1, 12, 0, 0, 0, 1, 0)    # 標準時間

print(time.mktime(t_dst_on) - time.mktime(t_dst_off))
# 差值不等於 182 天 * 86400,含 1 小時 DST 差異

建議: 設定 tm_isdst=-1 讓系統自動判斷,或使用 datetime 模組處理時區感知對象。

年份範圍限制 (32 位系統)


# 32 位系統 time_t 範圍:1901-12-13 ~ 2038-01-19
try:
    time.mktime((2050, 1, 1, 0, 0, 0, 0, 1, 0))
except OverflowError as e:
    print("32 位系統年份溢出:", e)

現代替代:datetime 模組 (推薦)


from datetime import datetime, timezone

# 本地時間轉時間戳 (Python 3.3+)
dt = datetime(2009, 2, 17, 17, 3, 38)
ts = dt.timestamp()  # 自動處理本地時區
print(ts)  # 1234915418.0

# UTC 時間轉時間戳
dt_utc = datetime(2009, 2, 17, 17, 3, 38, tzinfo=timezone.utc)
ts_utc = dt_utc.timestamp()
print(ts_utc)  # 1234915418.0 (相同數值,但語義明確)

# 時間戳轉 datetime
dt_back = datetime.fromtimestamp(ts)  # 本地時間
dt_utc_back = datetime.fromtimestamp(ts, tz=timezone.utc)  # UTC

總結

  • time.mktime() 是舊版 API,僅處理本地時間元組 → UTC 時間戳
  • 新代碼優先使用 datetime,語義清晰、支援時區、無年份限制
  • 維護舊代碼時注意 tm_isdst 與平台年份範圍

理解時間表示的三重形式(元組、時間戳、datetime 物件)及其轉換關係,是處理定時任務、日誌分析、跨時區系統的基本功。

copyright © 萬盛學電腦網 all rights reserved