datetime —- 基本日期和时间类型

datetime —- 基本日期和时间类型

源代码： Lib/datetime.py

datetime 模块提供用于处理日期和时间的类。

在支持日期时间数学运算的同时，实现的关注点更着重于如何能够更有效地解析其属性用于格式化输出和数据操作。

小技巧

跳到 格式代码。

参见

模块 calendar

通用日历相关函数

模块 time

时间的访问和转换

zoneinfo 模块

代表 IANA 时区数据库的具体时区。

dateutil 包

具有扩展时区和解析支持的第三方库。

DateType 软件包

这个第三方库引入了几种独特的静态类型的第三方库，例如允许静态类型检查器区分简单型和感知型日期时间。

感知型对象和简单型对象

日期和时间对象可以根据它们是否包含时区信息而分为“感知型”和“简单型”两类。

充分掌握应用性算法和政治性时间调整信息例如时区和夏令时的情况下，一个 感知型 对象就能相对于其他感知型对象来精确定位自身时间点。 感知型对象是用来表示一个没有解释空间的固定时间点。 1

简单型 对象没有包含足够多的信息来无歧义地相对于其他 date/time 对象来定位自身时间点。 不论一个简单型对象所代表的是世界标准时间（UTC）、当地时间还是某个其他时区的时间完全取决于具体程序，就像一个特定数字所代表的是米、英里还是质量完全取决于具体程序一样。 简单型对象更易于理解和使用，代价则是忽略了某些现实性考量。

对于要求感知型对象的应用，datetime 和 time 对象具有一个可选的时区信息属性 tzinfo，它可被设为抽象类 tzinfo 的子类的一个实例。 这些 tzinfo 对象会捕获与 UTC 时间的差值、时区名称以及夏令时是否生效等信息。

datetime 模块只提供了一个具体的 tzinfo 类，即 timezone 类。 timezone 类可以表示具有相对于 UTC 的固定时差的简单时区，例如 UTC 本身或北美的 EST 和 EDT 时区等。 支持时间的详细程度取决于具体的应用。 世界各地的时间调整规则往往是政治性多于合理性，经常会发生变化，除了 UTC 之外并没有一个能适合所有应用的标准。

常量

The datetime module exports the following constants:

datetime.MINYEAR

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

datetime.MAXYEAR

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

datetime.UTC

UTC 时区单例 datetime.timezone.utc 的别名。

3.11 新版功能.

有效的类型

class datetime.date

一个理想化的简单型日期，它假设当今的公历在过去和未来永远有效。 属性: year, month, and day。

class datetime.time

一个独立于任何特定日期的理想化时间，它假设每一天都恰好等于 246060 秒。 （这里没有“闰秒”的概念。） 包含属性: hour, minute, second, microsecond 和 tzinfo。

class datetime.datetime

日期和时间的结合。属性：year, month, day, hour, minute, second, microsecond, and tzinfo.

class datetime.timedelta

表示两个 date 对象或 time 对象，或者 datetime 对象之间的时间间隔，精确到微秒。

class datetime.tzinfo

一个描述时区信息对象的抽象基类。 用来给 datetime 和 time 类提供自定义的时间调整概念（例如处理时区和/或夏令时）。

class datetime.timezone

一个实现了 tzinfo 抽象基类的子类，用于表示相对于 世界标准时间（UTC）的偏移量。

3.2 新版功能.

这些类型的对象都是不可变的。

子类关系

object
    timedelta
    tzinfo
        timezone
    time
    date
        datetime

通用的特征属性

date, datetime, time 和 timezone 类型共享这些通用特性:

• 这些类型的对象都是不可变的。

• 这些类型的对象是 hashable，意味着它们可以被用作字典的键。

• 这些类型的对象支持通过 pickle 模块进行高效的封存。

确定一个对象是感知型还是简单型

date 类型的对象都是简单型的。

time 或 datetime 类型的对象可以是感知型或者简单型。

一个 datetime 对象 d 在以下条件同时成立时将是感知型的：

1. d.tzinfo 不为 None

2. d.tzinfo.utcoffset(d) 不返回 None

在其他情况下， d 将是简单型的。

一个 time 对象 t 在以下条件同时成立时将是感知型的：

1. t.tzinfo 不为 None

2. t.tzinfo.utcoffset(None) 不返回 None。

在其他情况下， t 将是简单型的。

感知型和简单型之间的区别不适用于 timedelta 对象。

timedelta 类对象

timedelta 对象表示两个 date 或者 time 的时间间隔。

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

所有参数都是可选的并且默认为 0。 这些参数可以是整数或者浮点数，也可以是正数或者负数。

只有 days , seconds 和 microseconds 会存储在内部。 参数单位的换算规则如下：

