感知型對象和簡(jiǎn)單型對象?

日期和時(shí)間對象可以根據它們是否包含時(shí)區信息而分為“感知型”和“簡(jiǎn)單型”兩類(lèi)。

充分掌握應用性算法和政治性時(shí)間調整信息例如時(shí)區和夏令時(shí)的情況下，一個(gè) 感知型 對象就能相對于其他感知型對象來(lái)精確定位自身時(shí)間點(diǎn)。 感知型對象是用來(lái)表示一個(gè)沒(méi)有解釋空間的固定時(shí)間點(diǎn)。 1

簡(jiǎn)單型 對象沒(méi)有包含足夠多的信息來(lái)無(wú)歧義地相對于其他 date/time 對象來(lái)定位自身時(shí)間點(diǎn)。 不論一個(gè)簡(jiǎn)單型對象所代表的是世界標準時(shí)間（UTC）、當地時(shí)間還是某個(gè)其他時(shí)區的時(shí)間完全取決于具體程序，就像一個(gè)特定數字所代表的是米、英里還是質(zhì)量完全取決于具體程序一樣。 簡(jiǎn)單型對象更易于理解和使用，代價(jià)則是忽略了某些現實(shí)性考量。

對于要求感知型對象的應用，datetime 和 time 對象具有一個(gè)可選的時(shí)區信息屬性 tzinfo，它可被設為抽象類(lèi) tzinfo 的子類(lèi)的一個(gè)實(shí)例。 這些 tzinfo 對象會(huì )捕獲與 UTC 時(shí)間的差值、時(shí)區名稱(chēng)以及夏令時(shí)是否生效等信息。

datetime 模塊只提供了一個(gè)具體的 tzinfo 類(lèi)，即 timezone 類(lèi)。 timezone 類(lèi)可以表示具有相對于 UTC 的固定時(shí)差的簡(jiǎn)單時(shí)區，例如 UTC 本身或北美的 EST 和 EDT 時(shí)區等。 支持時(shí)間的詳細程度取決于具體的應用。 世界各地的時(shí)間調整規則往往是政治性多于合理性，經(jīng)常會(huì )發(fā)生變化，除了 UTC 之外并沒(méi)有一個(gè)能適合所有應用的標準。

常量?

The datetime module exports the following constants:

datetime.MINYEAR?

date 或者 datetime 對象允許的最小年份。 常量 MINYEAR 是 1 。

datetime.MAXYEAR?

date 或 datetime 對象允許最大的年份。常量 MAXYEAR 是 9999 。

datetime.UTC?

Alias for the UTC timezone singleton datetime.timezone.utc.

3.11 新版功能.

有效的類(lèi)型?

class datetime.date

一個(gè)理想化的簡(jiǎn)單型日期，它假設當今的公歷在過(guò)去和未來(lái)永遠有效。 屬性: year, month, and day。

class datetime.time

一個(gè)獨立于任何特定日期的理想化時(shí)間，它假設每一天都恰好等于 24*60*60 秒。 （這里沒(méi)有“閏秒”的概念。） 包含屬性: hour, minute, second, microsecond 和 tzinfo。

class datetime.datetime

日期和時(shí)間的結合。屬性：year, month, day, hour, minute, second, microsecond, and tzinfo.

class datetime.timedelta

表示兩個(gè) date 對象或 time 對象，或者 datetime 對象之間的時(shí)間間隔，精確到微秒。

class datetime.tzinfo

一個(gè)描述時(shí)區信息對象的抽象基類(lèi)。 用來(lái)給 datetime 和 time 類(lèi)提供自定義的時(shí)間調整概念（例如處理時(shí)區和/或夏令時(shí)）。

class datetime.timezone

一個(gè)實(shí)現了 tzinfo 抽象基類(lèi)的子類(lèi)，用于表示相對于 世界標準時(shí)間（UTC）的偏移量。

3.2 新版功能.

這些類(lèi)型的對象都是不可變的。

子類(lèi)關(guān)系

object
    timedelta
    tzinfo
        timezone
    time
    date
        datetime

timedelta 類(lèi)對象?

timedelta 對象表示兩個(gè) date 或者 time 的時(shí)間間隔。

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

所有參數都是可選的并且默認為 0。 這些參數可以是整數或者浮點(diǎn)數，也可以是正數或者負數。

只有 days, seconds 和 microseconds 會(huì )存儲在內部。 參數單位的換算規則如下：

• 1毫秒會(huì )轉換成1000微秒。

• 1分鐘會(huì )轉換成60秒。

• 1小時(shí)會(huì )轉換成3600秒。

• 1星期會(huì )轉換成7天。

日期、秒、微秒都是標準化的，所以它們的表達方式也是唯一的，例：

• 0 <= microseconds < 1000000

• 0 <= seconds < 3600*24 (一天的秒數)

• -999999999 <= days <= 999999999

下面的例子演示了如何對 days, seconds 和 microseconds 以外的任意參數執行“合并”操作并標準化為以上三個(gè)結果屬性:

>>>

>>> from datetime import timedelta
>>> delta = timedelta(
...     days=50,
...     seconds=27,
...     microseconds=10,
...     milliseconds=29000,
...     minutes=5,
...     hours=8,
...     weeks=2
... )
>>> # Only days, seconds, and microseconds remain
>>> delta
datetime.timedelta(days=64, seconds=29156, microseconds=10)

在有任何參數為浮點(diǎn)型并且 microseconds 值為小數的情況下，從所有參數中余下的微秒數將被合并，并使用四舍五入偶不入奇的規則將總計值舍入到最接近的整數微秒值。 如果沒(méi)有任何參數為浮點(diǎn)型的情況下，則轉換和標準化過(guò)程將是完全精確的（不會(huì )丟失信息）。

如果標準化后的 days 數值超過(guò)了指定范圍，將會(huì )拋出 OverflowError 異常。

請注意對負數值進(jìn)行標準化的結果可能會(huì )令人感到驚訝。 例如:

>>>

>>> from datetime import timedelta
>>> d = timedelta(microseconds=-1)
>>> (d.days, d.seconds, d.microseconds)
(-1, 86399, 999999)

類(lèi)屬性：

timedelta.min?

The most negative timedelta object, timedelta(-999999999).

timedelta.max?

The most positive timedelta object, timedelta(days=999999999, hours=23, minutes=59, seconds=59, microseconds=999999).

timedelta.resolution?

兩個(gè)不相等的 timedelta 類(lèi)對象最小的間隔為 timedelta(microseconds=1)。

需要注意的是，因為標準化的緣故，timedelta.max > -timedelta.min，-timedelta.max 不可以表示一個(gè) timedelta 類(lèi)對象。

實(shí)例屬性（只讀）：

支持的運算：

注釋?zhuān)?/p>

1. 結果正確，但可能會(huì )溢出。

2. 結果正確，不會(huì )溢出。

3. 除以0將會(huì )拋出異常 ZeroDivisionError 。

4. -timedelta.max 不是一個(gè) timedelta 類(lèi)對象。

5. timedelta 對象的字符串表示形式類(lèi)似于其內部表示形式被規范化。對于負時(shí)間增量，這會(huì )導致一些不尋常的結果。例如:

   >>>

   >>> timedelta(hours=-5)
   datetime.timedelta(days=-1, seconds=68400)
   >>> print(_)
   -1 day, 19:00:00
   

6. 表達式 t2 - t3 通常與 t2 + (-t3) 是等價(jià)的，除非 t3 等于 timedelta.max; 在這種情況下前者會(huì )返回結果，而后者則會(huì )溢出。

除了上面列舉的操作以外，timedelta 對象還支持與 date 和 datetime 對象進(jìn)行特定的相加和相減運算（見(jiàn)下文）。

支持 timedelta 對象之間進(jìn)行比較，但其中有一些注意事項。

== 或 != 比較 總是 返回一個(gè) bool 對象，無(wú)論被比較的對象是什么類(lèi)型:

>>> from datetime import timedelta
>>> delta1 = timedelta(seconds=57)
>>> delta2 = timedelta(hours=25, seconds=2)
>>> delta2 != delta1
True
>>> delta2 == 5
False

對于所有其他比較 (例如 < 和 >)，當一個(gè) timedelta 對象與其他類(lèi)型的對象比較時(shí)，將引發(fā) TypeError:

>>> delta2 > delta1
True
>>> delta2 > 5
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: '>' not supported between instances of 'datetime.timedelta' and 'int'

在布爾運算中，timedelta 對象當且僅當其不等于 timedelta(0) 時(shí)則會(huì )被視為真值。

實(shí)例方法：

timedelta.total_seconds()?

返回期間占用了多少秒。等價(jià)于 td / timedelta(seconds=1)。對于秒以外的間隔單位，直接使用除法形式 (例如 td / timedelta(microseconds=1))。

需要注意的是，時(shí)間間隔較大時(shí)，這個(gè)方法的結果中的微秒將會(huì )失真（大多數平臺上大于270年視為一個(gè)較大的時(shí)間間隔）。

3.2 新版功能.

>>> # Components of another_year add up to exactly 365 days
>>> from datetime import timedelta
>>> year = timedelta(days=365)
>>> another_year = timedelta(weeks=40, days=84, hours=23,
...                          minutes=50, seconds=600)
>>> year == another_year
True
>>> year.total_seconds()
31536000.0

>>> from datetime import timedelta
>>> year = timedelta(days=365)
>>> ten_years = 10 * year
>>> ten_years
datetime.timedelta(days=3650)
>>> ten_years.days // 365
10
>>> nine_years = ten_years - year
>>> nine_years
datetime.timedelta(days=3285)
>>> three_years = nine_years // 3
>>> three_years, three_years.days // 365
(datetime.timedelta(days=1095), 3)

date 對象?

date 對象代表一個(gè)理想化歷法中的日期（年、月和日），即當今的格列高利歷向前后兩個(gè)方向無(wú)限延伸。

公元 1 年 1 月 1日是第 1 日，公元 1 年 1 月 2 日是第 2 日，依此類(lèi)推。 2

class datetime.date(year, month, day)?

所有參數都是必要的。 參數必須是在下面范圍內的整數：

