Python 文档注解｜strftime 和 strptime（时间格式字符串）

Python 3 官方文档地址：https://docs.python.org/zh-cn/3/library/datetime.html#strftime-and-strptime-behavior

文档目录层级：

• datetime —— 基本日期和时间类型
  • strftime() 和 strptime() 的行为

本文在 Python 3 官方文档的基础上，增加注解（会用全角方括号标出）以补全含义和修正机翻的错误，并补充实例（会使用引用方法标出）。

date、datetime 和 time 对象都支持 strftime(format) 方法，可用来创建由一个显式格式字符串所控制的表示时间的字符串。

补充实例

>>> from datetime import date, datetime, time

date 对象的 strftime(format) 方法

>>> date.today().strftime("%Y.%m.%d %H:%M:%S.%f")
'2022.12.09 00:00:00.000000'

datetime 对象的 strftime(format) 方法

>>> datetime.now().strftime("%Y.%m.%d %H:%M:%S.%f")
'2022.12.09 13:20:39.267528'

time 对象的 strftime(format) 方法

>>> datetime.now().time().strftime("%Y.%m.%d %H:%M:%S.%f")
'1900.01.01 13:22:36.682868'

相反地，datetime.strptime() 类会根据表示日期和时间的字符串和相应的格式字符串来创建一个 datetime 对象。

补充实例

>>> datetime.strptime("2022.12.09 13:20:39.267528", "%Y.%m.%d %H:%M:%S.%f")
datetime.datetime(2022, 12, 9, 13, 20, 39, 267528)

下表提供了 strftime() 与 strptime() 的高层级比较：

strftime() 和 strptime() 的格式编码

以下列表显示了 1989 版 C 标准所要求的全部格式代码，它们在带有标准 C 实现的所有平台上均可用。

为了方便起见，还包括了 C89 标准不需要的其他一些指令。这些参数都对应于 ISO 8601 日期值。

官方版本变化梳理

在 3.6 及之后的版本中，新增了 %G, %u 和 %V。

对完整格式代码集的支持在不同平台上有所差异，因为 Python 要调用所在平台的 C 库的 strftime() 函数，而不同平台的差异是很常见的。要查看你所用平台所支持的完整格式代码集，请参阅 strftime 文档。不同的平台在处理不支持的格式指定符方面也有差异。

官方文档备注汇总

See R. H. van Gent’s guide to the mathematics of the ISO 8601 calendar for a good explanation.

补充实例

>>> datetime(2023,2,28).strftime("%G %u %V")
'2023 2 09'

技术细节

总体而言，d.strftime(fmt) 类似于 time 模块的 time.strftime(fmt, d.timetuple())，但是并非所有对象都支持 timetuple() 方法。

对于 datetime.strptime() 类方法，默认值为 1900-01-01T00:00:00.000: 任何未在格式字符串中指定的部分都将从默认值中提取。

官方文档备注

传入 datetime.strptime('Feb 29', '%b %d') 将导致错误，因为 1900 不是闰年。

补充样例

>>> datetime.strptime('Feb 29', '%b %d')
Traceback (most recent call last):
File "<input>", line 1, in <module>
File "C:\Program Files\Python39\lib\_strptime.py", line 579, in _strptime_datetime
 return cls(*args)
ValueError: day is out of range for month

使用 datetime.strptime(date_string, format) 等价于：

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

除非格式中包含秒以下的部分或时区差值信息，它们在 datetime.strptime 中受支持但会被 time.strptime 所丢弃。

对于 time 对象，年、月、日的格式代码不应被使用，因为 time 对象没有这些值。 如果它们被使用，则年份将被替换为 1900，而月和日将被替换为 1。

补充样例

>>> time(13, 31, 15).strftime("%Y.%m.%d")
'1900.01.01'

对于 date 对象，时、分、秒和微秒的格式代码不应被使用，因为 date 对象没有这些值。 如果它们被使用，则它们都将被替换为 0。

补充样例

>>> date(2023, 2, 28).strftime("%H:%H:%S.%f")
'00:00:00.000000'

出于相同的原因，对于包含当前区域设置字符集所无法表示的 Unicode 码位的格式字符串的处理方式也取决于具体平台。在某些平台上这样的码位会不加修改地原样输出，而在其他平台上 strftime 则可能引发 UnicodeError 或只返回一个空字符串。