• 1毫秒会转换成1000微秒。

• 1分钟会转换成60秒。

• 1小时会转换成3600秒。

• 1星期会转换成7天。

日期、秒、微秒都是标准化的，所以它们的表达方式也是唯一的，例：

• 0 <= microseconds < 1000000

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

• -999999999 <= days <= 999999999

下面的例子演示了如何对 days , seconds 和 microseconds 以外的任意参数执行“合并”操作并标准化为以上三个结果属性:

>>> 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)

在有任何参数为浮点型并且 microseconds 值为小数的情况下，从所有参数中余下的微秒数将被合并，并使用四舍五入偶不入奇的规则将总计值舍入到最接近的整数微秒值。 如果没有任何参数为浮点型的情况下，则转换和标准化过程将是完全精确的（不会丢失信息）。

如果标准化后的 days 数值超过了指定范围，将会抛出 OverflowError 异常。

请注意对负数值进行标准化的结果可能会令人感到惊讶。 例如:

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

类属性：

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

两个不相等的 timedelta 类对象最小的间隔为 timedelta(microseconds=1)。

需要注意的是，因为标准化的缘故，timedelta.max > -timedelta.min，-timedelta.max 不可以表示一个 timedelta 类对象。

实例属性（只读）：

支持的运算：

注释：

1. 结果正确，但可能会溢出。

2. 结果正确，不会溢出。

3. 除以0将会抛出异常 ZeroDivisionError 。

4. -timedelta.max 不是一个 timedelta 类对象。

5. timedelta 对象的字符串表示形式类似于其内部表示形式被规范化。对于负时间增量，这会导致一些不寻常的结果。例如:

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

1. 表达式 t2 - t3 通常与 t2 + (-t3) 是等价的，除非 t3 等于 timedelta.max; 在这种情况下前者会返回结果，而后者则会溢出。

除了上面列举的操作以外，timedelta 对象还支持与 date 和 datetime 对象进行特定的相加和相减运算（见下文）。

在 3.2 版更改: 现在已支持 timedelta 对象与另一个 timedelta 对象相整除或相除，包括求余运算和 divmod() 函数。 现在也支持 timedelta 对象加上或乘以一个 float 对象。

支持 timedelta 对象之间进行比较，但其中有一些注意事项。

== 或 != 比较 总是 返回一个 bool 对象，无论被比较的对象是什么类型:

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

对于所有其他比较 (例如 < 和 >)，当一个 timedelta 对象与其他类型的对象比较时，将引发 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) 时则会被视为真值。

实例方法：

timedelta.total_seconds()

返回期间占用了多少秒。等价于 td / timedelta(seconds=1)。对于秒以外的间隔单位，直接使用除法形式 (例如 td / timedelta(microseconds=1))。

需要注意的是，时间间隔较大时，这个方法的结果中的微秒将会失真（大多数平台上大于270年视为一个较大的时间间隔）。

3.2 新版功能.

timedelta 用法示例

一个标准化的附加示例:

>>> # 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

timedelta 算术运算的示例:

>>> 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 对象代表一个理想化历法中的日期（年、月和日），即当今的格列高利历向前后两个方向无限延伸。

公元 1 年 1 月 1日是第 1 日，公元 1 年 1 月 2 日是第 2 日，依此类推。 2

class datetime.date(year , month , day)

所有参数都是必要的。 参数必须是在下面范围内的整数：

• MINYEAR <= year <= MAXYEAR

• 1 <= month <= 12

• 1 <= 日期 <= 给定年月对应的天数

如果参数不在这些范围内，则抛出 ValueError 异常。

其它构造器，所有的类方法：

classmethod date.today()

返回当前的本地日期。

这等价于 date.fromtimestamp(time.time())。

classmethod date.fromtimestamp(timestamp)

返回对应于 POSIX 时间戳的当地时间，例如 time.time() 返回的就是时间戳。

这可能引发 OverflowError，如果时间戳数值超出所在平台 C localtime() 函数的支持范围的话，并且会在 localtime() 出错时引发 OSError。 通常该数值会被限制在 1970 年至 2038 年之间。 请注意在时间戳概念包含闰秒的非 POSIX 系统上，闰秒会被 fromtimestamp() 所忽略。

在 3.3 版更改: 引发 OverflowError 而不是 ValueError，如果时间戳数值超出所在平台 C localtime() 函数的支持范围的话，并会在 localtime() 出错时引发 OSError 而不是 ValueError。

classmethod date.fromordinal(ordinal)

返回对应于预期格列高利历序号的日期，其中公元 1 年 1 月 1 日的序号为 1。