• MINYEAR <= year <= MAXYEAR

• 1 <= month <= 12

• 1 <= 日期 <= 給定年月對應的天數

如果參數不在這些范圍內，則拋出 ValueError 異常。

其它構造器，所有的類(lèi)方法：

classmethod date.today()?

返回當前的本地日期。

這等價(jià)于 date.fromtimestamp(time.time())。

classmethod date.fromtimestamp(timestamp)?

返回對應于 POSIX 時(shí)間戳的當地時(shí)間，例如 time.time() 返回的就是時(shí)間戳。

這可能引發(fā) OverflowError，如果時(shí)間戳數值超出所在平臺 C localtime() 函數的支持范圍的話(huà)，并且會(huì )在 localtime() 出錯時(shí)引發(fā) OSError。 通常該數值會(huì )被限制在 1970 年至 2038 年之間。 請注意在時(shí)間戳概念包含閏秒的非 POSIX 系統上，閏秒會(huì )被 fromtimestamp() 所忽略。

在 3.3 版更改: 引發(fā) OverflowError 而不是 ValueError，如果時(shí)間戳數值超出所在平臺 C localtime() 函數的支持范圍的話(huà)，并會(huì )在 localtime() 出錯時(shí)引發(fā) OSError 而不是 ValueError。

classmethod date.fromordinal(ordinal)?

返回對應于預期格列高利歷序號的日期，其中公元 1 年 1 月 1 日的序號為 1。

除非 1 <= ordinal <= date.max.toordinal() 否則會(huì )引發(fā) ValueError。對于任意日期 d，date.fromordinal(d.toordinal()) == d。

classmethod date.fromisoformat(date_string)?

Return a date corresponding to a date_string given in any valid ISO 8601 format, except ordinal dates (e.g. YYYY-DDD):

>>>

>>> from datetime import date
>>> date.fromisoformat('2019-12-04')
datetime.date(2019, 12, 4)
>>> date.fromisoformat('20191204')
datetime.date(2019, 12, 4)
>>> date.fromisoformat('2021-W01-1')
datetime.date(2021, 1, 4)

3.7 新版功能.

在 3.11 版更改: Previously, this method only supported the format YYYY-MM-DD.

classmethod date.fromisocalendar(year, week, day)?

返回指定 year, week 和 day 所對應 ISO 歷法日期的 date。 這是函數 date.isocalendar() 的逆操作。

3.8 新版功能.

類(lèi)屬性：

date.min?

最小的日期 date(MINYEAR, 1, 1) 。

date.max?

最大的日期 ，date(MAXYEAR, 12, 31)。

date.resolution?

兩個(gè)日期對象的最小間隔，timedelta(days=1)。

實(shí)例屬性（只讀）：

date.year?

在 MINYEAR 和 MAXYEAR 之間，包含邊界。

date.month?

1 至 12（含）

date.day?

返回1到指定年月的天數間的數字。

支持的運算：

注釋?zhuān)?/p>

1. 如果 timedelta.days > 0 則 date2 將在時(shí)間線(xiàn)上前進(jìn)，如果 timedelta.days < 0 則將后退。 操作完成后 date2 - date1 == timedelta.days。 timedelta.seconds 和 timedelta.microseconds 會(huì )被忽略。 如果 date2.year 將小于 MINYEAR 或大于 MAXYEAR 則會(huì )引發(fā) OverflowError。

2. timedelta.seconds 和 timedelta.microseconds 會(huì )被忽略。

3. 此值完全精確且不會(huì )溢出。 操作完成后 timedelta.seconds 和 timedelta.microseconds 均為 0，并且 date2 + timedelta == date1。

4. 換句話(huà)說(shuō)，當且僅當 date1.toordinal() < date2.toordinal() 時(shí) date1 < date2。 日期比較會(huì )引發(fā) TypeError，如果比較目標不為 date 對象的話(huà)。 不過(guò)也可能會(huì )返回 NotImplemented，如果比較目標具有 timetuple() 屬性的話(huà)。 這個(gè)鉤子給予其他日期對象類(lèi)型實(shí)現混合類(lèi)型比較的機會(huì )。 否則，當 date 對象與不同類(lèi)型的對象比較時(shí)將會(huì )引發(fā) TypeError，除非是 == 或 != 比較。 后兩種情況將分別返回 False 或 True。

在布爾運算中，所有 date 對象都會(huì )被視為真值。

實(shí)例方法：

date.replace(year=self.year, month=self.month, day=self.day)?

返回一個(gè)具有同樣值的日期，除非通過(guò)任何關(guān)鍵字參數給出了某些形參的新值。

示例:

>>>

>>> from datetime import date
>>> d = date(2002, 12, 31)
>>> d.replace(day=26)
datetime.date(2002, 12, 26)

date.timetuple()?

返回一個(gè) time.struct_time，即 time.localtime() 所返回的類(lèi)型。

hours, minutes 和 seconds 值均為 0，且 DST 旗標值為 -1。

d.timetuple() 等價(jià)于:

time.struct_time((d.year, d.month, d.day, 0, 0, 0, d.weekday(), yday, -1))

其中 yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1 是當前年份中的日期序號，1 月 1 日的序號為 1。

date.toordinal()?

返回日期的預期格列高利歷序號，其中公元 1 年 1 月 1 日的序號為 1。 對于任意 date 對象 d，date.fromordinal(d.toordinal()) == d。

date.weekday()?

返回一個(gè)整數代表星期幾，星期一為0，星期天為6。例如， date(2002, 12, 4).weekday() == 2，表示的是星期三。參閱 isoweekday()。

date.isoweekday()?

返回一個(gè)整數代表星期幾，星期一為1，星期天為7。例如：date(2002, 12, 4).isoweekday() == 3,表示星期三。參見(jiàn) weekday(), isocalendar()。

date.isocalendar()?

返回一個(gè)由三部分組成的 named tuple 對象: year, week 和 weekday。

ISO 歷法是一種被廣泛使用的格列高利歷。 3

ISO 年由 52 或 53 個(gè)完整星期構成，每個(gè)星期開(kāi)始于星期一結束于星期日。 一個(gè) ISO 年的第一個(gè)星期就是（格列高利）歷法的一年中第一個(gè)包含星期四的星期。 這被稱(chēng)為 1 號星期，這個(gè)星期四所在的 ISO 年與其所在的格列高利年相同。

例如，2004 年的第一天是星期四，因此 ISO 2004 年的第一個(gè)星期開(kāi)始于 2003 年 12 月 29 日星期一，結束于 2004 年 1 月 4 日星期日:

>>>

>>> from datetime import date
>>> date(2003, 12, 29).isocalendar()
datetime.IsoCalendarDate(year=2004, week=1, weekday=1)
>>> date(2004, 1, 4).isocalendar()
datetime.IsoCalendarDate(year=2004, week=1, weekday=7)

在 3.9 版更改: 結果由元組改為 named tuple。

date.isoformat()?

返回一個(gè)以 ISO 8601 格式 YYYY-MM-DD 來(lái)表示日期的字符串:

>>>

>>> from datetime import date
>>> date(2002, 12, 4).isoformat()
'2002-12-04'

date.__str__()?

對于日期對象 d, str(d) 等價(jià)于 d.isoformat() 。

date.ctime()?

返回一個(gè)表示日期的字符串:

>>>

>>> from datetime import date
>>> date(2002, 12, 4).ctime()
'Wed Dec  4 00:00:00 2002'

d.ctime() 等效于:

time.ctime(time.mktime(d.timetuple()))

在原生 C ctime() 函數 (time.ctime() 會(huì )發(fā)起調用該函數，但 date.ctime() 則不會(huì )) 遵循 C 標準的平臺上。

date.strftime(format)?

返回一個(gè)由顯式格式字符串所指明的代表日期的字符串。 表示時(shí)、分或秒的格式代碼值將為 0。 要獲取格式指令的完整列表請參閱 strftime() 和 strptime() 的行為。

date.__format__(format)?

與 date.strftime() 相同。 此方法使得為 date 對象指定以 格式化字符串字面值 表示的格式化字符串以及使用 str.format() 進(jìn)行格式化成為可能。 要獲取格式指令的完整列表，請參閱 strftime() 和 strptime() 的行為。

>>> import time
>>> from datetime import date
>>> today = date.today()
>>> today
datetime.date(2007, 12, 5)
>>> 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(2008, 6, 24)
>>> time_to_birthday = abs(my_birthday - today)
>>> time_to_birthday.days
202

>>> from datetime import date
>>> d = date.fromordinal(730920) # 730920th day after 1. 1. 0001
>>> d
datetime.date(2002, 3, 11)

>>> # Methods related to formatting string output
>>> d.isoformat()
'2002-03-11'
>>> d.strftime("%d/%m/%y")
'11/03/02'
>>> d.strftime("%A %d. %B %Y")
'Monday 11. March 2002'
>>> d.ctime()
'Mon Mar 11 00:00:00 2002'
>>> 'The {1} is {0:%d}, the {2} is {0:%B}.'.format(d, "day", "month")
'The day is 11, the month is March.'

>>> # Methods for to extracting 'components' under different calendars
>>> t = d.timetuple()
>>> for i in t:     
...     print(i)
2002                # year
3                   # month
11                  # day
0
0
0
0                   # weekday (0 = Monday)
70                  # 70th day in the year
-1
>>> ic = d.isocalendar()
>>> for i in ic:    
...     print(i)
2002                # ISO year
11                  # ISO week number
1                   # ISO day number ( 1 = Monday )

>>> # A date object is immutable; all operations produce a new object
>>> d.replace(year=2005)
datetime.date(2005, 3, 11)

datetime 對象?

datetime 對象是包含來(lái)自 date 對象和 time 對象的所有信息的單一對象。

與 date 對象一樣，datetime 假定當前的格列高利歷向前后兩個(gè)方向無(wú)限延伸；與 time 對象一樣，datetime 假定每一天恰好有 3600*24 秒。

構造器 ：

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

year, month 和 day 參數是必須的。 tzinfo 可以是 None 或者是一個(gè) tzinfo 子類(lèi)的實(shí)例。 其余的參數必須是在下面范圍內的整數：

