datetime 模組詳解 -- 基本的日期和時間型別

datetime 模組提供了各種類用於操作日期和時間，該模組側重於高效率的格式化輸出

在 Python 中，與時間處理有關的模組包括：time，datetime 以及 calendar

datetime 模組定義了兩個常量：

• datetime.MINYEAR - date 和 datetime 物件所能支援的最小年份，object.MINYEAR 的值為 1
• datetime.MAXYEAR - date 和 datetime 物件所能支援的最大年份，object.MAXYEAR 的值為 9999

datetime 模組中定義的類（前四個下方有詳解）：

• datetime.date - 表示日期的類，常用屬性：year, month, day
• datetime.time - 表示時間的類，常用屬性：hour, minute, second, microsecond, tzinfo
• datetime.datetime - 表示日期和時間的類，常用屬性： year, month, day, hour, minute, second, microsecond, tzinfo
• datetime.timedelta - 表示時間間隔，即兩個時間點（date，time，datetime）之間的長度
• datetime.tzinfo - 表示時區的基類，為上方的 time 和 datetime 類提供調整的基準
• datetime.timezone - 表示 UTC 時區的固定偏移，是 tzinfo 基類的實現

注：上邊這些類的物件是不可變的

上邊這些類的從屬關係：

object
    timedelta
    tzinfo
        timezone
    time
    date
        datetime

timedelta 物件

timedelta 物件表示兩個日期或時間之間的間隔

datetime.timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0) 

以上所有的引數都是可選的（預設為 0），引數的可以是整數或浮點數，正數或負數。

內部的儲存單位只有 days（天）、seconds（秒）、microseconds（毫秒），其他單位均先轉換後再儲存：
 

• 1 millisecond -> 1000 microseconds
• 1 minutes -> 60 seconds
• 1 hours -> 3600 seconds
• 1 weeks -> 7 days

而 days、seconds 和 microseconds 為了不產生時間表示上的歧義，將根據以下範圍自動“進位”：

• 0 <= microseconds < 1000000
• 0 <= seconds < 3600 * 24（1小時的秒數 * 24小時）
• -999999999 <= days <= 999999999

timedelta 類屬性：

• timedelta.min - timedelta 物件負值的極限，timedelta(-999999999)
• timedelta.max - timedelta 物件正值的極限，timedelta(days=999999999, hours=23, minutes=59, seconds=59, microseconds=999999)
• timedelta.resolution - 兩個 timedelta 不相等的物件之間最小的差值，timedelta(microseconds=1)

請注意，在正常情況下，timedelta.max > -timedelta.min，-timedelta.max 無意義。

timedelta 例項屬性（只讀）：

timedelta 物件支援的操作：

注1：這是準確的，但可能會溢位
注2：這是準確的，並且不會溢位
注3：除數為 0 會引發 ZeroDivisionError 異常
注4：-timedelta.max 是無意義的

timedelta 例項方法：

timedelta.total_seconds()
- 返回 timedelta 物件所包含的總秒數，相當於 td / timedelta(seconds=1)

請注意，對於非常大的時間間隔（在大多數平臺上是大於270年），這種方法將失去微秒（microsecond）精度

timedelta 用法示例：

# 愛生活，愛科技
>>> from datetime import timedelta
>>> year = timedelta(days=365)
>>> another_year = timedelta(weeks=40, days=84, hours=23,
...                          minutes=50, seconds=600)  # adds up to 365 days
>>> year.total_seconds()
31536000.0
>>> year == another_year
True
>>> ten_years = 10 * year
>>> ten_years, ten_years.days // 365
(datetime.timedelta(3650), 10)
>>> nine_years = ten_years - year
>>> nine_years, nine_years.days // 365
(datetime.timedelta(3285), 9)
>>> three_years = nine_years // 3;
>>> three_years, three_years.days // 365
(datetime.timedelta(1095), 3)
>>> abs(three_years - ten_years) == 2 * three_years + year
True

date 物件

date 物件表示一個日期，在一個理想化的日曆裡，日期由 year（年）、month（月）、day（日）組成

datetime.date(year, month, day)

所有的引數都是必需的，引數可以是整數，並且在以下範圍內：

• MINYEAR <= year <= MAXYEAR（也就是 1 ~ 9999）
• 1 <= month <= 12
• 1 <= day <= 根據 year 和 month 來決定（例如 2015年2月 只有 28 天）

date 類方法（classmethod）：
 