除非 1 <= ordinal <= date.max.toordinal() 否则会引发 ValueError。对于任意日期 d ，date.fromordinal(d.toordinal()) == d。

classmethod date.fromisoformat(date_string)

返回一个对应于以任何有效的 ISO 8601 格式给出的 date_string 的 date，序数日期除外 (如 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 版更改: 在之前版本中，此方法仅支持一种格式 YYYY-MM-DD。

classmethod date.fromisocalendar(year , week , day)

返回指定 year, week 和 day 所对应 ISO 历法日期的 date。 这是函数 date.isocalendar() 的逆操作。

3.8 新版功能.

类属性：

date.min

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

date.max

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

date.resolution

两个日期对象的最小间隔，timedelta(days=1)。

实例属性（只读）：

date.year

在 MINYEAR 和 MAXYEAR 之间，包含边界。

date.month

1 至 12（含）

date.day

返回1到指定年月的天数间的数字。

支持的运算：

注释：

1. 如果 timedelta.days > 0 则 date2 将在时间线上前进，如果 timedelta.days < 0 则将后退。 操作完成后 date2 - date1 == timedelta.days。 timedelta.seconds 和 timedelta.microseconds 会被忽略。 如果 date2.year 将小于 MINYEAR 或大于 MAXYEAR 则会引发 OverflowError。

2. timedelta.seconds 和 timedelta.microseconds 会被忽略。

3. 此值完全精确且不会溢出。 操作完成后 timedelta.seconds 和 timedelta.microseconds 均为 0，并且 date2 + timedelta == date1。

4. 换句话说，当且仅当 date1.toordinal() < date2.toordinal() 时 date1 < date2。 日期比较会引发 TypeError，如果比较目标不为 date 对象的话。 不过也可能会返回 NotImplemented，如果比较目标具有 timetuple() 属性的话。 这个钩子给予其他日期对象类型实现混合类型比较的机会。 否则，当 date 对象与不同类型的对象比较时将会引发 TypeError，除非是 == 或 != 比较。 后两种情况将分别返回 False 或 True。

在布尔运算中，所有 date 对象都会被视为真值。

实例方法：

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

返回一个具有同样值的日期，除非通过任何关键字参数给出了某些形参的新值。

示例:

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

date.timetuple()

返回一个 time.struct_time，即 time.localtime() 所返回的类型。

hours, minutes 和 seconds 值均为 0，且 DST 旗标值为 -1。

d.timetuple() 等价于:

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()

返回一个整数代表星期几，星期一为0，星期天为6。例如， date(2002, 12, 4).weekday() == 2，表示的是星期三。参阅 isoweekday()。

date.isoweekday()

返回一个整数代表星期几，星期一为1，星期天为7。例如：date(2002, 12, 4).isoweekday() == 3,表示星期三。参见 weekday(), isocalendar()。

date.isocalendar()

返回一个由三部分组成的 named tuple 对象: year, week 和 weekday。

ISO 历法是一种被广泛使用的格列高利历。 3

ISO 年由 52 或 53 个完整星期构成，每个星期开始于星期一结束于星期日。 一个 ISO 年的第一个星期就是（格列高利）历法的一年中第一个包含星期四的星期。 这被称为 1 号星期，这个星期四所在的 ISO 年与其所在的格列高利年相同。

例如，2004 年的第一天是星期四，因此 ISO 2004 年的第一个星期开始于 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()

返回一个以 ISO 8601 格式 YYYY-MM-DD 来表示日期的字符串:

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

date.str()

对于日期对象 d , str(d) 等价于 d.isoformat() 。

date.ctime()

返回一个表示日期的字符串:

>>> 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() 会发起调用该函数，但 date.ctime() 则不会) 遵循 C 标准的平台上。

date.strftime(format)

返回一个由显式格式字符串所控制的，代表日期的字符串。 表示时、分或秒的格式代码值将为 0。 另请参阅 strftime() 和 strptime() 的行为 和 date.isoformat()。

date.format(format)

与 date.strftime() 相同。 此方法使得在 格式化字符串字面值 中以及使用 str.format() 时为 date 对象指定格式字符串成为可能。 另请参阅 strftime() 和 strptime() 的行为 和 date.isoformat()。

date 用法示例

计算距离特定事件天数的例子:

>>> 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

使用 date 的更多例子：

>>> 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 对象是包含来自 date 对象和 time 对象的所有信息的单一对象。

与 date 对象一样，datetime 假定当前的格列高利历向前后两个方向无限延伸；与 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 或者是一个 tzinfo 子类的实例。 其余的参数必须是在下面范围内的整数：

• 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 参数。

其它构造器，所有的类方法：

classmethod datetime.today()

返回表示当前地方时的 datetime 对象，其中 tzinfo 为 None。