• MINYEAR <= year <= MAXYEAR,

• 1 <= month <= 12,

• 1 <= day <= 指定年月的天數,

• 0 <= hour < 24,

• 0 <= minute < 60,

• 0 <= second < 60,

• 0 <= microsecond < 1000000,

• fold in [0, 1].

如果參數不在這些范圍內，則拋出 ValueError 異常。

3.6 新版功能: 增加了 fold 參數。

其它構造器，所有的類(lèi)方法：

classmethod datetime.today()?

返回表示當前地方時(shí)的 datetime 對象，其中 tzinfo 為 None。

等價(jià)于:

datetime.fromtimestamp(time.time())

另請參閱 now(), fromtimestamp()。

此方法的功能等價(jià)于 now()，但是不帶 tz 形參。

classmethod datetime.now(tz=None)?

返回表示當前地方時(shí)的 date 和 time 對象。

如果可選參數 tz 為 None 或未指定，這就類(lèi)似于 today()，但該方法會(huì )在可能的情況下提供比通過(guò) time.time() 時(shí)間戳所獲時(shí)間值更高的精度（例如，在提供了 C gettimeofday() 函數的平臺上就可以做到這一點(diǎn)）。

如果 tz 不為 None，它必須是 tzinfo 子類(lèi)的一個(gè)實(shí)例，并且當前日期和時(shí)間將被轉換到 tz 時(shí)區。

此函數可以替代 today() 和 utcnow()。

classmethod datetime.utcnow()?

返回表示當前 UTC 時(shí)間的 date 和 time，其中 tzinfo 為 None。

這類(lèi)似于 now()，但返回的是當前 UTC 日期和時(shí)間，類(lèi)型為簡(jiǎn)單型 datetime 對象。 感知型的當前 UTC 日期時(shí)間可通過(guò)調用 datetime.now(timezone.utc) 來(lái)獲得。 另請參閱 now()。

警告

由于簡(jiǎn)單型 datetime 對象會(huì )被許多 datetime 方法當作本地時(shí)間來(lái)處理，最好是使用感知型日期時(shí)間對象來(lái)表示 UTC 時(shí)間。 因此，創(chuàng )建表示當前 UTC 時(shí)間的對象的推薦方式是通過(guò)調用 datetime.now(timezone.utc)。

classmethod datetime.fromtimestamp(timestamp, tz=None)?

返回 POSIX 時(shí)間戳對應的本地日期和時(shí)間，如 time.time() 返回的。 如果可選參數 tz 指定為 None 或未指定，時(shí)間戳將轉換為平臺的本地日期和時(shí)間，并且返回的 datetime 對象將為簡(jiǎn)單型。

如果 tz 不為 None，它必須是 tzinfo 子類(lèi)的一個(gè)實(shí)例，并且時(shí)間戳將被轉換到 tz 指定的時(shí)區。

fromtimestamp() 可能會(huì )引發(fā) OverflowError，如果時(shí)間戳數值超出所在平臺 C localtime() 或 gmtime() 函數的支持范圍的話(huà)，并會(huì )在 localtime() 或 gmtime() 報錯時(shí)引發(fā) OSError。 通常該數值會(huì )被限制在 1970 年至 2038 年之間。 請注意在時(shí)間戳概念包含閏秒的非 POSIX 系統上，閏秒會(huì )被 fromtimestamp() 所忽略，結果可能導致兩個(gè)相差一秒的時(shí)間戳產(chǎn)生相同的 datetime 對象。 相比 utcfromtimestamp() 更推薦使用此方法。

在 3.3 版更改: 引發(fā) OverflowError 而不是 ValueError，如果時(shí)間戳數值超出所在平臺 C localtime() 或 gmtime() 函數的支持范圍的話(huà)。 并會(huì )在 localtime() 或 gmtime() 出錯時(shí)引發(fā) OSError 而不是 ValueError。

在 3.6 版更改: fromtimestamp() 可能返回 fold 值設為 1 的實(shí)例。

classmethod datetime.utcfromtimestamp(timestamp)?

返回對應于 POSIX 時(shí)間戳的 UTC datetime，其中 tzinfo 值為 None。 （結果為簡(jiǎn)單型對象。）

這可能引發(fā) OverflowError，如果時(shí)間戳數值超出所在平臺 C gmtime() 函數的支持范圍的話(huà)，并會(huì )在 gmtime() 報錯時(shí)引發(fā) OSError。 通常該數值會(huì )被限制在 1970 至 2038 年之間。

要得到一個(gè)感知型 datetime 對象，應調用 fromtimestamp():

datetime.fromtimestamp(timestamp, timezone.utc)

在 POSIX 兼容的平臺上，它等價(jià)于以下表達式:

datetime(1970, 1, 1, tzinfo=timezone.utc) + timedelta(seconds=timestamp)

不同之處在于后一種形式總是支持完整年份范圍：從 MINYEAR 到 MAXYEAR 的開(kāi)區間。

警告

由于簡(jiǎn)單型 datetime 對象會(huì )被許多 datetime 方法當作本地時(shí)間來(lái)處理，最好是使用感知型日期時(shí)間對象來(lái)表示 UTC 時(shí)間。 因此，創(chuàng )建表示特定 UTC 時(shí)間戳的日期時(shí)間對象的推薦方式是通過(guò)調用 datetime.fromtimestamp(timestamp, tz=timezone.utc)。

在 3.3 版更改: 引發(fā) OverflowError 而不是 ValueError，如果時(shí)間戳數值超出所在平臺 C gmtime() 函數的支持范圍的話(huà)。 并會(huì )在 gmtime() 出錯時(shí)引發(fā) OSError 而不是 ValueError。

classmethod datetime.fromordinal(ordinal)?

返回對應于預期格列高利歷序號的 datetime，其中公元 1 年 1 月 1 日的序號為 1。 除非 1 <= ordinal <= datetime.max.toordinal() 否則會(huì )引發(fā) ValueError。 結果的 hour, minute, second 和 microsecond 值均為 0，并且 tzinfo 值為 None。

classmethod datetime.combine(date, time, tzinfo=self.tzinfo)?

返回一個(gè)新的 datetime 對象，對象的日期部分等于給定的 date 對象的值，而其時(shí)間部分等于給定的 time 對象的值。 如果提供了 tzinfo 參數，其值會(huì )被用來(lái)設置結果的 tzinfo 屬性，否則將使用 time 參數的 tzinfo 屬性。

對于任意 datetime 對象 d，d == datetime.combine(d.date(), d.time(), d.tzinfo)。 如果 date 是一個(gè) datetime 對象，它的時(shí)間部分和 tzinfo 屬性會(huì )被忽略。

在 3.6 版更改: 增加了 tzinfo 參數。

classmethod datetime.fromisoformat(date_string)?

Return a datetime corresponding to a date_string in any valid ISO 8601 format, with the following exceptions:

1. Time zone offsets may have fractional seconds.

2. The T separator may be replaced by any single unicode character.

3. Ordinal dates are not currently supported.

4. Fractional hours and minutes are not supported.

示例:

>>>

>>> from datetime import datetime
>>> datetime.fromisoformat('2011-11-04')
datetime.datetime(2011, 11, 4, 0, 0)
>>> datetime.fromisoformat('20111104')
datetime.datetime(2011, 11, 4, 0, 0)
>>> datetime.fromisoformat('2011-11-04T00:05:23')
datetime.datetime(2011, 11, 4, 0, 5, 23)
>>> datetime.fromisoformat('2011-11-04T00:05:23Z')
datetime.datetime(2011, 11, 4, 0, 5, 23, tzinfo=datetime.timezone.utc)
>>> datetime.fromisoformat('20111104T000523')
datetime.datetime(2011, 11, 4, 0, 5, 23)
>>> datetime.fromisoformat('2011-W01-2T00:05:23.283')
datetime.datetime(2011, 1, 4, 0, 5, 23, 283000)
>>> datetime.fromisoformat('2011-11-04 00:05:23.283')
datetime.datetime(2011, 11, 4, 0, 5, 23, 283000)
>>> datetime.fromisoformat('2011-11-04 00:05:23.283+00:00')
datetime.datetime(2011, 11, 4, 0, 5, 23, 283000, tzinfo=datetime.timezone.utc)
>>> datetime.fromisoformat('2011-11-04T00:05:23+04:00')   
datetime.datetime(2011, 11, 4, 0, 5, 23,
    tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))

3.7 新版功能.

在 3.11 版更改: Previously, this method only supported formats that could be emitted by date.isoformat() or datetime.isoformat().

classmethod datetime.fromisocalendar(year, week, day)?

返回以 year, week 和 day 值指明的 ISO 歷法日期所對應的 datetime。 該datetime 對象的非日期部分將使用其標準默認值來(lái)填充。 這是函數 datetime.isocalendar() 的逆操作。

3.8 新版功能.

classmethod datetime.strptime(date_string, format)?

返回一個(gè)對應于 date_string，根據 format 進(jìn)行解析得到的 datetime 對象。

這相當于：

datetime(*(time.strptime(date_string, format)[0:6]))

如果 date_string 和 format 無(wú)法被 time.strptime() 解析或它返回一個(gè)不是時(shí)間元組的值，則將引發(fā) ValueError。 要獲取格式化指令的完整列表，請參閱 strftime() 和 strptime() 的行為。

類(lèi)屬性：

datetime.min?

最早的可表示 datetime，datetime(MINYEAR, 1, 1, tzinfo=None)。

datetime.max?

最晚的可表示 datetime，datetime(MAXYEAR, 12, 31, 23, 59, 59, 999999, tzinfo=None)。

datetime.resolution?

兩個(gè)不相等的 datetime 對象之間可能的最小間隔，timedelta(microseconds=1)。

實(shí)例屬性（只讀）：

datetime.year?

在 MINYEAR 和 MAXYEAR 之間，包含邊界。

datetime.month?

1 至 12（含）

datetime.day?

返回1到指定年月的天數間的數字。

datetime.hour?

取值范圍是 range(24)。

datetime.minute?

取值范圍是 range(60)。