• date.today() - 返回一個表示當前本地日期的 date 物件
• date.fromtimestamp(timestamp) - 根據給定的時間戮，返回一個 date 物件
• date.fromordinal(ordinal) - 將 Gregorian 日曆時間轉換為 date 物件（Gregorian Calendar：一種日曆表示方法，類似於我國的農曆，西方國家使用比較多）

date 類屬性：

• date.min - date 物件所能表示的最早日期，date(MINYEAR, 1, 1)
• date.max - date 物件所能表示的最晚日期，date(MAXYEAR, 12, 31)
• date.resolution - date 物件表示日期的最小單位，在這裡是 1 天，timedelta(days=1)

date 例項屬性（只讀）：

date 物件支援的操作：

注1：timedelta.day > 0 或 timedelta.day < 0 決定 date2 日期增長的方向；隨後，date2 - date1 == timedelta.days；timedelta.seconds 和 timedelta.microseconds 被忽略；如果 date2.year < MINYEAR 或 date2.year > MAXYEAR，引發 OverflowError 異常

注2：這並不等同於 date1 + (-timedelta)，因為單獨的 -timedelta 可能會溢位，而 date1 - timedelta 則不會溢位；timedelta.seconds 和 timedelta.microseconds 被忽略

注3：這是準確的，並且不會溢位；timedelta.seconds 和 timedelta.microseconds 都為 0，然後 date2 + timedelta == date1

注4：換句話說，當且僅當 date1.toordinal() < date2.toordinal()，才有 date1 < date2


date 例項方法：

date.replace(year, month, day)
- 生成一個新的日期物件，用引數指定的年、月、日代替原有物件中的屬性

date.timetuple()
- 返回日期對應的 time.struct_time 物件（類似於 time 模組 的 time.localtime()）

date.toordinal()
- 返回日期對應的 Gregorian Calendar 日期

date.weekday()
- 返回 0 ~ 6 表示星期幾（星期一是 0，依此類推）

date.isoweekday()
- 返回 1 ~ 7 表示星期幾（星期一是1， 依此類推）

date.isocalendar()
- 返回一個三元組格式 (year, month, day)

date.isoformat()
- 返回一個 ISO 8601 格式的日期字串，如 "YYYY-MM-DD" 的字串

date.__str__()
- 對於 date 物件 d 來說，str(d) 相當於 d.isoformat()

date.ctime()
- 返回一個表示日期的字串，相當於 time 模組的 time.ctime(time.mktime(d.timetuple()))

date.strftime(format)
- 返回自定義格式化字串表示日期，下面有詳解

date.__format__(format)
- 跟 date.strftime(format) 一樣，這使得呼叫 str.format() 時可以指定 data 物件的字串


以下是計算天數的例子：

# You may say I'm the dreamer. But I'm not the only one! 

>>> import time
>>> from datetime import date
>>> today = date.today()
>>> today
datetime.date(2014, 8, 31)
>>> today == date.fromtimestamp(time.time())
True
>>> my_birthday = date(today.year, 6, 24)
>>> if my_birthday < today:
        my_birthday = my_birthday.replace(year = today.year + 1)

>>> my_birthday
datetime.date(2015, 6, 24)
>>> time_to_birthday = abs(my_birthday - today)
>>> time_to_birthday.days
297

關於 date 的綜合應用：

>>> from datetime import date
>>> d = date.fromordinal(735678)  # 自日期 1.1.0001 之後的第 735678 天
>>> d
datetime.date(2015, 3, 21)
>>> t = d.timetuple()
>>> for i in t:
        print(i)
        
2015
3
21
0
0
0
5
80
-1
>>> ic = d.isocalendar()
>>> for i in ic:
        print(i)
        
2015
12
6
>>> d.isoformat()
'2015-03-21'
>>> d.strftime("%d/%m/%y")
'21/03/15'
>>> d.strftime("%A %d. %B %Y")
'Saturday 21. March 2015'
>>> 'The {1} is {0:%d}, the {2} is {0:%B}.'.format(d, "day", "month")
'The day is 21, the month is March.'

time 物件

time 物件表示一天中的一個時間，並且可以通過 tzinfo 物件進行調整

datetime.time(hour=0, minute=0, second=0, microsecond=0, tzinfo=None)

所有的引數都是可選的；tzinfo 可以是 None 或者 tzinfo 子類的例項物件；其餘的引數可以是整數，並且在以下範圍內：
 

• 0 <= hour < 24
• 0 <= minute < 60
• 0 <= second < 60
• 0 <= microsecond < 1000000

注：如果引數超出範圍，將引發 ValueError 異常