等价于:

datetime.fromtimestamp(time.time())

另请参阅 now(), fromtimestamp()。

此方法的功能等价于 now()，但是不带 tz 形参。

classmethod datetime.now(tz=None)

返回表示当前地方时的 date 和 time 对象。

如果可选参数 tz 为 None 或未指定，这就类似于 today()，但该方法会在可能的情况下提供比通过 time.time() 时间戳所获时间值更高的精度（例如，在提供了 C gettimeofday() 函数的平台上就可以做到这一点）。

如果 tz 不为 None，它必须是 tzinfo 子类的一个实例，并且当前日期和时间将被转换到 tz 时区。

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

classmethod datetime.utcnow()

返回表示当前 UTC 时间的 date 和 time，其中 tzinfo 为 None。

这类似于 now()，但返回的是当前 UTC 日期和时间，类型为简单型 datetime 对象。 感知型的当前 UTC 日期时间可通过调用 datetime.now(timezone.utc) 来获得。 另请参阅 now()。

警告

由于简单型 datetime 对象会被许多 datetime 方法当作本地时间来处理，最好是使用感知型日期时间对象来表示 UTC 时间。 因此，创建表示当前 UTC 时间的对象的推荐方式是通过调用 datetime.now(timezone.utc)。

3.12 版后已移除: 请用带 UTC 的 datetime.now() 代替。

classmethod datetime.fromtimestamp(timestamp , tz=None)

返回 POSIX 时间戳对应的本地日期和时间，如 time.time() 返回的。 如果可选参数 tz 指定为 None 或未指定，时间戳将转换为平台的本地日期和时间，并且返回的 datetime 对象将为简单型。

如果 tz 不为 None，它必须是 tzinfo 子类的一个实例，并且时间戳将被转换到 tz 指定的时区。

fromtimestamp() 可能会引发 OverflowError，如果时间戳数值超出所在平台 C localtime() 或 gmtime() 函数的支持范围的话，并会在 localtime() 或 gmtime() 报错时引发 OSError。 通常该数值会被限制在 1970 年至 2038 年之间。 请注意在时间戳概念包含闰秒的非 POSIX 系统上，闰秒会被 fromtimestamp() 所忽略，结果可能导致两个相差一秒的时间戳产生相同的 datetime 对象。 相比 utcfromtimestamp() 更推荐使用此方法。

在 3.3 版更改: 引发 OverflowError 而不是 ValueError，如果时间戳数值超出所在平台 C localtime() 或 gmtime() 函数的支持范围的话。 并会在 localtime() 或 gmtime() 出错时引发 OSError 而不是 ValueError。

在 3.6 版更改: fromtimestamp() 可能返回 fold 值设为 1 的实例。

classmethod datetime.utcfromtimestamp(timestamp)

返回对应于 POSIX 时间戳的 UTC datetime，其中 tzinfo 值为 None。 （结果为简单型对象。）

这可能引发 OverflowError，如果时间戳数值超出所在平台 C gmtime() 函数的支持范围的话，并会在 gmtime() 报错时引发 OSError。 通常该数值会被限制在 1970 至 2038 年之间。

要得到一个感知型 datetime 对象，应调用 fromtimestamp():

datetime.fromtimestamp(timestamp, timezone.utc)

在 POSIX 兼容的平台上，它等价于以下表达式:

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

不同之处在于后一种形式总是支持完整年份范围：从 MINYEAR 到 MAXYEAR 的开区间。

警告

由于简单型 datetime 对象会被许多 datetime 方法当作本地时间来处理，最好是使用感知型日期时间对象来表示 UTC 时间。 因此，创建表示特定 UTC 时间戳的日期时间对象的推荐方式是通过调用 datetime.fromtimestamp(timestamp, tz=timezone.utc)。

在 3.3 版更改: 引发 OverflowError 而不是 ValueError，如果时间戳数值超出所在平台 C gmtime() 函数的支持范围的话。 并会在 gmtime() 出错时引发 OSError 而不是 ValueError。

3.12 版后已移除: 请用带 UTC 的 datetime.fromtimestamp() 代替。

classmethod datetime.fromordinal(ordinal)

返回对应于预期格列高利历序号的 datetime，其中公元 1 年 1 月 1 日的序号为 1。 除非 1 <= ordinal <= datetime.max.toordinal() 否则会引发 ValueError。 结果的 hour, minute, second 和 microsecond 值均为 0，并且 tzinfo 值为 None。

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

返回一个新的 datetime 对象，其日期部分等于给定的 date 对象的值，而其时间部分等于给定的 time 对象的值。 如果提供了 tzinfo 参数，其值会被用来设置结果的 tzinfo 属性，否则将使用 time 参数的 tzinfo 属性。 如果 date 参数是一个 datetime 对象，则其时间部分和 tzinfo 属性将被忽略。

