如何使用 datetime 模組處理日期時間？datetime 模組介紹

閱讀 17:56·字數 5382·更新 2024-4-12

本節內容不涉及 Python 日期時間與字串之間的轉換，日期時間的格式化以及時區，要了解他們，你可以檢視內容分類一段列出的章節。

datetime 模組

Python 的datetime模組擁有多個類別，比如datetime，date，time，他們提供了與日期時間相關的功能，可完成絕大部分的日期時間操作。其中，類別datetime繼承自類別date。

datetime 模組所允許的最小和最大日期時間

datetime模組的兩個變數MINYEAR和MAXYEAR，分別表示所允許的最小年份和最大年份，其中MINYEAR為1，MAXYEAR為9999。

date類別的類別變數min和max，分別表示所允許的最小日期和最大日期，其中min等價於運算式date(MINYEAR,1,1)運算得到的date物件，max等價於運算式date(MAXYEAR,12,31)運算得到的date物件。

time類別的類別變數min和max，分別表示所允許的最小時間和最大時間，其中min等價於運算式time(0,0,0,0)運算得到的time物件，max等價於運算式time(23,59,59,999999)運算得到的time物件。

datetime類別的類別變數min和max，分別表示所允許的最小日期時間和最大日期時間，其中min等價於運算式datetime(MINYEAR,1,1,tzinfo=None)運算得到的datetime物件，max等價於運算式datetime(MAXYEAR,12,31,23,59,59,999999,tzinfo=None)運算得到的datetime物件。

date|time|datetime.min date|time|datetime.max

import datetime
# 最小年份
datetime.MINYEAR
1
# 最大年份
datetime.MAXYEAR
9999
# 最小日期
datetime.date.min
datetime.date(1, 1, 1)
# 最大日期
datetime.date.max
datetime.date(9999, 12, 31)
# 最小時間
datetime.time.min
datetime.time(0, 0)
# 最大時間
datetime.time.max
datetime.time(23, 59, 59, 999999)
# 最小日期時間
datetime.datetime.min
datetime.datetime(1, 1, 1, 0, 0)
# 最大日期時間
datetime.date.max
datetime.datetime(9999, 12, 31, 23, 59, 59, 999999)

datetime 模組的 date 類別

date類別用於表示一個日期，該日期包含了年，月和日的資訊，其建構子的形式如下。如果傳遞給建構子的參數不能正確的表示一個日期，那麽建構子將擲回例外狀況ValueError。

date(year, month, day)

year 參數: year參數表示年份，其值需要大於或等於datetime模組的MINYEAR變數，並小於或等於datetime模組的MAXYEAR變數。
month 參數: month參數表示月份，其值需要大於或等於1，並小於或等於12。
day 參數: day參數表示datetime物件對應的日期是月份中的第幾天，其值需要大於或等於1，並小於或等於月份允許的最大天數。

from datetime import date
# 建立 date 物件
date(9999, 1, 1)
datetime.date(9999, 1, 1)
# day 參數不正確
date(9999, 1, 100)
…
ValueError: day is out of range for month

datetime 模組的 time 類別

time類別用於表示一天中的某個特定時間，該時間包含了小時，分，秒，微秒等資訊，其建構子的形式如下。如果傳遞給建構子的參數不能正確的表示一個時間，那麽建構子將擲回例外狀況ValueError。

time(hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)

hour 參數: hour參數表示時間的小時部分，其值需要大於或等於0，並小於24。
minute 參數: minute參數表示時間的分鐘部分，其值需要大於或等於0，並小於60。
second 參數: second參數表示時間的秒數部分，其值需要大於或等於0，並小於60。
microsecond 參數: microsecond參數表示時間的微秒部分，其值需要大於或等於0，並小於1000000。
tzinfo 參數: tzinfo參數為時間對應的時區物件。
fold 參數: fold參數用於消除歧義，其取值可以是0或1。如果參數tzinfo所指定的時區物件未在其相關方法中使用參數fold，那麽fold的取值是無關緊要的。

from datetime import time
# 建立 time 物件
time(8, 59, 0, 123456)
datetime.time(8, 59, 0, 123456)
# second 參數不正確
time(15, 0, 60)
…
ValueError: second must be in 0..59

datetime 模組的 datetime 類別