time 類屬性

• time.min - time 物件所能表示的最早時間，time(0, 0, 0, 0)
• time.max - time 物件所能表示的最晚時間，time(23, 59, 59, 999999)
• time.resolution - time 物件表示時間的最小單位，在這裡是 1 毫秒，timedelta(microseconds=1)

time 例項屬性（只讀）：

time 例項方法：

time.replace([hour[, minute[, second[, microsecond[, tzinfo]]]]]) 
- 生成一個新的時間物件，用引數指定時間代替原有物件中的屬性

time.isoformat()
- 返回一個 ISO 8601 格式的日期字串，如 "HH:MM:SS.mmmmmm" 的字串

time.__str__()
- 對於 time 物件 t 來說，str(t) 相當於 t.isoformat()

time.strftime(format)
- 返回自定義格式化字串表示時間，下面有詳解

time.__format__(format)
- 跟 time.strftime(format) 一樣，這使得呼叫 str.format() 時可以指定 time 物件的字串

time.utcoffset()
- 如果 tzinfo 屬性是 None，則返回 None；否則返回 self.tzinfo.utcoffset(self)

time.dst()
- 如果 tzinfo 屬性是 None，則返回 None；否則返回 self.tzinfo.dst(self)

time.tzname()
- 如果 tzinfo 屬性是 None，則返回 None；否則返回 self.tzinfo.tzname(self)


關於 time 的綜合應用：
 

>>> from datetime import time, timedelta, tzinfo
>>> class GMT1(tzinfo):
        def utcoffset(self, dt):
                return timedelta(hours=1)
        def dst(self, dt):
                return timedelta(0)
        def tzname(self, dt):
                return "歐洲/布拉格"

>>> t = time(14, 10, 30, tzinfo=GMT1())
>>> t
datetime.time(14, 10, 30, tzinfo=<__main__.GMT1 object at 0x02D7FE90>)
>>> gmt = GMT1()
>>> t.isoformat()
'14:10:30+01:00'
>>> t.dst()
datetime.timedelta(0)
>>> t.tzname()
'歐洲/布拉格'
>>> t.strftime("%H:%M:%S %Z")
'14:10:30 歐洲/布拉格'
>>> 'The {} is {:%H:%M}.'.format("time", t)
'The time is 14:10.'

datetime 物件

datetime 物件是 date 物件和 time 物件的結合體，並且包含他們的所有資訊
 

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

必須的引數是 year（年）、month（月）、day（日）；tzinfo 可以是 None 或者 tzinfo 子類的例項物件；其餘的引數可以是整數，並且在以下範圍內：

• MINYEAR <= year <= MAXYEAR（也就是 1 ~ 9999）
• 1 <= month <= 12
• 1 <= day <= 根據 year 和 month 來決定（例如 2015年2月 只有 28 天）
• 0 <= hour < 24
• 0 <= minute < 60
• 0 <= second < 60
• 0 <= microsecond < 1000000

注：如果引數超出範圍，將引發 ValueError 異常

datetime 類方法（classmethod）：

datetime.today()
- 返回一個表示當前本地時間的 datetime 物件，等同於 datetime.fromtimestamp(time.time())

datetime.now(tz=None)
- 返回一個表示當前本地時間的 datetime 物件；如果提供了引數 tz，則獲取 tz 引數所指時區的本地時間

datetime.utcnow()
- 返回一個當前 UTC 時間的 datetime 物件

datetime.fromtimestamp(timestamp, tz=None)
- 根據時間戮建立一個 datetime 物件，引數 tz 指定時區資訊

datetime.utcfromtimestamp(timestamp)
- 根據時間戮建立一個 UTC 時間的 datetime 物件

datetime.fromordinal(ordinal)
- 返回對應 Gregorian 日曆時間對應的 datetime 物件

datetime.combine(date, time)
- 根據引數 date 和 time，建立一個 datetime 物件

datetime.strptime(date_string, format)
- 將格式化字串轉換為 datetime 物件

datetime 類屬性：

• datetime.min - datetime 物件所能表示的最早日期，datetime(MINYEAR, 1, 1, tzinfo=None)
• datetime.max - datetime 物件所能表示的最晚日期，datetime(MAXYEAR, 12, 31, 23, 59, 59, 999999, tzinfo=None)
• datetime.resolution - datetime 物件表示日期的最小單位，在這裡是 1 毫秒，timedelta(microseconds=1)

datetime 例項屬性（只讀）：

datetime 物件支援的操作：
 