对于任意 datetime 对象 d ，d == datetime.combine(d.date(), d.time(), d.tzinfo)。

在 3.6 版更改: 增加了 tzinfo 参数。

classmethod datetime.fromisoformat(date_string)

返回一个对应于以任何有效的 8601 格式给出的 date_string 的 datetime，下列格式除外:

1. 时区时差可能会有带小数的秒值。

2. T 分隔符可以用任何单个 unicode 字符来替换。

3. 目前不支持序数日期。

4. 带小数的时和分是不受支持的。

示例:

>>> 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 版更改: 在之前版本中，此方法仅支持可以由 date.isoformat() 或 datetime.isoformat() 发出的格式。

classmethod datetime.fromisocalendar(year , week , day)

返回以 year, week 和 day 值指明的 ISO 历法日期所对应的 datetime。 该datetime 对象的非日期部分将使用其标准默认值来填充。 这是函数 datetime.isocalendar() 的逆操作。

3.8 新版功能.

classmethod datetime.strptime(date_string , format)

返回一个对应于 date_string ，根据 format 进行解析得到的 datetime 对象。

如果 format 不包含微秒或时区信息，这将等价于:

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

如果 date_string 和 format 无法被 time.strptime() 解析或它返回一个不是时间元组的值则将引发 ValueError。 另请参阅 strftime() 和 strptime() 的行为 和 datetime.fromisoformat()。

类属性：

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 对象之间可能的最小间隔，timedelta(microseconds=1)。

实例属性（只读）：

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 构造器的对象，如果没有传入值则为 None。

datetime.fold

取值范围是 [0, 1]。 用于在重复的时间段中消除边界时间歧义。 （当夏令时结束时回拨时钟或由于政治原因导致当明时区的 UTC 时差减少就会出现重复的时间段。） 取值 0 (1) 表示两个时刻早于（晚于）所代表的同一边界时间。

3.6 新版功能.

支持的运算：

1. datetime2 是从 datetime1 去掉了一段 timedelta 的结果，如果 timedelta.days > 0 则是在时间线上前进，如果 timedelta.days < 0 则是在时间线上后退。 该结果具有与输入的 datetime 相同的 tzinfo 属性，并且操作完成后 datetime2 - datetime1 == timedelta。 如果 datetime2.year 将要小于 MINYEAR 或大于 MAXYEAR 则会引发 OverflowError。 请注意即使输入的是一个感知型对象，该方法也不会进行时区调整。

2. 计算 datetime2 使得 datetime2 + timedelta == datetime1。 与相加操作一样，结果具有与输入的 datetime 相同的 tzinfo 属性，即使输入的是一个感知型对象，该方法也不会进行时区调整。

3. 从一个 datetime 减去一个 datetime 仅对两个操作数均为简单型或均为感知型时有定义。 如果一个是感知型而另一个是简单型，则会引发 TypeError。

如果两个操作数都是简单型，或都是感知型并且具有相同的 tzinfo 属性，则 tzinfo 属性会被忽略，并且结果会是一个使得 datetime2 + t == datetime1 的 timedelta 对象 t 。 在此情况下不会进行时区调整。

如果两个操作数都是感知型且具有不同的 tzinfo 属性，a-b 操作的效果就如同 a 和 b 首先被转换为简单型 UTC 日期时间。 结果将是 (a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None) - b.utcoffset())，除非具体实现绝对不溢出。

1. 当 datetime1 的时间在 datetime2 之前则认为 datetime1 小于 datetime2 。

如果比较的一方是简单型而另一方是感知型，则如果尝试进行顺序比较将引发 TypeError。 对于相等比较，简单型实例将永远不等于感知型实例。

如果两个比较方都是感知型，且具有相同的 tzinfo 属性，则相同的 tzinfo 属性会被忽略并对基本日期时间值进行比较。 如果两个比较方都是感知型且具有不同的 tzinfo 属性，则两个比较方将首先通过减去它们的 UTC 差值（使用 self.utcoffset() 获取）来进行调整。

在 3.3 版更改: 感知型和简单型 datetime 实例之间的相等比较不会引发 TypeError。

备注

为了防止比较操作回退为默认的对象地址比较方式，datetime 比较通常会引发 TypeError，如果比较目标不同样为 datetime 对象的话。 不过也可能会返回 NotImplemented，如果比较目标具有 timetuple() 属性的话。 这个钩子给予其他种类的日期对象实现混合类型比较的机会。 如果未实现，则当 datetime 对象与不同类型比较时将会引发 TypeError，除非是 == 或 != 比较。 后两种情况将分别返回 False 或 True。