datetime.second?

取值范圍是 range(60)。

datetime.microsecond?

取值范圍是 range(1000000)。

datetime.tzinfo?

作為 tzinfo 參數被傳給 datetime 構造器的對象，如果沒(méi)有傳入值則為 None。

datetime.fold?

取值范圍是 [0, 1]。 用于在重復的時(shí)間段中消除邊界時(shí)間歧義。 （當夏令時(shí)結束時(shí)回撥時(shí)鐘或由于政治原因導致當明時(shí)區的 UTC 時(shí)差減少就會(huì )出現重復的時(shí)間段。） 取值 0 (1) 表示兩個(gè)時(shí)刻早于（晚于）所代表的同一邊界時(shí)間。

3.6 新版功能.

支持的運算：

1. datetime2 是從 datetime1 去掉了一段 timedelta 的結果，如果 timedelta.days > 0 則是在時(shí)間線(xiàn)上前進(jìn)，如果 timedelta.days < 0 則是在時(shí)間線(xiàn)上后退。 該結果具有與輸入的 datetime 相同的 tzinfo 屬性，并且操作完成后 datetime2 - datetime1 == timedelta。 如果 datetime2.year 將要小于 MINYEAR 或大于 MAXYEAR 則會(huì )引發(fā) OverflowError。 請注意即使輸入的是一個(gè)感知型對象，該方法也不會(huì )進(jìn)行時(shí)區調整。

2. 計算 datetime2 使得 datetime2 + timedelta == datetime1。 與相加操作一樣，結果具有與輸入的 datetime 相同的 tzinfo 屬性，即使輸入的是一個(gè)感知型對象，該方法也不會(huì )進(jìn)行時(shí)區調整。

3. 從一個(gè) datetime 減去一個(gè) datetime 僅對兩個(gè)操作數均為簡(jiǎn)單型或均為感知型時(shí)有定義。 如果一個(gè)是感知型而另一個(gè)是簡(jiǎn)單型，則會(huì )引發(fā) TypeError。

   如果兩個(gè)操作數都是簡(jiǎn)單型，或都是感知型并且具有相同的 tzinfo 屬性，則 tzinfo 屬性會(huì )被忽略，并且結果會(huì )是一個(gè)使得 datetime2 + t == datetime1 的 timedelta 對象 t。 在此情況下不會(huì )進(jìn)行時(shí)區調整。

   如果兩個(gè)操作數都是感知型且具有不同的 tzinfo 屬性，a-b 操作的效果就如同 a 和 b 首先被轉換為簡(jiǎn)單型 UTC 日期時(shí)間。 結果將是 (a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None) - b.utcoffset())，除非具體實(shí)現絕對不溢出。

4. 當 datetime1 的時(shí)間在 datetime2 之前則認為 datetime1 小于 datetime2。

   如果比較的一方是簡(jiǎn)單型而另一方是感知型，則如果嘗試進(jìn)行順序比較將引發(fā) TypeError。 對于相等比較，簡(jiǎn)單型實(shí)例將永遠不等于感知型實(shí)例。

   如果兩個(gè)比較方都是感知型，且具有相同的 tzinfo 屬性，則相同的 tzinfo 屬性會(huì )被忽略并對基本日期時(shí)間值進(jìn)行比較。 如果兩個(gè)比較方都是感知型且具有不同的 tzinfo 屬性，則兩個(gè)比較方將首先通過(guò)減去它們的 UTC 差值（使用 self.utcoffset() 獲?。﹣?lái)進(jìn)行調整。

   在 3.3 版更改: 感知型和簡(jiǎn)單型 datetime 實(shí)例之間的相等比較不會(huì )引發(fā) TypeError。

   備注

   為了防止比較操作回退為默認的對象地址比較方式，datetime 比較通常會(huì )引發(fā) TypeError，如果比較目標不同樣為 datetime 對象的話(huà)。 不過(guò)也可能會(huì )返回 NotImplemented，如果比較目標具有 timetuple() 屬性的話(huà)。 這個(gè)鉤子給予其他種類(lèi)的日期對象實(shí)現混合類(lèi)型比較的機會(huì )。 如果未實(shí)現，則當 datetime 對象與不同類(lèi)型比較時(shí)將會(huì )引發(fā) TypeError，除非是 == 或 != 比較。 后兩種情況將分別返回 False 或 True。

實(shí)例方法：

datetime.date()?

返回具有同樣 year, month 和 day 值的 date 對象。

datetime.time()?

返回具有同樣 hour, minute, second, microsecond 和 fold 值的 time 對象。 tzinfo 值為 None。 另請參見(jiàn) timetz() 方法。

在 3.6 版更改: fold 值會(huì )被復制給返回的 time 對象。

datetime.timetz()?

返回具有同樣 hour, minute, second, microsecond, fold 和 tzinfo 屬性性的 time 對象。 另請參見(jiàn) time() 方法。

在 3.6 版更改: fold 值會(huì )被復制給返回的 time 對象。

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=0)?

返回一個(gè)具有同樣屬性值的 datetime，除非通過(guò)任何關(guān)鍵字參數為某些屬性指定了新值。 請注意可以通過(guò)指定 tzinfo=None 來(lái)從一個(gè)感知型 datetime 創(chuàng )建一個(gè)簡(jiǎn)單型 datetime 而不必轉換日期和時(shí)間數據。

3.6 新版功能: 增加了 fold 參數。

datetime.astimezone(tz=None)?

返回一個(gè)具有新的 tzinfo 屬性 tz 的 datetime 對象，并會(huì )調整日期和時(shí)間數據使得結果對應的 UTC 時(shí)間與 self 相同，但為 tz 時(shí)區的本地時(shí)間。

如果給出了 tz，則它必須是一個(gè) tzinfo 子類(lèi)的實(shí)例，并且其 utcoffset() 和 dst() 方法不可返回 None。 如果 self 為簡(jiǎn)單型，它會(huì )被假定為基于系統時(shí)區表示的時(shí)間。

如果調用時(shí)不傳入參數 (或傳入 tz=None) 則將假定目標時(shí)區為系統的本地時(shí)區。 轉換后 datetime 實(shí)例的 .tzinfo 屬性將被設為一個(gè) timezone 實(shí)例，時(shí)區名稱(chēng)和時(shí)差值將從 OS 獲取。

如果 self.tzinfo 為 tz，self.astimezone(tz) 等于 self: 不會(huì )對日期或時(shí)間數據進(jìn)行調整。 否則結果為 tz 時(shí)區的本地時(shí)間，代表的 UTC 時(shí)間與 self 相同：在 astz = dt.astimezone(tz) 之后，astz - astz.utcoffset() 將具有與 dt - dt.utcoffset() 相同的日期和時(shí)間數據。

如果你只是想要附加一個(gè)時(shí)區對象 tz 到一個(gè) datetime 對象 dt 而不調整日期和時(shí)間數據，請使用 dt.replace(tzinfo=tz)。 如果你只想從一個(gè)感知型 datetime 對象 dt 移除時(shí)區對象，請使用 dt.replace(tzinfo=None)。

請注意默認的 tzinfo.fromutc() 方法在 tzinfo 的子類(lèi)中可以被重載，從而影響 astimezone() 的返回結果。 如果忽略出錯的情況，astimezone() 的行為就類(lèi)似于:

def astimezone(self, tz):
    if self.tzinfo is tz:
        return self
    # Convert self to UTC, and attach the new time zone object.
    utc = (self - self.utcoffset()).replace(tzinfo=tz)
    # Convert from UTC to tz's local time.
    return tz.fromutc(utc)

在 3.3 版更改: tz 現在可以被省略。

在 3.6 版更改: astimezone() 方法可以由簡(jiǎn)單型實(shí)例調用，這將假定其表示本地時(shí)間。

datetime.utcoffset()?

如果 tzinfo 為 None，則返回 None，否則返回 self.tzinfo.utcoffset(self)，并且在后者不返回 None 或者一個(gè)幅度小于一天的 timedelta 對象時(shí)將引發(fā)異常。

在 3.7 版更改: UTC 時(shí)差不再限制為一個(gè)整數分鐘值。

datetime.dst()?

如果 tzinfo 為 None，則返回 None，否則返回 self.tzinfo.dst(self)，并且在后者不返回 None 或者一個(gè)幅度小于一天的 timedelta 對象時(shí)將引發(fā)異常。

在 3.7 版更改: DST 差值不再限制為一個(gè)整數分鐘值。

datetime.tzname()?

如果 tzinfo 為 None，則返回 None，否則返回 self.tzinfo.tzname(self)，如果后者不返回 None 或者一個(gè)字符串對象則將引發(fā)異常。

datetime.timetuple()?

返回一個(gè) time.struct_time，即 time.localtime() 所返回的類(lèi)型。

d.timetuple() 等價(jià)于:

time.struct_time((d.year, d.month, d.day,
                  d.hour, d.minute, d.second,
                  d.weekday(), yday, dst))

其中 yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1 是日期在當前年份中的序號，起始序號 1 表示 1 月 1 日。 結果的 tm_isdst 旗標的設定會(huì )依據 dst() 方法：如果 tzinfo 為 None 或 dst() 返回 None，則 tm_isdst 將設為 -1；否則如果 dst() 返回一個(gè)非零值，則 tm_isdst 將設為 1；在其他情況下 tm_isdst 將設為 0。

datetime.utctimetuple()?

如果 datetime 實(shí)例 d 為簡(jiǎn)單型，這類(lèi)似于 d.timetuple()，不同之處在于 tm_isdst 會(huì )強制設為 0，無(wú)論 d.dst() 返回什么結果。 DST 對于 UTC 時(shí)間永遠無(wú)效。

如果 d 為感知型， d 會(huì )通過(guò)減去 d.utcoffset() 來(lái)標準化為 UTC 時(shí)間，并返回該標準化時(shí)間所對應的 time.struct_time。 tm_isdst 會(huì )強制設為 0。 請注意如果 d.year 為 MINYEAR 或 MAXYEAR 并且 UTC 調整超出一年的邊界則可能引發(fā) OverflowError。

警告