注释

备注 (1)

由于此格式依赖于当前区域设置，因此对具体输出值应当保持谨慎预期。字段顺序会发生改变（例如 “month/day/year” 与 “day/month/year”），并且输出可能包含使用区域设置所指定的默认编码格式的 Unicode 字符（例如如果当前区域为 ja_JP，则默认编码格式可能为 eucJP, SJIS 或 utf-8 中的一个；使用 locale.getlocale() 可确定当前区域设置的编码格式）。

补充实例

>>> import locale
>>> locale.getlocale()
('Chinese (Simplified)_China', '936')

备注 (2)

strptime() 方法能够解析整个 [1, 9999] 范围内的年份，但 < 1000 的年份必须加零填充为 4 位数字宽度。

官方版本变化梳理

在 3.2 之前的版本中，strftime() 方法只限于 >= 1900 的年份；

在 3.2 版本中，strftime() 方法只限于 years >= 1000 的年份；

在 3.3 及之后的版本中，strftime() 方法能够解析 [1, 9999] 的年份。

备注 (3)

当与 strptime() 方法一起使用时，如果使用 %I 指令来解析小时，%p 指令只影响输出小时字段。

备注 (4)

与 time 模块不同的是， datetime 模块不支持闰秒。

备注 (5)

当与 strptime() 方法一起使用时，%f 指令可接受一至六个数码及左边的零填充。 %f 是对 C 标准中格式字符集的扩展（但单独在 datetime 对象中实现，因此它总是可用）。

备注 (6)

对于简单型对象，%z and %Z 格式代码会被替换为空字符串。对于一个感知型对象而言：

%z：utcoffset() 会被转换为 ±HHMM[SS[.ffffff]] 形式的字符串，其中 HH 为给出 UTC 时差的小时部分的 2 位数码字符串，MM 为给出 UTC 时差的分钟部分的 2 位数码字符串，SS 为给出 UTC 时差的秒部分的 2 位数码字符串，而 ffffff 为给出 UTC 时差的微秒部分的 6 位数码字符串。 当时差为整数秒时 ffffff 部分将被省略，而当时差为整数分钟时 ffffff 和 SS 部分都将被省略。 例如，如果 utcoffset() 返回 timedelta(hours=-3, minutes=-30)，则 %z 会被替换为字符串 '-0330'。

官方版本变化梳理

在 3.7 版本更新：

• UTC 时差不再限制为一个整数分钟值。
• 当提供 %z 指令给 strptime() 方法时，UTC 差值可以在时、分和秒之间使用冒号分隔符。 例如，'+01:00:00' 将被解读为一小时的差值。 此外，提供 'Z' 就相当于 '+00:00'。

%Z：在 strftime() 中，如果 tzname() 返回 None 则 %Z 会被替换为一个空字符串；在其他情况下 %Z 会被替换为返回值，该值必须为一个字符串。strptime() 仅接受特定的 %Z 值:你的机器的区域设置可以是 time.tzname 中的任何值硬编码的值 UTC 和 GMT这样生活在日本的人可用的值为 JST, UTC 和 GMT，但可能没有 EST。 它将引发 ValueError 表示无效的值。

官方版本变化梳理

在 3.2 版本更新：当提供 %z 指令给 strptime() 方法时，将产生一个感知型 datetime 对象。 结果的 tzinfo 将被设为一个 timezone 实例。

这些代码可能不是在所有平台上都可与 strftime() 方法配合使用。 ISO 8601 年份和 ISO 8601 星期指令并不能与上面的年份和星期序号指令相互替代。调用 strptime() 时传入不完整或有歧义的 ISO 8601 指令将引发 ValueError。

备注 (7)

当与 strptime() 方法一起使用时，%U 和 %W 仅用于指定星期几和日历年份 (%Y) 的计算。

注释 (8)

类似于 %U 和 %W，%V 仅用于在 strptime() 格式字符串中指定星期几和 ISO 年份 (%G) 的计算。 还要注意 %G 和 %Y 是不可交换的。

注释 (9)

When used with the strptime() method, the leading zero is optional for formats %d, %m, %H, %I, %M, %S, %j, %U, %W, and %V. Format %y does require a leading zero.