实例方法：

datetime.date()

返回具有同样 year, month 和 day 值的 date 对象。

datetime.time()

返回具有同样 hour, minute, second, microsecond 和 fold 值的 time 对象。 tzinfo 值为 None。 另请参见 timetz() 方法。

在 3.6 版更改: fold 值会被复制给返回的 time 对象。

datetime.timetz()

返回具有同样 hour, minute, second, microsecond, fold 和 tzinfo 属性性的 time 对象。 另请参见 time() 方法。

在 3.6 版更改: fold 值会被复制给返回的 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)

返回一个具有同样属性值的 datetime，除非通过任何关键字参数为某些属性指定了新值。 请注意可以通过指定 tzinfo=None 来从一个感知型 datetime 创建一个简单型 datetime 而不必转换日期和时间数据。

3.6 新版功能: 增加了 fold 参数。

datetime.astimezone(tz=None)

返回一个具有新的 tzinfo 属性 tz 的 datetime 对象，并会调整日期和时间数据使得结果对应的 UTC 时间与 self 相同，但为 tz 时区的本地时间。

如果给出了 tz ，则它必须是一个 tzinfo 子类的实例，并且其 utcoffset() 和 dst() 方法不可返回 None。 如果 self 为简单型，它会被假定为基于系统时区表示的时间。

如果调用时不传入参数 (或传入 tz=None) 则将假定目标时区为系统的本地时区。 转换后 datetime 实例的 .tzinfo 属性将被设为一个 timezone 实例，时区名称和时差值将从 OS 获取。

如果 self.tzinfo 为 tz ，self.astimezone(tz) 等于 self : 不会对日期或时间数据进行调整。 否则结果为 tz 时区的本地时间，代表的 UTC 时间与 self 相同：在 astz = dt.astimezone(tz) 之后，astz - astz.utcoffset() 将具有与 dt - dt.utcoffset() 相同的日期和时间数据。

如果你只是想要附加一个时区对象 tz 到一个 datetime 对象 dt 而不调整日期和时间数据，请使用 dt.replace(tzinfo=tz)。 如果你只想从一个感知型 datetime 对象 dt 移除时区对象，请使用 dt.replace(tzinfo=None)。

请注意默认的 tzinfo.fromutc() 方法在 tzinfo 的子类中可以被重载，从而影响 astimezone() 的返回结果。 如果忽略出错的情况，astimezone() 的行为就类似于:

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() 方法可以由简单型实例调用，这将假定其表示本地时间。

datetime.utcoffset()

如果 tzinfo 为 None，则返回 None，否则返回 self.tzinfo.utcoffset(self)，并且在后者不返回 None 或者一个幅度小于一天的 timedelta 对象时将引发异常。

在 3.7 版更改: UTC 时差不再限制为一个整数分钟值。

datetime.dst()

如果 tzinfo 为 None，则返回 None，否则返回 self.tzinfo.dst(self)，并且在后者不返回 None 或者一个幅度小于一天的 timedelta 对象时将引发异常。

在 3.7 版更改: DST 差值不再限制为一个整数分钟值。

datetime.tzname()

如果 tzinfo 为 None，则返回 None，否则返回 self.tzinfo.tzname(self)，如果后者不返回 None 或者一个字符串对象则将引发异常。

datetime.timetuple()

返回一个 time.struct_time，即 time.localtime() 所返回的类型。

d.timetuple() 等价于:

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 旗标的设定会依据 dst() 方法：如果 tzinfo 为 None 或 dst() 返回 None，则 tm_isdst 将设为 -1；否则如果 dst() 返回一个非零值，则 tm_isdst 将设为 1；在其他情况下 tm_isdst 将设为 0。

datetime.utctimetuple()

如果 datetime 实例 d 为简单型，这类似于 d.timetuple()，不同之处在于 tm_isdst 会强制设为 0，无论 d.dst() 返回什么结果。 DST 对于 UTC 时间永远无效。

如果 d 为感知型， d 会通过减去 d.utcoffset() 来标准化为 UTC 时间，并返回该标准化时间所对应的 time.struct_time。 tm_isdst 会强制设为 0。 请注意如果 d.year 为 MINYEAR 或 MAXYEAR 并且 UTC 调整超出一年的边界则可能引发 OverflowError。

警告

由于简单型 datetime 对象会被许多 datetime 方法当作本地时间来处理，最好是使用感知型日期时间来表示 UTC 时间；因此，使用 datetime.utctimetuple() 可能会给出误导性的结果。 如果你有一个表示 UTC 的简单型 datetime，请使用 datetime.replace(tzinfo=timezone.utc) 将其改为感知型，这样你才能使用 datetime.timetuple()。