datetime類別用於表示一個特定的日期時間，該日期時間包含了年，月，日，小時，分，秒，微秒等資訊，其建構子的形式如下，建構子的參數的含義與date，time類別的建構子相同。如果傳遞給建構子的參數不能正確的表示一個日期時間，那麽建構子將擲回例外狀況ValueError。

datetime(year, month, day, hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)

from datetime import datetime
# 建立 datetime 物件
datetime(2024, 12, 30)
datetime.datetime(2024, 12, 30, 0, 0)

取得日期時間資訊

date，time和datetime物件具有以下唯讀屬性，可用於取得與日期時間相關的資訊。其中，year屬性表示年份，month屬性表示月份（1至12），day屬性表示一月中的第幾天，hour屬性表示小時（0至23），minute屬性表示分鐘（0至59），second屬性表示秒數（0至59），microsecond屬性表示微秒數（0至999999），tzinfo屬性是表示時區資訊的tzinfo物件，fold屬性的取值為0或1，表示如何消除歧義。

datetime物件的date方法，可用於取得日期時間對應的日期，其傳回值是一個新的date物件，擁有與原datetime物件相同的year，month以及day屬性。

datetime物件的timetz方法，可用於取得日期時間對應的時間，其傳回值是一個新的time物件，擁有與原datetime物件相同的hour，minute，second，microsecond，tzinfo以及fold（需要 Python 3.6 或更高版本）屬性。datetime物件的time方法與timetz方法類似，只不過其傳回的time物件的tzinfo屬性為空值None。

datetime.date() datetime.timetz() datetime.time()

date和datetime物件的timetuple方法，其傳回值是time模組的struct_time物件，該物件包含了一些與日期時間相關的屬性。

date|datetime.timetuple()

from datetime import date, time, datetime, timezone
# 取得年份
date(2024, 1, 1).year
2024
# 取得微秒數
datetime.today().microsecond
573657
# 取得秒數
time(1, 30, 59).second
59
dt = datetime(2024, 9, 25, 8, 30, 0, 1234, timezone.utc, fold=1)
# 取得日期時間中的時間，不帶時區
dt.time()
datetime.time(8, 30, 0, 1234, fold=1)
# 取得日期時間中的時間，帶時區
dt.timetz()
datetime.time(8, 30, 0, 1234, tzinfo=datetime.timezone.utc, fold=1)
# 取得 struct_time
dt.timetuple()
time.struct_time(tm_year=2024, tm_mon=9, tm_mday=25, tm_hour=8, tm_min=30, tm_sec=0, tm_wday=2, tm_yday=269, tm_isdst=-1)

修改日期時間

date，time和datetime物件的replace方法會使用原有物件來建立新的物件，並根據給出的參數來取代原有的日期時間資訊，其參數含義與相關類別的建構子的參數含義相同。

date.replace(year=self.year, month=self.month, day=self.day) time.replace(hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=self.fold) datetime.replace(year=self.year, month=self.month, day=self.day, hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=self.fold)

你無法修改 date，time，datetime 物件所表示的日期時間

你無法通過date，time和datetime物件的相關屬性來修改日期時間，這些屬性是唯讀的，比如year屬性。Python 的設計者並不希望日期時間被改動，即便通過date，time和datetime物件的replace方法，因為該方法會傳回一個新的物件。

時區

如果你希望將datetime物件轉換為某個時區對應的日期時間而不是簡單的取代時區資訊，那麽可以檢視為日期時間轉換時區一段。

from datetime import date, time, datetime
# 根據原有日期時間建立新的日期時間
date(2024, 1, 1).replace(2023)
datetime.date(2023, 1, 1)
time(23, 59, 59, 1234).replace(microsecond=4321)
datetime.time(23, 59, 59, 4321)
datetime(2024, 1, 1, 23, 59, 59, fold=1).replace(month=3)
datetime.datetime(2024, 3, 1, 23, 59, 59, fold=1)

取得日期時間的 POSIX 時間戳記

datetime物件的方法timestamp，可用於取得datetime物件所表示的日期時間的 POSIX 時間戳記，該方法的傳回值是一個浮點數。

datetime.timestamp()

Python 中的 POSIX 時間戳記