由于簡(jiǎn)單型 datetime 對象會(huì )被許多 datetime 方法當作本地時(shí)間來(lái)處理，最好是使用感知型日期時(shí)間來(lái)表示 UTC 時(shí)間；因此，使用 utcfromtimetuple 可能會(huì )給出誤導性的結果。 如果你有一個(gè)表示 UTC 的簡(jiǎn)單型 datetime，請使用 datetime.replace(tzinfo=timezone.utc) 將其改為感知型，這樣你才能使用 datetime.timetuple()。

datetime.toordinal()?

返回日期的預期格列高利歷序號。 與 self.date().toordinal() 相同。

datetime.timestamp()?

返回對應于 datetime 實(shí)例的 POSIX 時(shí)間戳。 此返回值是與 time.time() 返回值類(lèi)似的 float 對象。

簡(jiǎn)單型 datetime 實(shí)例會(huì )假定為代表本地時(shí)間，并且此方法依賴(lài)于平臺的 C mktime() 函數來(lái)執行轉換。 由于在許多平臺上 datetime 支持的范圍比 mktime() 更廣，對于極其遙遠的過(guò)去或未來(lái)此方法可能引發(fā) OverflowError。

對于感知型 datetime 實(shí)例，返回值的計算方式為:

(dt - datetime(1970, 1, 1, tzinfo=timezone.utc)).total_seconds()

3.3 新版功能.

在 3.6 版更改: timestamp() 方法使用 fold 屬性來(lái)消除重復間隔中的時(shí)間歧義。

備注

沒(méi)有一個(gè)方法能直接從表示 UTC 時(shí)間的簡(jiǎn)單型 datetime 實(shí)例獲取 POSIX 時(shí)間戳。 如果你的應用程序使用此慣例并且你的系統時(shí)區不是設為 UTC，你可以通過(guò)提供 tzinfo=timezone.utc 來(lái)獲取 POSIX 時(shí)間戳:

timestamp = dt.replace(tzinfo=timezone.utc).timestamp()

或者通過(guò)直接計算時(shí)間戳:

timestamp = (dt - datetime(1970, 1, 1)) / timedelta(seconds=1)

datetime.weekday()?

返回一個(gè)整數代表星期幾，星期一為 0，星期天為 6。 相當于 self.date().weekday()。 另請參閱 isoweekday()。

datetime.isoweekday()?

返回一個(gè)整數代表星期幾，星期一為 1，星期天為 7。 相當于 self.date().isoweekday()。 另請參閱 weekday(), isocalendar()。

datetime.isocalendar()?

返回一個(gè)由三部分組成的 named tuple: year, week 和 weekday。 等同于 self.date().isocalendar()。

datetime.isoformat(sep='T', timespec='auto')?

返回一個(gè)以 ISO 8601 格式表示的日期和時(shí)間字符串：

• YYYY-MM-DDTHH:MM:SS.ffffff，如果 microsecond 不為 0

• YYYY-MM-DDTHH:MM:SS，如果 microsecond 為 0

如果 utcoffset() 返回值不為 None，則添加一個(gè)字符串來(lái)給出 UTC 時(shí)差：

• YYYY-MM-DDTHH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]，如果 microsecond 不為 0

• YYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]]，如果 microsecond 為 0

示例:

>>>

>>> from datetime import datetime, timezone
>>> datetime(2019, 5, 18, 15, 17, 8, 132263).isoformat()
'2019-05-18T15:17:08.132263'
>>> datetime(2019, 5, 18, 15, 17, tzinfo=timezone.utc).isoformat()
'2019-05-18T15:17:00+00:00'

可選參數 sep (默認為 'T') 為單個(gè)分隔字符，會(huì )被放在結果的日期和時(shí)間兩部分之間。 例如:

>>>

>>> from datetime import tzinfo, timedelta, datetime
>>> class TZ(tzinfo):
...     """A time zone with an arbitrary, constant -06:39 offset."""
...     def utcoffset(self, dt):
...         return timedelta(hours=-6, minutes=-39)
...
>>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
'2002-12-25 00:00:00-06:39'
>>> datetime(2009, 11, 27, microsecond=100, tzinfo=TZ()).isoformat()
'2009-11-27T00:00:00.000100-06:39'

可選參數 timespec 要包含的額外時(shí)間組件值 (默認為 'auto')。它可以是以下值之一：

• 'auto': 如果 microsecond 為 0 則與 'seconds' 相同，否則與 'microseconds' 相同。

• 'hours': 以?xún)蓚€(gè)數碼的 HH 格式 包含 hour。

• 'minutes': 以 HH:MM 格式包含 hour 和 minute。

• 'seconds': 以 HH:MM:SS 格式包含 hour, minute 和 second。

• 'milliseconds': 包含完整時(shí)間，但將秒值的小數部分截斷至微秒。 格式為 HH:MM:SS.sss

• 'microseconds': 以 HH:MM:SS.ffffff 格式包含完整時(shí)間。

備注

排除掉的時(shí)間部分將被截斷，而不是被舍入。

對于無(wú)效的 timespec 參數將引發(fā) ValueError:

>>>

>>> from datetime import datetime
>>> datetime.now().isoformat(timespec='minutes')   
'2002-12-25T00:00'
>>> dt = datetime(2015, 1, 1, 12, 30, 59, 0)
>>> dt.isoformat(timespec='microseconds')
'2015-01-01T12:30:59.000000'

3.6 新版功能: 增加了 timespec 參數。

datetime.__str__()?

對于 datetime 實(shí)例 d，str(d) 等價(jià)于 d.isoformat(' ')。

datetime.ctime()?

返回一個(gè)表示日期和時(shí)間的字符串:

>>>

>>> from datetime import datetime
>>> datetime(2002, 12, 4, 20, 30, 40).ctime()
'Wed Dec  4 20:30:40 2002'

輸出字符串將 并不 包括時(shí)區信息，無(wú)論輸入的是感知型還是簡(jiǎn)單型。

d.ctime() 等效于:

time.ctime(time.mktime(d.timetuple()))

在原生 C ctime() 函數 (time.ctime() 會(huì )發(fā)起調用該函數，但 datetime.ctime() 則不會(huì )) 遵循 C 標準的平臺上。

datetime.strftime(format)?

返回一個(gè)由顯式格式字符串所指明的代表日期和時(shí)間的字符串，要獲取格式指令的完整列表，請參閱 strftime() 和 strptime() 的行為。

datetime.__format__(format)?

與 datetime.strftime() 相同。 此方法使得為 datetime 對象指定以 格式化字符串字面值 表示的格式化字符串以及使用 str.format() 進(jìn)行格式化成為可能。 要獲取格式指令的完整列表，請參閱 strftime() 和 strptime() 的行為。

>>> from datetime import datetime, date, time, timezone

>>> # Using datetime.combine()
>>> d = date(2005, 7, 14)
>>> t = time(12, 30)
>>> datetime.combine(d, t)
datetime.datetime(2005, 7, 14, 12, 30)

>>> # Using datetime.now()
>>> datetime.now()   
datetime.datetime(2007, 12, 6, 16, 29, 43, 79043)   # GMT +1
>>> datetime.now(timezone.utc)   
datetime.datetime(2007, 12, 6, 15, 29, 43, 79060, tzinfo=datetime.timezone.utc)

>>> # Using datetime.strptime()
>>> dt = datetime.strptime("21/11/06 16:30", "%d/%m/%y %H:%M")
>>> dt
datetime.datetime(2006, 11, 21, 16, 30)

>>> # Using datetime.timetuple() to get tuple of all attributes
>>> tt = dt.timetuple()
>>> for it in tt:   
...     print(it)
...
2006    # year
11      # month
21      # day
16      # hour
30      # minute
0       # second
1       # weekday (0 = Monday)
325     # number of days since 1st January
-1      # dst - method tzinfo.dst() returned None

>>> # Date in ISO format
>>> ic = dt.isocalendar()
>>> for it in ic:   
...     print(it)
...
2006    # ISO year
47      # ISO week
2       # ISO weekday

>>> # Formatting a datetime
>>> dt.strftime("%A, %d. %B %Y %I:%M%p")
'Tuesday, 21. November 2006 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.'

from datetime import timedelta, datetime, tzinfo, timezone

class KabulTz(tzinfo):
    # Kabul used +4 until 1945, when they moved to +4:30
    UTC_MOVE_DATE = datetime(1944, 12, 31, 20, tzinfo=timezone.utc)

    def utcoffset(self, dt):
        if dt.year < 1945:
            return timedelta(hours=4)
        elif (1945, 1, 1, 0, 0) <= dt.timetuple()[:5] < (1945, 1, 1, 0, 30):
            # An ambiguous ("imaginary") half-hour range representing
            # a 'fold' in time due to the shift from +4 to +4:30.
            # If dt falls in the imaginary range, use fold to decide how
            # to resolve. See PEP495.
            return timedelta(hours=4, minutes=(30 if dt.fold else 0))
        else:
            return timedelta(hours=4, minutes=30)

    def fromutc(self, dt):
        # Follow same validations as in datetime.tzinfo
        if not isinstance(dt, datetime):
            raise TypeError("fromutc() requires a datetime argument")
        if dt.tzinfo is not self:
            raise ValueError("dt.tzinfo is not self")

        # A custom implementation is required for fromutc as
        # the input to this function is a datetime with utc values
        # but with a tzinfo set to self.
        # See datetime.astimezone or fromtimestamp.
        if dt.replace(tzinfo=timezone.utc) >= self.UTC_MOVE_DATE:
            return dt + timedelta(hours=4, minutes=30)
        else:
            return dt + timedelta(hours=4)

    def dst(self, dt):
        # Kabul does not observe daylight saving time.
        return timedelta(0)

    def tzname(self, dt):
        if dt >= self.UTC_MOVE_DATE:
            return "+04:30"
        return "+04"

>>> tz1 = KabulTz()

>>> # Datetime before the change
>>> dt1 = datetime(1900, 11, 21, 16, 30, tzinfo=tz1)
>>> print(dt1.utcoffset())
4:00:00