datetime.toordinal()

返回日期的预期格列高利历序号。 与 self.date().toordinal() 相同。

datetime.timestamp()

返回对应于 datetime 实例的 POSIX 时间戳。 此返回值是与 time.time() 返回值类似的 float 对象。

简单型 datetime 实例会被假定为代表本地时间并且此方法依赖于平台的 C mktime() 函数来执行转换。 由于在许多平台上 datetime 支持的取值范围比 mktime() 更广，对于极其遥远的过去或未来此方法可能会引发 OverflowError 或 OSError。

对于感知型 datetime 实例，返回值的计算方式为:

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

3.3 新版功能.

在 3.6 版更改: timestamp() 方法使用 fold 属性来消除重复间隔中的时间歧义。

备注

没有一个方法能直接从表示 UTC 时间的简单型 datetime 实例获取 POSIX 时间戳。 如果你的应用程序使用此惯例并且你的系统时区不是设为 UTC，你可以通过提供 tzinfo=timezone.utc 来获取 POSIX 时间戳:

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

或者通过直接计算时间戳:

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

datetime.weekday()

返回一个整数代表星期几，星期一为 0，星期天为 6。 相当于 self.date().weekday()。 另请参阅 isoweekday()。

datetime.isoweekday()

返回一个整数代表星期几，星期一为 1，星期天为 7。 相当于 self.date().isoweekday()。 另请参阅 weekday(), isocalendar()。

datetime.isocalendar()

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

datetime.isoformat(sep=’T’ , timespec=’auto’)

返回一个以 ISO 8601 格式表示的日期和时间字符串：

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

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

如果 utcoffset() 返回值不为 None，则添加一个字符串来给出 UTC 时差：

• 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') 为单个分隔字符，会被放在结果的日期和时间两部分之间。 例如:

>>> 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 要包含的额外时间组件值 (默认为 'auto')。它可以是以下值之一：

• 'auto': 如果 microsecond 为 0 则与 'seconds' 相同，否则与 'microseconds' 相同。

• 'hours': 以两个数码的 HH 格式 包含 hour。

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

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

• 'milliseconds': 包含完整时间，但将秒值的小数部分截断至毫秒。 格式为 HH:MM:SS.sss。

• 'microseconds': 以 HH:MM:SS.ffffff 格式包含完整时间。

备注

排除掉的时间部分将被截断，而不是被舍入。

对于无效的 timespec 参数将引发 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 实例 d ，str(d) 等价于 d.isoformat(' ')。

datetime.ctime()

返回一个表示日期和时间的字符串:

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

输出字符串将 并不 包括时区信息，无论输入的是感知型还是简单型。

d.ctime() 等效于:

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

在原生 C ctime() 函数 (time.ctime() 会发起调用该函数，但 datetime.ctime() 则不会) 遵循 C 标准的平台上。

datetime.strftime(format)

返回一个由显式格式字符串所控制的，代表日期和时间的字符串。 另请参阅 strftime() 和 strptime() 的行为 和 datetime.isoformat()。

datetime.format(format)

与 datetime.strftime() 相同。 此方法使得在 格式化字符串字面值 中以及使用 str.format() 时为 datetime 对象指定格式字符串成为可能。 另请参阅 strftime() 和 strptime() 的行为 和 datetime.isoformat()。

用法示例: datetime

使用 datetime 对象的例子：

>>> 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.'

以下示例定义了一个 tzinfo 子类，它捕获 Kabul, Afghanistan 时区的信息，该时区使用 +4 UTC 直到 1945 年，之后则使用 +4:30 UTC:

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"

上述 KabulTz 的用法:

>>> 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 对象

一个 time 对象代表某日的（本地）时间，它独立于任何特定日期，并可通过 tzinfo 对象来调整。

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

所有参数都是可选的。 tzinfo 可以是 None，或者是一个 tzinfo 子类的实例。 其余的参数必须是在下面范围内的整数：

• 0 <= hour < 24,

• 0 <= minute < 60,

• 0 <= second < 60,

• 0 <= microsecond < 1000000,

• fold in [0, 1].

如果给出一个此范围以外的参数，则会引发 ValueError。 所有参数值默认为 0，只有 tzinfo 默认为 None。

类属性：

time.min

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

time.max

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

time.resolution

两个不相等的 time 对象之间可能的最小间隔，timedelta(microseconds=1)，但是请注意 time 对象并不支持算术运算。

实例属性（只读）：

time.hour

取值范围是 range(24)。

time.minute

取值范围是 range(60)。

time.second

取值范围是 range(60)。

time.microsecond

取值范围是 range(1000000)。