POSIX 時間戳記是一個數值，他表示某個日期時間與國際標準日期時間（UTC） 1970 年 1 月 1 日 0 時 0 分 0 秒之間的差值。在 Python 中，POSIX 時間戳記被表示為浮點數，浮點數的整數部分對應了秒數，浮點數的小數部分對應了微秒。

from datetime import datetime
# 取得本機日期時間的時間戳記
datetime.today().timestamp()
1727179679.344979

取得 POSIX 時間戳記對應的日期時間

date類別的類別方法fromtimestamp，可用於取得某個 POSIX 時間戳記對應的日期（不包含時間資訊），該方法的傳回值是一個date物件。

date.fromtimestamp(timestamp)

timestamp 參數: timestamp參數為表示 POSIX 時間戳記的浮點數。

datetime類別的類別方法fromtimestamp，可用於取得某個 POSIX 時間戳記對應的日期時間，該方法的傳回值是一個datetime物件。

datetime.fromtimestamp(timestamp, tz=None)

timestamp 參數: timestamp參數為表示 POSIX 時間戳記的浮點數。
tz 參數: tz參數為表示時區資訊的tzinfo物件，方法會將 POSIX 時間戳記轉換為對應時區的日期時間並傳回。如果忽略該參數或將該參數設定為None，則直接傳回目前的本機日期時間。

在 Python 3.12 和之後的版本中，datetime類別的類別方法utcfromtimestamp已經被取代，他可用於取得 POSIX 時間戳記對應的國際標準日期時間（UTC）。

datetime 模組不能轉換所有的 POSIX 時間戳記

datetime模組不能將所有 POSIX 時間戳記轉換為日期時間，比如，時間戳記對應的浮點數太大，將小於0的時間戳記轉換為小於 1970 年 1 月 1 日 0 時 0 分 0 秒的國際標準日期時間（可以轉換時間戳記0）。如果時間戳記轉換失敗，那麽可能會擲回例外狀況OSError。

from datetime import date, datetime, timezone
# 將時間戳記轉換為日期
date.fromtimestamp(1727246240.124616)
datetime.date(2024, 9, 25)
# 將時間戳記轉換為日期時間
datetime.fromtimestamp(1727246240.124616)
datetime.datetime(2024, 9, 25, 14, 37, 20, 124616)
datetime.fromtimestamp(1727246240.124616, timezone.utc)
datetime.datetime(2024, 9, 25, 6, 37, 20, 124616, tzinfo=datetime.timezone.utc)
# 時間戳記不能小於 0
date.fromtimestamp(-1)
…
OSError: [Errno …] Invalid argument

取得目前的日期時間

date類別的類別方法today，可用於取得目前的本機日期（不包含時間資訊），該方法的傳回值是一個date物件。

date.today()

datetime類別的類別方法today和now，可用於取得目前的本機日期時間或其在指定時區對應的日期時間，該方法的傳回值是一個datetime物件。

datetime.today() datetime.now(tz=None)

tz 參數: tz參數為表示時區資訊的tzinfo物件，方法會將目前的本機日期時間轉換為對應時區的日期時間並傳回。如果忽略該參數或將該參數設定為None，則直接傳回目前的本機日期時間。

在 Python 3.12 和之後的版本中，datetime類別的類別方法utcnow已經被取代，他可用於取得目前的國際標準日期時間（UTC）。

from datetime import date, datetime, timezone
# 取得目前的本機日期
date.today()
datetime.date(2024, 9, 24)
# 取得目前的本機日期時間
datetime.today()
datetime.datetime(2024, 9, 24, 20, 53, 38, 244890)
datetime.now()
datetime.datetime(2024, 9, 24, 20, 54, 9, 974196)
# 取得目前的本機日期時間對應的 UTC 日期時間
datetime.now(timezone.utc)
datetime.datetime(2024, 9, 24, 12, 54, 51, 164800)

取得日期時間是一周中的第幾天

date和datetime物件的方法weekday，其傳回值是一個整數，該整數表示日期時間是一周中的第幾天，即當周日次（0表示星期一，6表示星期日）。

date和datetime物件的方法isoweekday與方法weekday類似，只不過傳回1表示星期一而不是星期二（7表示星期日）。

date|datetime.weekday() date|datetime.isoweekday()