注1：timedelta.day > 0 或 timedelta.day < 0 決定 datetime2 日期增長的方向；計算結果 datetime2 的 tzinfo 屬性和 datetime1 相同；如果 date2.year < MINYEAR 或 date2.year > MAXYEAR，引發 OverflowError 異常

注2：計算結果 datetime2 的 tzinfo 屬性和 datetime1 相同；這並不等同於 date1 + (-timedelta)，因為單獨的 -timedelta 可能會溢位，而 date1 - timedelta 則不會溢位

注3：如果 datetime1 和 datetime2 的 tzinfo 屬性一樣（指向同一個時區），則 tzinfo 屬性被忽略，計算結果為一個 timedelta 物件 t，則 datetime2 + t == datetime1（不用進行時區調整）；如果 datetime1 和 datetime2 的 tzinfo 屬性不一樣（指向不同時區），則 datetime1 和 datetime2 會先被轉換為 UTC 時區時間，在進行計算，(datetime1.replace(tzinfo=None) - datetime1.utcoffset()) - (datetime2.replace(tzinfo=None) - datetime2.utcoffset())


datetime 例項方法：

datetime.date()
- 返回一個 date 物件datetime.time() - 返回一個 time 物件（tzinfo 屬性為 None）

datetime.timetz()
- 返回一個 time() 物件（帶有 tzinfo 屬性）

datetime.replace([year[, month[, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]]]]])
- 生成一個新的日期物件，用引數指定日期和時間代替原有物件中的屬性

datetime.astimezone(tz=None)
- 傳入一個新的 tzinfo 屬性，返回根據新時區調整好的 datetime 物件

datetime.utcoffset()
- 如果 tzinfo 屬性是 None，則返回 None；否則返回 self.tzinfo.utcoffset(self)

datetime.dst()
- 如果 tzinfo 屬性是 None，則返回 None；否則返回 self.tzinfo.dst(self)

datetime.tzname()
- 如果 tzinfo 屬性是 None，則返回 None；否則返回 self.tzinfo.tzname(self)

datetime.timetuple()
-  返回日期對應的 time.struct_time 物件（類似於 time 模組的 time.localtime()）

datetime.utctimetuple()
- 返回 UTC 日期對應的 time.struct_time 物件

datetime.toordinal()
- 返回日期對應的 Gregorian Calendar 日期（類似於 self.date().toordinal()）

datetime.timestamp()
- 返回當前時間的時間戳（類似於 time 模組的 time.time()）

datetime.weekday()
- 返回 0 ~ 6 表示星期幾（星期一是 0，依此類推）

datetime.isoweekday() 
- 返回 1 ~ 7 表示星期幾（星期一是1， 依此類推）

datetime.isocalendar() 
- 返回一個三元組格式 (year, month, day)

datetime.isoformat(sep='T')
- 返回一個 ISO 8601 格式的日期字串，如 "YYYY-MM-DD" 的字串

datetime.__str__()
- 對於 date 物件 d 來說，str(d) 相當於 d.isoformat()

datetime.ctime()
- 返回一個表示日期的字串，相當於 time 模組的 time.ctime(time.mktime(d.timetuple()))

datetime.strftime(format)
- 返回自定義格式化字串表示日期，下面有詳解

datetime.__format__(format)
- 跟 datetime.strftime(format) 一樣，這使得呼叫 str.format() 時可以指定 data 物件的字串


關於 datetime 的綜合應用：
 

>>> from datetime import datetime, date, time

# 使用 datetime.combine()
>>> d = date(2015, 8, 1)
>>> t = time(12, 30)
>>> datetime.combine(d, t)
datetime.datetime(2015, 8, 1, 12, 30)

# 使用 datetime.now() 或 datetime.utcnow()
>>> datetime.now()
datetime.datetime(2014, 8, 31, 18, 13, 40, 858954)
>>> datetime.utcnow()
datetime.datetime(2014, 8, 31, 10, 13, 49, 347984)

# 使用 datetime.srptime()
>>> dt = datetime.strptime("21/11/14 16:30", "%d/%m/%y %H:%M")
>>> dt
datetime.datetime(2014, 11, 21, 16, 30)

# 使用 datetime.timetuple()
>>> tt = dt.timetuple()
>>> for it in tt:
        print(it)

2014
11
21
16
30
0
4
325
-1

# ISO 格式的日期
>>> ic = dt.isocalendar()
>>> for it in ic:
        print(it)

2014
47
5