time.tzinfo

作为 tzinfo 参数被传给 time 构造器的对象，如果没有传入值则为 None。

time.fold

取值范围是 [0, 1]。 用于在重复的时间段中消除边界时间歧义。 （当夏令时结束时回拨时钟或由于政治原因导致当明时区的 UTC 时差减少就会出现重复的时间段。） 取值 0 (1) 表示两个时刻早于（晚于）所代表的同一边界时间。

3.6 新版功能.

time 对象支持 time 与 time 的比较，当 a 时间在 b 之前时，则认为 a 小于 b 。 如果比较的一方是简单型而另一方是感知型，则如果尝试进行顺序比较将引发 TypeError。 对于相等比较，简单型实例将永远不等于感知型实例。

如果两个比较方都是感知型，且具有相同的 tzinfo 属性，相同的 tzinfo 属性会被忽略并对基本时间值进行比较。 如果两个比较方都是感知型且具有不同的 tzinfo 属性，两个比较方将首先通过减去它们的 UTC 时差（从 self.utcoffset() 获取）来进行调整。 为了防止将混合类型比较回退为基于对象地址的默认比较，当 time 对象与不同类型的对象比较时，将会引发 TypeError，除非比较运算符是 == 或 !=。 在后两种情况下将分别返回 False 或 True。

在 3.3 版更改: 感知型和简单型 time 实例之间的相等比较不会引发 TypeError。

在布尔运算时，time 对象总是被视为真值。

在 3.5 版更改: 在 Python 3.5 之前，如果一个 time 对象代表 UTC 午夜零时则会被视为假值。 此行为被认为容易引发困惑和错误，因此从 Python 3.5 起已被去除。 详情参见 bpo-13936。

其他构造方法：

classmethod time.fromisoformat(time_string)

返回一个对应于以任何有效的 ISO 8601 格式给出的 time_string 的 time，下列格式除外:

1. 时区时差可能会有带小数的秒值。

2. 打头的 T，通常在当日期和时间之间可能存在歧义时才有必要，不是必需的。

3. 带小数的秒值可以有任意多位数码（超过 6 位将被截断）。

4. 带小数的时和分是不受支持的。

示例:

>>> 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 版更改: 在之前版本中，此方法仅支持可由 time.isoformat() 发出的格式。

实例方法：

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

返回一个具有同样属性值的 time，除非通过任何关键字参数指定了某些属性值。 请注意可以通过指定 tzinfo=None 从一个感知型 time 创建一个简单型 time，而不必转换时间数据。

3.6 新版功能: 增加了 fold 参数。

time.isoformat(timespec=’auto’)

返回表示为下列 ISO 8601 格式之一的时间字符串：

• 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 要包含的额外时间组件值 (默认为 'auto')。它可以是以下值之一：

• 'auto': 如果 microsecond 为 0 则与 'seconds' 相同，否则与 'microseconds' 相同。

• 'hours': 以两个数码的 HH 格式 包含 hour。

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

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

• 'milliseconds': 包含完整时间，但将秒值的小数部分截断至毫秒。 格式为 HH:MM:SS.sss。

• 'microseconds': 以 HH:MM:SS.ffffff 格式包含完整时间。

备注

排除掉的时间部分将被截断，而不是被舍入。

对于无效的 timespec 参数将引发 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()

对于时间对象 t , str(t) 等价于 t.isoformat()。

time.strftime(format)

返回一个由显式格式字符串所控制的，代表时间的字符串。 另请参阅 strftime() 和 strptime() 的行为 和 time.isoformat()。

time.format(format)

与 time.strftime() 相同。 此方法使得在 格式化字符串字面值 中以及使用 str.format() 时为 time 对象指定格式字符串成为可能。 另请参阅 strftime() 和 strptime() 的行为 和 time.isoformat()。

time.utcoffset()

如果 tzinfo 为 None，则返回 None，否则返回 self.tzinfo.utcoffset(None)，并且在后者不返回 None 或一个幅度小于一天的 a timedelta 对象时将引发异常。

在 3.7 版更改: UTC 时差不再限制为一个整数分钟值。

time.dst()

如果 tzinfo 为 None，则返回 None，否则返回 self.tzinfo.dst(None)，并且在后者不返回 None 或者一个幅度小于一天的 timedelta 对象时将引发异常。

在 3.7 版更改: DST 差值不再限制为一个整数分钟值。

time.tzname()

如果 tzinfo 为 None，则返回 None，否则返回 self.tzinfo.tzname(None)，如果后者不返回 None 或者一个字符串对象则将引发异常。

用法示例: time

使用 time 对象的例子:

>>> 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.'

（本文超出站点单文档体积上限，已按小节截断）