from datetime import date, datetime
# 取得當周日次
date(2024, 9, 25).weekday()
2
datetime(2024, 9, 25, 23, 59, 59).isoweekday()
3

取得日期時間的行事歷資訊

date和datetime物件的方法isocalendar，其傳回值是一個具名元組（可通過元組變數來存取元組中的元素），該元組包含變數year，week，weekday，他們分別表示日期時間的年份，是一年中的第幾周（1表示第一周），是一周中的第幾天（1表示星期一）。

date|datetime.isocalendar()

from datetime import date, datetime
# 取得行事歷資訊
date(2024, 9, 25).isocalendar()
datetime.IsoCalendarDate(year=2024, week=39, weekday=3)
datetime(2024, 9, 25, 23, 59, 59).isocalendar()
datetime.IsoCalendarDate(year=2024, week=39, weekday=3)

取得行事歷資訊對應的日期時間

date和datetime類別的類別方法fromisocalendar（需要 Python 3.8 或更高版本），將根據給出的行事歷資訊，傳回其對應的日期（date物件）或日期時間（datetime物件）。

date|datetime.fromisocalendar(year, week, day)

year 參數: year參數表示年份，最終得到的日期或日期時間的年份可能與year參數不同。
week 參數: week參數表示日期時間是一年中的第幾周（1表示第一周）。
day 參數: day參數表示日期時間是一周中的第幾天（1表示星期一）。

from datetime import date, datetime
# 取得行事歷資訊對應的日期
date.fromisocalendar(2024, 39, 3)
datetime.date(2024, 9, 25)
# 取得行事歷資訊對應的日期時間
datetime.fromisocalendar(2024, 39, 3)
datetime.datetime(2024, 9, 25, 0, 0)

取得日期，時間，時區對應的日期時間

datetime類別的類別方法combine，可根據已有的日期（date物件），時間（time物件）以及時區資訊建立新的日期時間（datetime物件）。

datetime.combine(date, time, tzinfo=time.tzinfo)

date 參數: date參數為用來建立日期時間的date物件。
time 參數: time參數為用來建立日期時間的time物件。
tzinfo 參數: tzinfo參數為用來建立日期時間的時區資訊物件，如果忽略該參數，則將采用time參數的tzinfo屬性。

from datetime import date, time, datetime, timezone
# 根據日期，時間，時區建立日期時間
datetime.combine(date(2024, 9, 25), time(0, 0, 0, tzinfo=timezone.utc))
datetime.datetime(2024, 9, 25, 0, 0, tzinfo=datetime.timezone.utc)
datetime.combine(date(2024, 9, 25), time(0, 0, 0, tzinfo=timezone.utc), None)
datetime.datetime(2024, 9, 25, 0, 0)

取得日期時間在西元紀年法中的序號

date和datetime物件的方法toordinal，其傳回值是一個整數，可用於取得日期時間在西元紀年法中的序號（西元 1 年 1 月 1 日對應的序號為1，以此類推）。

date|datetime.toordinal()

from datetime import date, datetime
# 2024 年 9 月 25 日在西元紀年法中的序號
date(2024, 9, 25).toordinal()
739154
# 2024 年 9 月 25 日 23 時 59 分 59 秒在西元紀年法中的序號
datetime(2024, 9, 25, 23, 59, 59).toordinal()
739154

取得西元紀年序號對應的日期時間

date和datetime類別的類別方法fromordinal，可用於取得西元紀年序號（1對應西元 1 年 1 月 1 日，以此類推）對應的日期時間，其傳回值是一個date或datetime物件。如果傳回值是datetime物件，那麽其表示的時，分，秒，微秒均為0，其屬性tzinfo為None。

date|datetime.fromordinal(ordinal)

ordinal 參數: ordinal參數為表示西元紀年序號的整數，該值不能小於1或大於運算式datetime.max.toordinal()的計算結果，否則可能會引發例外狀況ValueError。

from datetime import date, datetime
# 取得西元紀年法序號 1 對應的日期
date.fromordinal(1)
datetime.date(1, 1, 1)
# 取得西元紀年法序號 2 對應的日期時間
datetime.fromordinal(2)
datetime.datetime(1, 1, 2, 0, 0)
# 序號不能小於 1
datetime.fromordinal(0)
…
ValueError: ordinal must be >= 1