>>> # Datetime after the change
>>> dt2 = datetime(2006, 6, 14, 13, 0, tzinfo=tz1)
>>> print(dt2.utcoffset())
4:30:00

>>> # Convert datetime to another time zone
>>> dt3 = dt2.astimezone(timezone.utc)
>>> dt3
datetime.datetime(2006, 6, 14, 8, 30, tzinfo=datetime.timezone.utc)
>>> dt2
datetime.datetime(2006, 6, 14, 13, 0, tzinfo=KabulTz())
>>> dt2 == dt3
True

time 對象?

一個(gè) time 對象代表某日的（本地）時(shí)間，它獨立于任何特定日期，并可通過(guò) tzinfo 對象來(lái)調整。

class datetime.time(hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)?

所有參數都是可選的。 tzinfo 可以是 None，或者是一個(gè) tzinfo 子類(lèi)的實(shí)例。 其余的參數必須是在下面范圍內的整數：

• 0 <= hour < 24,

• 0 <= minute < 60,

• 0 <= second < 60,

• 0 <= microsecond < 1000000,

• fold in [0, 1].

如果給出一個(gè)此范圍以外的參數，則會(huì )引發(fā) ValueError。 所有參數值默認為 0，只有 tzinfo 默認為 None。

類(lèi)屬性：

time.min?

早最的可表示 time, time(0, 0, 0, 0)。

time.max?

最晚的可表示 time, time(23, 59, 59, 999999)。

time.resolution?

兩個(gè)不相等的 time 對象之間可能的最小間隔，timedelta(microseconds=1)，但是請注意 time 對象并不支持算術(shù)運算。

實(shí)例屬性（只讀）：

time.hour?

取值范圍是 range(24)。

time.minute?

取值范圍是 range(60)。

time.second?

取值范圍是 range(60)。

time.microsecond?

取值范圍是 range(1000000)。

time.tzinfo?

作為 tzinfo 參數被傳給 time 構造器的對象，如果沒(méi)有傳入值則為 None。

time.fold?

取值范圍是 [0, 1]。 用于在重復的時(shí)間段中消除邊界時(shí)間歧義。 （當夏令時(shí)結束時(shí)回撥時(shí)鐘或由于政治原因導致當明時(shí)區的 UTC 時(shí)差減少就會(huì )出現重復的時(shí)間段。） 取值 0 (1) 表示兩個(gè)時(shí)刻早于（晚于）所代表的同一邊界時(shí)間。

3.6 新版功能.

time 對象支持 time 與 time 的比較，當 a 時(shí)間在 b 之前時(shí)，則認為 a 小于 b。 如果比較的一方是簡(jiǎn)單型而另一方是感知型，則如果嘗試進(jìn)行順序比較將引發(fā) TypeError。 對于相等比較，簡(jiǎn)單型實(shí)例將永遠不等于感知型實(shí)例。

如果兩個(gè)比較方都是感知型，且具有相同的 tzinfo 屬性，相同的 tzinfo 屬性會(huì )被忽略并對基本時(shí)間值進(jìn)行比較。 如果兩個(gè)比較方都是感知型且具有不同的 tzinfo 屬性，兩個(gè)比較方將首先通過(guò)減去它們的 UTC 時(shí)差（從 self.utcoffset() 獲?。﹣?lái)進(jìn)行調整。 為了防止將混合類(lèi)型比較回退為基于對象地址的默認比較，當 time 對象與不同類(lèi)型的對象比較時(shí)，將會(huì )引發(fā) TypeError，除非比較運算符是 == 或 !=。 在后兩種情況下將分別返回 False 或 True。

在布爾運算時(shí)，time 對象總是被視為真值。

其他構造方法：

classmethod time.fromisoformat(time_string)?

Return a time corresponding to a time_string in any valid ISO 8601 format, with the following exceptions:

1. Time zone offsets may have fractional seconds.

2. The leading T, normally required in cases where there may be ambiguity between a date and a time, is not required.

3. Fractional seconds may have any number of digits (anything beyond 6 will be truncated).

4. Fractional hours and minutes are not supported.

示例:

>>>

>>> from datetime import time
>>> time.fromisoformat('04:23:01')
datetime.time(4, 23, 1)
>>> time.fromisoformat('T04:23:01')
datetime.time(4, 23, 1)
>>> time.fromisoformat('T042301')
datetime.time(4, 23, 1)
>>> time.fromisoformat('04:23:01.000384')
datetime.time(4, 23, 1, 384)
>>> time.fromisoformat('04:23:01,000')
datetime.time(4, 23, 1, 384)
>>> time.fromisoformat('04:23:01+04:00')
datetime.time(4, 23, 1, tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))
>>> time.fromisoformat('04:23:01Z')
datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)
>>> time.fromisoformat('04:23:01+00:00')
datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)

3.7 新版功能.

在 3.11 版更改: Previously, this method only supported formats that could be emitted by time.isoformat().

實(shí)例方法：

time.replace(hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=0)?

返回一個(gè)具有同樣屬性值的 time，除非通過(guò)任何關(guān)鍵字參數指定了某些屬性值。 請注意可以通過(guò)指定 tzinfo=None 從一個(gè)感知型 time 創(chuàng )建一個(gè)簡(jiǎn)單型 time，而不必轉換時(shí)間數據。

3.6 新版功能: 增加了 fold 參數。

time.isoformat(timespec='auto')?

返回表示為下列 ISO 8601 格式之一的時(shí)間字符串：

• HH:MM:SS.ffffff，如果 microsecond 不為 0

• HH:MM:SS，如果 microsecond 為 0

• HH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]，如果 utcoffset() 不返回 None

• HH:MM:SS+HH:MM[:SS[.ffffff]]，如果 microsecond 為 0 并且 utcoffset() 不返回 None

可選參數 timespec 要包含的額外時(shí)間組件值 (默認為 'auto')。它可以是以下值之一：

• 'auto': 如果 microsecond 為 0 則與 'seconds' 相同，否則與 'microseconds' 相同。

• 'hours': 以?xún)蓚€(gè)數碼的 HH 格式 包含 hour。

• 'minutes': 以 HH:MM 格式包含 hour 和 minute。

• 'seconds': 以 HH:MM:SS 格式包含 hour, minute 和 second。

• 'milliseconds': 包含完整時(shí)間，但將秒值的小數部分截斷至微秒。 格式為 HH:MM:SS.sss

• 'microseconds': 以 HH:MM:SS.ffffff 格式包含完整時(shí)間。

備注

排除掉的時(shí)間部分將被截斷，而不是被舍入。

對于無(wú)效的 timespec 參數將引發(fā) ValueError。

示例:

>>>

>>> from datetime import time
>>> time(hour=12, minute=34, second=56, microsecond=123456).isoformat(timespec='minutes')
'12:34'
>>> dt = time(hour=12, minute=34, second=56, microsecond=0)
>>> dt.isoformat(timespec='microseconds')
'12:34:56.000000'
>>> dt.isoformat(timespec='auto')
'12:34:56'

3.6 新版功能: 增加了 timespec 參數。

time.__str__()?

對于時(shí)間對象 t, str(t) 等價(jià)于 t.isoformat()。

time.strftime(format)?

返回一個(gè)由顯式格式字符串所指明的代表時(shí)間的字符串。 要獲取格式指令的完整列表，請參閱 strftime() 和 strptime() 的行為。

time.__format__(format)?

與 time.strftime() 相同。 此方法使得為 time 對象指定以 格式化字符串字面值 表示的格式化字符串以及使用 str.format() 進(jìn)行格式化成為可能。 要獲取格式指令的完整列表，請參閱 strftime() 和 strptime() 的行為。

time.utcoffset()?

如果 tzinfo 為 None，則返回 None，否則返回 self.tzinfo.utcoffset(None)，并且在后者不返回 None 或一個(gè)幅度小于一天的 a timedelta 對象時(shí)將引發(fā)異常。

在 3.7 版更改: UTC 時(shí)差不再限制為一個(gè)整數分鐘值。

time.dst()?

如果 tzinfo 為 None，則返回 None，否則返回 self.tzinfo.dst(None)，并且在后者不返回 None 或者一個(gè)幅度小于一天的 timedelta 對象時(shí)將引發(fā)異常。

在 3.7 版更改: DST 差值不再限制為一個(gè)整數分鐘值。

time.tzname()?

如果 tzinfo 為 None，則返回 None，否則返回 self.tzinfo.tzname(None)，如果后者不返回 None 或者一個(gè)字符串對象則將引發(fā)異常。

>>> from datetime import time, tzinfo, timedelta
>>> class TZ1(tzinfo):
...     def utcoffset(self, dt):
...         return timedelta(hours=1)
...     def dst(self, dt):
...         return timedelta(0)
...     def tzname(self,dt):
...         return "+01:00"
...     def  __repr__(self):
...         return f"{self.__class__.__name__}()"
...
>>> t = time(12, 10, 30, tzinfo=TZ1())
>>> t
datetime.time(12, 10, 30, tzinfo=TZ1())
>>> t.isoformat()
'12:10:30+01:00'
>>> t.dst()
datetime.timedelta(0)
>>> t.tzname()
'+01:00'
>>> t.strftime("%H:%M:%S %Z")
'12:10:30 +01:00'
>>> 'The {} is {:%H:%M}.'.format("time", t)
'The time is 12:10.'

tzinfo 對象?

class datetime.tzinfo?

這是一個(gè)抽象基類(lèi)，也就是說(shuō)該類(lèi)不應被直接實(shí)例化。 請定義 tzinfo 的子類(lèi)來(lái)捕獲有關(guān)特定時(shí)區的信息。

tzinfo 的（某個(gè)實(shí)體子類(lèi)）的實(shí)例可以被傳給 datetime 和 time 對象的構造器。 這些對象會(huì )將它們的屬性視為對應于本地時(shí)間，并且 tzinfo 對象支持展示本地時(shí)間與 UTC 的差值、時(shí)區名稱(chēng)以及 DST 差值的方法，都是與傳給它們的日期或時(shí)間對象的相對值。