# 格式化 datetime 物件
>>> dt.strftime("%A, %d. %B %Y %I:%M%p")
'Friday, 21. November 2014 04:30PM'
>>> 'The {1} is {0:%d}, the {2} is {0:%B}, the {3} is {0:%I:%M%p}.'.format(dt, "day", "month", "time")
'The day is 21, the month is November, the time is 04:30PM.'

帶有 tzinfo 的 datetime 綜合演示：
 

>>> from datetime import timedelta, datetime, tzinfo
>>> class GMT1(tzinfo):
        def utcoffset(self, dt):
                return timedelta(hours=1) + self.dst(dt)
        def dst(self, dt):
                # DST 開始於三月最後一個星期天
                # 結束於十月最後一個星期天
                d = datetime(dt.year, 4, 1)
                self.dston = d - timedelta(days=d.weekday() + 1)
                d = datetime(dt.year, 11, 1)
                self.dstoff = d - timedelta(days=d.weekday() + 1)
                if self.dston <= dt.replace(tzinfo=None) < self.dstoff:
                        return timedelta(hours=1)
                else:
                        return timedelta(0)
        def tzname(self, dt):
                return "GMT +1"
        
>>> class GMT2(tzinfo):
        def utcoffset(self, dt):
                return timedelta(hours=2) + self.dst(dt)
        def dst(self, dt):
                d = datetime(dt.year, 4, 1)
                self.dston = d - timedelta(days=d.weekday() + 1)
                d = datetime(dt.year, 11, 1)
                self.dstoff = d - timedelta(days=d.weekday() + 1)
                if self.dston <=  dt.replace(tzinfo=None) < self.dstoff:
                        return timedelta(hours=1)
                else:
                        return timedelta(0)
        def tzname(self, dt):
                return "GMT +2"
        
>>> gmt1 = GMT1()

# 夏令時
>>> dt1 = datetime(2014, 11, 21, 16, 30, tzinfo=gmt1)
>>> dt1.dst()
datetime.timedelta(0)
>>> dt1.utcoffset()
datetime.timedelta(0, 3600)
>>> dt2 = datetime(2014, 6, 14, 13, 0, tzinfo=gmt1)
>>> dt2.dst()
datetime.timedelta(0, 3600)
>>> dt2.utcoffset()
datetime.timedelta(0, 7200)

# 將 datetime 轉換到另一個時區
>>> dt3 = dt2.astimezone(GMT2())
>>> dt3
datetime.datetime(2014, 6, 14, 14, 0, tzinfo=<__main__.GMT2 object at 0x036C0F70>)
>>> dt2
datetime.datetime(2014, 6, 14, 13, 0, tzinfo=<__main__.GMT1 object at 0x036C0B10>)
>>> dt2.utctimetuple() == dt3.utctimetuple()
True

格式化字串：strftime() 和 strptime()

date, datetime, 和 time 物件均支援使用 strftime(format) 方法，將指定的日期或時間轉換為自定義的格式化字串

相反的，datetime.strptime() 類方法卻是把格式化字串轉換為 datetime 物件
 

格式化字串綜合演示：
 

>>> from datetime import datetime
>>> dt = datetime.now()
>>> print('(%Y-%m-%d %H:%M:%S %f): ', dt.strftime('%Y-%m-%d %H:%M:%S %f'))
(%Y-%m-%d %H:%M:%S %f):  2014-08-31 23:54:58 379804
>>> print('(%Y-%m-%d %H:%M:%S %p): ', dt.strftime('%y-%m-%d %I:%M:%S %p'))
(%Y-%m-%d %H:%M:%S %p):  14-08-31 11:54:58 PM
>>> print('%%a: %s ' % dt.strftime('%a'))
%a: Sun 
>>> print('%%A: %s ' % dt.strftime('%A'))
%A: Sunday 
>>> print('%%b: %s ' % dt.strftime('%b'))
%b: Aug 
>>> print('%%B: %s ' % dt.strftime('%B'))
%B: August 
>>> print('日期時間%%c: %s ' % dt.strftime('%c'))
日期時間%c: 08/31/14 23:54:58 
>>> print('日期%%x：%s ' % dt.strftime('%x'))
日期%x：08/31/14 
>>> print('時間%%X：%s ' % dt.strftime('%X'))
時間%X：23:54:58 
>>> print('今天是這周的第%s天 ' % dt.strftime('%w'))
今天是這周的第0天 
>>> print('今天是今年的第%s天 ' % dt.strftime('%j'))
今天是今年的第243天 
>>> print('今周是今年的第%s周 ' % dt.strftime('%U'))
今周是今年的第35周