你需要派生一個(gè)實(shí)體子類(lèi)，并且（至少）提供你使用 datetime 方法所需要的標準 tzinfo 方法的實(shí)現。 datetime 模塊提供了 timezone，這是 tzinfo 的一個(gè)簡(jiǎn)單實(shí)體子類(lèi)，它能以與 UTC 的固定差值來(lái)表示不同的時(shí)區，例如 UTC 本身或北美的 EST 和 EDT。

對于封存操作的特殊要求：一個(gè) tzinfo 子類(lèi)必須具有可不帶參數調用的 __init__() 方法，否則它雖然可以被封存，但可能無(wú)法再次解封。 這是個(gè)技術(shù)性要求，在未來(lái)可能會(huì )被取消。

一個(gè) tzinfo 的實(shí)體子類(lèi)可能需要實(shí)現以下方法。 具體需要實(shí)現的方法取決于感知型 datetime 對象如何使用它。 如果有疑問(wèn)，可以簡(jiǎn)單地全都實(shí)現。

tzinfo.utcoffset(dt)?

將本地時(shí)間與 UTC 時(shí)差返回為一個(gè) timedelta 對象，如果本地時(shí)區在 UTC 以東則為正值。 如果本地時(shí)區在 UTC 以西則為負值。

這表示與 UTC 的 總計 時(shí)差；舉例來(lái)說(shuō)，如果一個(gè) tzinfo 對象同時(shí)代表時(shí)區和 DST 調整，則 utcoffset() 應當返回兩者的和。 如果 UTC 時(shí)差不確定則返回 None。 在其他情況下返回值必須為一個(gè) timedelta 對象，其取值嚴格限制于 -timedelta(hours=24) 和 timedelta(hours=24) 之間（差值的幅度必須小于一天）。 大多數 utcoffset() 的實(shí)現看起來(lái)可能像是以下兩者之一:

return CONSTANT                 # fixed-offset class
return CONSTANT + self.dst(dt)  # daylight-aware class

如果 utcoffset() 返回值不為 None，則 dst() 也不應返回 None。

默認的 utcoffset() 實(shí)現會(huì )引發(fā) NotImplementedError。

在 3.7 版更改: UTC 時(shí)差不再限制為一個(gè)整數分鐘值。

tzinfo.dst(dt)?

將夏令時(shí)（DST）調整返回為一個(gè) timedelta 對象，如果 DST 信息未知則返回 None。

如果 DST 未啟用則返回 timedelta(0)。 如果 DST 已啟用則將差值作為一個(gè) timedelta 對象返回（參見(jiàn) utcoffset() 了解詳情）。 請注意 DST 差值如果可用，就會(huì )直接被加入 utcoffset() 所返回的 UTC 時(shí)差，因此無(wú)需額外查詢(xún) dst() 除非你希望單獨獲取 DST 信息。 例如，datetime.timetuple() 會(huì )調用其 tzinfo 屬性的 dst() 方法來(lái)確定應該如何設置 tm_isdst 旗標，而 tzinfo.fromutc() 會(huì )調用 dst() 來(lái)在跨越時(shí)區時(shí)處理 DST 的改變。

一個(gè)可以同時(shí)處理標準時(shí)和夏令時(shí)的 tzinfo 子類(lèi)的實(shí)例 tz 必須在此情形中保持一致：

tz.utcoffset(dt) - tz.dst(dt)

必須為具有同樣的 tzinfo 子類(lèi)實(shí)例且 dt.tzinfo == tz 的每個(gè) datetime 對象 dt 返回同樣的結果，此表達式會(huì )產(chǎn)生時(shí)區的“標準時(shí)差”，它不應取決于具體日期或時(shí)間，只取決于地理位置。 datetime.astimezone() 的實(shí)現依賴(lài)此方法，但無(wú)法檢測違反規則的情況；確保符合規則是程序員的責任。 如果一個(gè) tzinfo 子類(lèi)不能保證這一點(diǎn)，也許可以重載 tzinfo.fromutc() 的默認實(shí)現以便在任何情況下與 astimezone() 正確配合。

大多數 dst() 的實(shí)現可能會(huì )如以下兩者之一:

def dst(self, dt):
    # a fixed-offset class:  doesn't account for DST
    return timedelta(0)

或者：

def dst(self, dt):
    # Code to set dston and dstoff to the time zone's DST
    # transition times based on the input dt.year, and expressed
    # in standard local time.

    if dston <= dt.replace(tzinfo=None) < dstoff:
        return timedelta(hours=1)
    else:
        return timedelta(0)

默認的 dst() 實(shí)現會(huì )引發(fā) NotImplementedError。

在 3.7 版更改: DST 差值不再限制為一個(gè)整數分鐘值。

tzinfo.tzname(dt)?

將對應于 datetime 對象 dt 的時(shí)區名稱(chēng)作為字符串返回。 datetime 模塊沒(méi)有定義任何字符串名稱(chēng)相關(guān)內容，也不要求名稱(chēng)有任何特定含義。 例如 "GMT", "UTC", "-500", "-5:00", "EDT", "US/Eastern", "America/New York" 都是有效的返回值。 如果字符串名稱(chēng)未知則返回 None。 請注意這是一個(gè)方法而不是一個(gè)固定的字符串，這主要是因為某些 tzinfo 子類(lèi)可能需要根據所傳入的特定 dt 值返回不同的名稱(chēng)，特別是當 tzinfo 類(lèi)要負責處理夏令時(shí)的時(shí)候。

默認的 tzname() 實(shí)現會(huì )引發(fā) NotImplementedError。

這些方法會(huì )被 datetime 或 time 對象調用，用來(lái)與它們的同名方法相對應。 datetime 對象會(huì )將自身作為傳入參數，而 time 對象會(huì )將 None 作為傳入參數。 這樣 tzinfo 子類(lèi)的方法應當準備好接受 dt 參數值為 None 或是 datetime 類(lèi)的實(shí)例。

當傳入 None 時(shí)，應當由類(lèi)的設計者來(lái)決定最佳回應方式。 例如，返回 None 適用于希望該類(lèi)提示時(shí)間對象不參與 tzinfo 協(xié)議處理。 讓 utcoffset(None) 返回標準 UTC 時(shí)差也許會(huì )更有用處，因為并沒(méi)有其他可用于發(fā)現標準時(shí)差的約定慣例。

當傳入一個(gè) datetime 對象來(lái)回應 datetime 方法時(shí)，dt.tzinfo 與 self 是同一對象。 tzinfo 方法可以依賴(lài)這一點(diǎn)，除非用戶(hù)代碼直接調用了 tzinfo 方法。 此行為的目的是使得 tzinfo 方法將 dt 解讀為本地時(shí)間，而不需要擔心其他時(shí)區的相關(guān)對象。

還有一個(gè)額外的 tzinfo 方法，某個(gè)子類(lèi)可能會(huì )希望重載它：

tzinfo.fromutc(dt)?

此方法會(huì )由默認的 datetime.astimezone() 實(shí)現來(lái)調用。 當被其調用時(shí)，dt.tzinfo 為 self，并且 dt 的日期和時(shí)間數據會(huì )被視為表示 UTC 時(shí)間，fromutc() 的目標是調整日期和時(shí)間數據，返回一個(gè)等價(jià)的 datetime 來(lái)表示 self 的本地時(shí)間。

大多數 tzinfo 子類(lèi)應該能夠毫無(wú)問(wèn)題地繼承默認的 fromutc() 實(shí)現。 它的健壯性足以處理固定差值的時(shí)區以及同時(shí)負責標準時(shí)和夏令時(shí)的時(shí)區，對于后者甚至還能處理 DST 轉換時(shí)間在各個(gè)年份有變化的情況。 一個(gè)默認 fromutc() 實(shí)現可能無(wú)法在所有情況下正確處理的例子是（與 UTC 的）標準時(shí)差取決于所經(jīng)過(guò)的特定日期和時(shí)間，這種情況可能由于政治原因而出現。 默認的 astimezone() 和 fromutc() 實(shí)現可能無(wú)法生成你希望的結果，如果這個(gè)結果恰好是跨越了標準時(shí)差發(fā)生改變的時(shí)刻當中的某個(gè)小時(shí)值的話(huà)。

忽略針對錯誤情況的代碼，默認 fromutc() 實(shí)現的行為方式如下:

def fromutc(self, dt):
    # raise ValueError error if dt.tzinfo is not self
    dtoff = dt.utcoffset()
    dtdst = dt.dst()
    # raise ValueError if dtoff is None or dtdst is None
    delta = dtoff - dtdst  # this is self's standard offset
    if delta:
        dt += delta   # convert to standard local time
        dtdst = dt.dst()
        # raise ValueError if dtdst is None
    if dtdst:
        return dt + dtdst
    else:
        return dt

在以下 tzinfo_examples.py 文件中有一些 tzinfo 類(lèi)的例子：

from datetime import tzinfo, timedelta, datetime

ZERO = timedelta(0)
HOUR = timedelta(hours=1)
SECOND = timedelta(seconds=1)

# A class capturing the platform's idea of local time.
# (May result in wrong values on historical times in
#  timezones where UTC offset and/or the DST rules had
#  changed in the past.)
import time as _time

STDOFFSET = timedelta(seconds = -_time.timezone)
if _time.daylight:
    DSTOFFSET = timedelta(seconds = -_time.altzone)
else:
    DSTOFFSET = STDOFFSET

DSTDIFF = DSTOFFSET - STDOFFSET

class LocalTimezone(tzinfo):

    def fromutc(self, dt):
        assert dt.tzinfo is self
        stamp = (dt - datetime(1970, 1, 1, tzinfo=self)) // SECOND
        args = _time.localtime(stamp)[:6]
        dst_diff = DSTDIFF // SECOND
        # Detect fold
        fold = (args == _time.localtime(stamp - dst_diff))
        return datetime(*args, microsecond=dt.microsecond,
                        tzinfo=self, fold=fold)

    def utcoffset(self, dt):
        if self._isdst(dt):
            return DSTOFFSET
        else:
            return STDOFFSET

    def dst(self, dt):
        if self._isdst(dt):
            return DSTDIFF
        else:
            return ZERO

    def tzname(self, dt):
        return _time.tzname[self._isdst(dt)]

    def _isdst(self, dt):
        tt = (dt.year, dt.month, dt.day,
              dt.hour, dt.minute, dt.second,
              dt.weekday(), 0, 0)
        stamp = _time.mktime(tt)
        tt = _time.localtime(stamp)
        return tt.tm_isdst > 0

Local = LocalTimezone()


# A complete implementation of current DST rules for major US time zones.

def first_sunday_on_or_after(dt):
    days_to_go = 6 - dt.weekday()
    if days_to_go:
        dt += timedelta(days_to_go)
    return dt


# US DST Rules
#
# This is a simplified (i.e., wrong for a few cases) set of rules for US
# DST start and end times. For a complete and up-to-date set of DST rules
# and timezone definitions, visit the Olson Database (or try pytz):
# http://www.twinsun.com/tz/tz-link.htm
# http://sourceforge.net/projects/pytz/ (might not be up-to-date)
#
# In the US, since 2007, DST starts at 2am (standard time) on the second
# Sunday in March, which is the first Sunday on or after Mar 8.
DSTSTART_2007 = datetime(1, 3, 8, 2)
# and ends at 2am (DST time) on the first Sunday of Nov.
DSTEND_2007 = datetime(1, 11, 1, 2)
# From 1987 to 2006, DST used to start at 2am (standard time) on the first
# Sunday in April and to end at 2am (DST time) on the last
# Sunday of October, which is the first Sunday on or after Oct 25.
DSTSTART_1987_2006 = datetime(1, 4, 1, 2)
DSTEND_1987_2006 = datetime(1, 10, 25, 2)
# From 1967 to 1986, DST used to start at 2am (standard time) on the last
# Sunday in April (the one on or after April 24) and to end at 2am (DST time)
# on the last Sunday of October, which is the first Sunday
# on or after Oct 25.
DSTSTART_1967_1986 = datetime(1, 4, 24, 2)
DSTEND_1967_1986 = DSTEND_1987_2006

def us_dst_range(year):
    # Find start and end times for US DST. For years before 1967, return
    # start = end for no DST.
    if 2006 < year:
        dststart, dstend = DSTSTART_2007, DSTEND_2007
    elif 1986 < year < 2007:
        dststart, dstend = DSTSTART_1987_2006, DSTEND_1987_2006
    elif 1966 < year < 1987:
        dststart, dstend = DSTSTART_1967_1986, DSTEND_1967_1986
    else:
        return (datetime(year, 1, 1), ) * 2

    start = first_sunday_on_or_after(dststart.replace(year=year))
    end = first_sunday_on_or_after(dstend.replace(year=year))
    return start, end


class USTimeZone(tzinfo):

    def __init__(self, hours, reprname, stdname, dstname):
        self.stdoffset = timedelta(hours=hours)
        self.reprname = reprname
        self.stdname = stdname
        self.dstname = dstname

    def __repr__(self):
        return self.reprname

    def tzname(self, dt):
        if self.dst(dt):
            return self.dstname
        else:
            return self.stdname

    def utcoffset(self, dt):
        return self.stdoffset + self.dst(dt)

    def dst(self, dt):
        if dt is None or dt.tzinfo is None:
            # An exception may be sensible here, in one or both cases.
            # It depends on how you want to treat them.  The default
            # fromutc() implementation (called by the default astimezone()
            # implementation) passes a datetime with dt.tzinfo is self.
            return ZERO
        assert dt.tzinfo is self
        start, end = us_dst_range(dt.year)
        # Can't compare naive to aware objects, so strip the timezone from
        # dt first.
        dt = dt.replace(tzinfo=None)
        if start + HOUR <= dt < end - HOUR:
            # DST is in effect.
            return HOUR
        if end - HOUR <= dt < end:
            # Fold (an ambiguous hour): use dt.fold to disambiguate.
            return ZERO if dt.fold else HOUR
        if start <= dt < start + HOUR:
            # Gap (a non-existent hour): reverse the fold rule.
            return HOUR if dt.fold else ZERO
        # DST is off.
        return ZERO

    def fromutc(self, dt):
        assert dt.tzinfo is self
        start, end = us_dst_range(dt.year)
        start = start.replace(tzinfo=self)
        end = end.replace(tzinfo=self)
        std_time = dt + self.stdoffset
        dst_time = std_time + HOUR
        if end <= dst_time < end + HOUR:
            # Repeated hour
            return std_time.replace(fold=1)
        if std_time < start or dst_time >= end:
            # Standard time
            return std_time
        if start <= std_time < end - HOUR:
            # Daylight saving time
            return dst_time


Eastern  = USTimeZone(-5, "Eastern",  "EST", "EDT")
Central  = USTimeZone(-6, "Central",  "CST", "CDT")
Mountain = USTimeZone(-7, "Mountain", "MST", "MDT")
Pacific  = USTimeZone(-8, "Pacific",  "PST", "PDT")

請注意同時(shí)負責標準時(shí)和夏令時(shí)的 tzinfo 子類(lèi)在每年兩次的 DST 轉換點(diǎn)上會(huì )出現不可避免的微妙問(wèn)題。具體而言，考慮美國東部時(shí)區 (UTC -0500)，它的 EDT 從三月的第二個(gè)星期天 1:59 (EST) 之后一分鐘開(kāi)始，并在十一月的第一天星期天 1:59 (EDT) 之后一分鐘結束:

  UTC   3:MM  4:MM  5:MM  6:MM  7:MM  8:MM
  EST  22:MM 23:MM  0:MM  1:MM  2:MM  3:MM
  EDT  23:MM  0:MM  1:MM  2:MM  3:MM  4:MM

start  22:MM 23:MM  0:MM  1:MM  3:MM  4:MM

  end  23:MM  0:MM  1:MM  1:MM  2:MM  3:MM

當 DST 開(kāi)始時(shí)（即 "start" 行），本地時(shí)鐘從 1:59 跳到 3:00。 形式為 2:MM 的時(shí)間值在那一天是沒(méi)有意義的，因此在 DST 開(kāi)始那一天 astimezone(Eastern) 不會(huì )輸出包含 hour == 2 的結果。 例如，在 2016 年春季時(shí)鐘向前調整時(shí)，我們得到:

>>> from datetime import datetime, timezone
>>> from tzinfo_examples import HOUR, Eastern
>>> u0 = datetime(2016, 3, 13, 5, tzinfo=timezone.utc)
>>> for i in range(4):
...     u = u0 + i*HOUR
...     t = u.astimezone(Eastern)
...     print(u.time(), 'UTC =', t.time(), t.tzname())
...
05:00:00 UTC = 00:00:00 EST
06:00:00 UTC = 01:00:00 EST
07:00:00 UTC = 03:00:00 EDT
08:00:00 UTC = 04:00:00 EDT

當 DST 結束時(shí)（見(jiàn) "end" 行），會(huì )有更糟糕的潛在問(wèn)題：本地時(shí)間值中有一個(gè)小時(shí)是不可能沒(méi)有歧義的：夏令時(shí)的最后一小時(shí)。 即以北美東部時(shí)間表示當天夏令時(shí)結束時(shí)的形式為 5:MM UTC 的時(shí)間。 本地時(shí)鐘從 1:59 (夏令時(shí)) 再次跳回到 1:00 (標準時(shí))。 形式為 1:MM 的本地時(shí)間就是有歧義的。 此時(shí) astimezone() 是通過(guò)將兩個(gè)相鄰的 UTC 小時(shí)映射到兩個(gè)相同的本地小時(shí)來(lái)模仿本地時(shí)鐘的行為。 在這個(gè)北美東部時(shí)間的示例中，形式為 5:MM 和 6:MM 的 UTC 時(shí)間在轉換為北美東部時(shí)間時(shí)都將被映射到 1:MM，但前一個(gè)時(shí)間會(huì )將 fold 屬性設為 0 而后一個(gè)時(shí)間會(huì )將其設為 1。 例如，在 2016 年秋季時(shí)鐘往回調整時(shí)，我們得到:

>>> u0 = datetime(2016, 11, 6, 4, tzinfo=timezone.utc)
>>> for i in range(4):
...     u = u0 + i*HOUR
...     t = u.astimezone(Eastern)
...     print(u.time(), 'UTC =', t.time(), t.tzname(), t.fold)
...
04:00:00 UTC = 00:00:00 EDT 0
05:00:00 UTC = 01:00:00 EDT 0
06:00:00 UTC = 01:00:00 EST 1
07:00:00 UTC = 02:00:00 EST 0

請注意不同的 datetime 實(shí)例僅通過(guò) fold 屬性值來(lái)加以區分，它們在比較時(shí)會(huì )被視為相等。

不允許時(shí)間顯示存在歧義的應用需要顯式地檢查 fold 屬性的值，或者避免使用混合式的 tzinfo 子類(lèi)；當使用 timezone 或者任何其他固定差值的 tzinfo 子類(lèi)例如僅表示 EST（固定差值 -5 小時(shí)）或僅表示 EDT（固定差值 -4 小時(shí)）的類(lèi)時(shí)是不會(huì )有歧義的。

timezone 對象?

timezone 類(lèi)是 tzinfo 的子類(lèi)，它的每個(gè)實(shí)例都代表一個(gè)以與 UTC 的固定時(shí)差來(lái)定義的時(shí)區。

此類(lèi)的對象不可被用于代表某些特殊地點(diǎn)的時(shí)區信息，這些地點(diǎn)在一年的不同日期會(huì )使用不同的時(shí)差，或是在歷史上對民用時(shí)間進(jìn)行過(guò)調整。

class datetime.timezone(offset, name=None)?

offset 參數必須指定為一個(gè) timedelta 對象，表示本地時(shí)間與 UTC 的時(shí)差。 它必須嚴格限制于 -timedelta(hours=24) 和 timedelta(hours=24) 之間，否則會(huì )引發(fā) ValueError。

name 參數是可選的。 如果指定則必須為一個(gè)字符串，它將被用作 datetime.tzname() 方法的返回值。

3.2 新版功能.

在 3.7 版更改: UTC 時(shí)差不再限制為一個(gè)整數分鐘值。