属性

datetime.time 和 datetime.datetime 类的实例将获得一个新的属性 fold，它有两个可能的值：0 和 1。

构造函数

datetime.time 和 datetime.datetime 类的 __new__ 方法将获得一个名为 fold 的新的仅限关键字参数，其默认值为 0。 fold 参数的值将用于初始化返回实例中 fold 属性的值。

方法

datetime.time 和 datetime.datetime 类的 replace() 方法将获得一个名为 fold 的新的仅限关键字参数。它的行为类似于其他 replace() 参数：如果指定了 fold 参数并赋予其 0 或 1 的值，则 replace() 返回的新实例的 fold 属性将设置为该值。在 CPython 中，fold 的任何非整数值都会引发 TypeError，但其他实现可能会允许值 None 的行为与未给出 fold 时相同。[4]（这是对跨 Python 实现的此方法其他位置的 None 参数处理方式的现有差异的认可；它并非意在为将来对 fold=None 的替代解释敞开大门。）如果未指定 fold 参数，则原始的 fold 属性值将复制到结果中。

C-API

将定义访问宏以从 PyDateTime_DateTime 和 PyDateTime_Time 对象中提取 fold 的值。

int PyDateTime_DATE_GET_FOLD(PyDateTime_DateTime *o)

将 fold 的值作为 C int 返回。

int PyDateTime_TIME_GET_FOLD(PyDateTime_Time *o)

将 fold 的值作为 C int 返回。

将定义新的构造函数，这些构造函数将采用一个额外的参数来指定在创建的实例中 fold 的值

PyObject* PyDateTime_FromDateAndTimeAndFold(
    int year, int month, int day, int hour, int minute,
    int second, int usecond, int fold)

返回一个具有指定年份、月份、日期、小时、分钟、秒、微秒和折叠的 datetime.datetime 对象。

PyObject* PyTime_FromTimeAndFold(
    int hour, int minute, int second, int usecond, int fold)

返回一个具有指定小时、分钟、秒、微秒和折叠的 datetime.time 对象。

现在几点？

不带参数调用的 datetime.now() 方法在返回系统本地时间折叠中的两个模棱两可时间中的第二个时，将设置 fold=1。当使用 tzinfo 参数调用时，fold 的值将由 tzinfo.fromutc() 实现确定。当将 datetime.timezone 类（stdlib 的固定偏移量 tzinfo 子类，例如 datetime.timezone.utc）的实例作为 tzinfo 传递时，返回的 datetime 实例将始终具有 fold=0。 datetime.utcnow() 方法不受影响。

从朴素时间转换为感知时间

提议了一项新功能，以促进从朴素 datetime 实例到感知时间的转换。

astimezone() 方法现在可以用于朴素的 self。在这种情况下，将假定系统本地时区，并且将使用 fold 标志来确定模棱两可的情况下哪个本地时区有效。

例如，在设置为 US/Eastern 时区的系统上

>>> dt = datetime(2014, 11, 2, 1, 30)
>>> dt.astimezone().strftime('%D %T %Z%z')
'11/02/14 01:30:00 EDT-0400'
>>> dt.replace(fold=1).astimezone().strftime('%D %T %Z%z')
'11/02/14 01:30:00 EST-0500'

这意味着 datetime.now(tz) 完全等效于 datetime.now().astimezone(tz)（假设 tz 是 PEP 后 tzinfo 实现的实例，即正确处理和设置 fold 的实例）。

从纪元开始的 POSIX 秒数转换为感知时间

datetime.datetime 的 fromtimestamp() 静态方法将在返回的对象中适当地设置 fold 属性。

例如，在设置为 US/Eastern 时区的系统上

>>> datetime.fromtimestamp(1414906200)
datetime.datetime(2014, 11, 2, 1, 30)
>>> datetime.fromtimestamp(1414906200 + 3600)
datetime.datetime(2014, 11, 2, 1, 30, fold=1)

从感知时间转换为纪元开始的 POSIX 秒数

datetime.datetime 的 timestamp() 方法将仅当这些实例表示模棱两可或缺失时间时，才会为仅 fold 属性值不同的 datetime.datetime 实例返回不同的值。

当 datetime.datetime 实例 dt 表示模棱两可的时间时，存在两个值 s0 和 s1，使得

datetime.fromtimestamp(s0) == datetime.fromtimestamp(s1) == dt

（这是因为 == 忽略了 fold 的值 - 请参见下文。）

在这种情况下，如果 dt.fold == 0，则 dt.timestamp() 将返回 s0 和 s1 中较小的值，否则返回较大的值。

例如，在设置为 US/Eastern 时区的系统上

>>> datetime(2014, 11, 2, 1, 30, fold=0).timestamp()
1414906200.0
>>> datetime(2014, 11, 2, 1, 30, fold=1).timestamp()
1414909800.0

当 datetime.datetime 实例 dt 表示缺失时间时，不存在这样的值 s：

datetime.fromtimestamp(s) == dt

但我们可以形成两个“了解一下”的 s 值，它们相差的时间间隔（以秒为单位）。一个是 s 的值，它对应于在时区中 dt，其中 UTC 偏移量始终与时间间隔之前的偏移量相同，另一个是类似的值，但在 UTC 偏移量始终与时间间隔之后的偏移量相同的时区中。

对于给定的缺失的 dt，dt.timestamp() 返回的值将是这两个“了解一下”值中较大的值，如果 dt.fold == 0，否则为较小的值。（这不是打字错误 - 它有意与模棱两可时间规则相反。）

例如，在设置为 US/Eastern 时区的系统上

>>> datetime(2015, 3, 8, 2, 30, fold=0).timestamp()
1425799800.0
>>> datetime(2015, 3, 8, 2, 30, fold=1).timestamp()
1425796200.0

感知时间 datetime 实例

tzinfo 的 PEP 之前实现的用户将不会看到其已知日期时间实例的行为有任何变化。仅 fold 属性的值不同的两个这样的实例，除了显式访问 fold 值之外，无法通过任何其他方式区分。（这是因为这些 PEP 之前的实现未使用 fold 属性。）

另一方面，如果对象的 tzinfo 设置为支持折叠的实现，那么在折叠或间隙中，fold 的值将影响几个方法的结果：utcoffset()、dst()、tzname()、astimezone()、strftime()（如果在格式规范中使用了“%Z”或“%z”指令）、isoformat() 和 timetuple()。

组合和拆分日期和时间

datetime.datetime.combine() 方法会将 fold 属性的值复制到生成的 datetime.datetime 实例。

datetime.datetime.time() 方法会将 fold 属性的值复制到生成的 datetime.time 实例。

Pickle

折叠属性的值仅保存在使用协议版本 4（在 Python 3.4 中引入）或更高版本创建的 pickle 中。

datetime.datetime 和 datetime.time 对象的 pickle 大小不会改变。fold 值将编码在 datetime.datetime pickle 有效负载的第 3 个字节的第一个比特中；以及 datetime.time 有效负载的第一个字节的第一个比特中。在当前实现中，这些字节用于存储月份 (1-12) 和小时 (0-23) 值，并且第一个比特始终为 0。我们选择这些字节是因为它们是当前 unpickle 代码检查的唯一字节。因此，在 PEP 之前的 Python 中加载 PEP 之后的 fold=1 pickle 将导致异常，而不是具有超出范围组件的实例。

非技术性答案

• 爱丽丝：鲍勃——我们明天凌晨1:30举行一次观星派对吧！
• 鲍勃：我是否应该最初假设指定时间是否处于夏令时？
• 爱丽丝：啊？

• 鲍勃：爱丽丝——我们明天凌晨1:30举行一次观星派对吧！
• 爱丽丝：你知道，鲍勃，明天凌晨1:30会发生两次。你指的是哪一次？
• 鲍勃：我没有想过，但让我们选择第一次。

（相同的人物，一小时后）

• 鲍勃：爱丽丝——我的这个Py-O-Clock小玩意儿要求我在设置明天凌晨1:30时在fold=0和fold=1之间进行选择。我该怎么办？
• 爱丽丝：我从未听说过Py-O-Clock，但我想fold=0是第一次凌晨1:30，fold=1是第二次。

技术原因

虽然time.struct_time对象的tm_isdst字段可用于消除fold中的本地时间歧义，但这种消除歧义的语义与本PEP中的提案完全不同。

tm_isdst字段的主要问题在于，如果不了解仅对tzinfo实现可用的有关时区的信息，就无法知道tm_isdst的哪个值是合适的。因此，虽然tm_isdst在诸如time.localtime之类的函数的输出中很有用，但作为诸如time.mktime之类的函数的输入，它却很麻烦。

如果程序员错误地将tm_isdst的非负值指定给time.mktime，则结果时间将相差1小时，并且由于很少有方法可以在调用time.mktime之前了解有关DST的任何信息，因此唯一明智的选择通常是tm_isdst=-1。

与tm_isdst不同，建议的fold属性不会影响datetime实例的解释，除非在没有该属性的情况下，两种（或零种）解释都是可能的。

由于将某些内容称为isdst，但其语义与tm_isdst不同，这会非常令人困惑，因此我们需要一个不同的名称。此外，datetime.datetime类已经有一个名为dst()的方法，如果我们将fold称为“isdst”，那么我们必然会遇到“isdst”为零但dst()不为零或反之亦然的情况。

向后兼容性

有人建议，如果 fold 标志的默认值为 None，则可以改进向后兼容性，这将表示请求 PEP 之前的行为。根据下面的分析，我们认为，使用 fold=0 作为默认值的提议更改具有足够的向后兼容性。

本 PEP 仅提供三种方法供程序发现两个在其他方面相同的 datetime 实例具有不同的 fold 值：(1) 对 fold 属性进行显式检查；(2) 如果实例是朴素的 - 使用 astimezone() 方法转换为另一个时区；以及 (3) 使用 timestamp() 方法转换为 float。

由于 fold 是一个新属性，因此现有程序无法使用第一个选项。请注意，选项 (2) 仅适用于恰好位于系统时区中的折叠或间隙中的朴素日期时间。在所有其他情况下，fold 的值在转换中将被忽略，除非实例使用 fold 感知的 tzinfo，而这在 PEP 之前的程序中是不可用的。类似地，对朴素实例调用的 astimezone() 在此类程序中也将不可用，因为 astimezone() 目前不适用于朴素日期时间。

这使得我们只有一种情况，即现有程序在实施本 PEP 后可能会开始产生不同的结果：当对恰好位于折叠或间隙中的朴素日期时间实例调用 datetime.timestamp() 方法时。在当前的实现中，结果是未定义的。根据系统 mktime 实现，程序在这些情况下可能会看到不同的结果或错误。使用本 PEP，时间戳的值在这些情况下将是明确定义的，但将取决于 fold 标志的值。我们认为 datetime.timestamp() 方法行为的变化是由本 PEP 启用的错误修复。依赖于旧行为的用户仍然可以通过编写 time.mktime(dt.timetuple()) + 1e-6*dt.microsecond 而不是 dt.timestamp() 来模拟旧行为。

与 tm_isdst 的类比

time.mktime 接口允许 tm_isdst 标志具有三个值：-1、0 和 1。正如我们上面解释的那样，-1（要求 mktime 根据其余字段从给定时间确定 DST 是否有效）是实际上唯一有用的选择。

但是，使用 fold 标志，datetime.timestamp() 将在 99.98% 的时间内返回与 mktime 具有 tm_isdst=-1 的相同值，这适用于大多数具有 DST 转换的时区。此外，无论 fold 的值如何，都指定了类似于 tm_isdst=-1 的行为。

只有在 0.02% 的情况下（每年 2 小时），datetime.timestamp() 和 mktime 具有 tm_isdst=-1 可能会不一致。但是，即使在这种情况下，大多数 mktime 实现也将返回 fold=0 或 fold=1 值，即使相关标准允许 mktime 返回 -1 并在这些情况下设置错误代码。

换句话说，本 PEP 中并没有缺少 tm_isdst=-1 行为。相反，它是以两种不同的明确定义的方式提供的唯一行为。缺少的行为是当给定的本地小时由于 tm_isdst 指定错误而被解释为不同的本地小时时。

例如，在北半球的遵守 DST 的时区（DST 在 6 月份有效）中，可以获得

>>> from time import mktime, localtime
>>> t = mktime((2015, 6, 1, 12, 0, 0, -1, -1, 0))
>>> localtime(t)[:]
(2015, 6, 1, 13, 0, 0, 0, 152, 1)

请注意，12:00 被 mktime 解释为 13:00。使用 datetime.timestamp、datetime.fromtimestamp，目前保证

>>> t = datetime.datetime(2015, 6, 1, 12).timestamp()
>>> datetime.datetime.fromtimestamp(t)
datetime.datetime(2015, 6, 1, 12, 0)

本 PEP 将相同的保证扩展到 fold 的两个值

>>> t = datetime.datetime(2015, 6, 1, 12, fold=0).timestamp()
>>> datetime.datetime.fromtimestamp(t)
datetime.datetime(2015, 6, 1, 12, 0)

>>> t = datetime.datetime(2015, 6, 1, 12, fold=1).timestamp()
>>> datetime.datetime.fromtimestamp(t)
datetime.datetime(2015, 6, 1, 12, 0)

因此，建议用于 fold=-1 的用途之一（匹配旧行为）是不需要的。fold 的任何选择都将匹配旧行为，除了旧行为未定义的少数情况。

严格的无效时间检查

另一个建议是使用 fold=-1 或 fold=None 来指示程序确实无法处理折叠和间隙，并且只要 dt 表示模棱两可或缺少的本地时间，dt.utcoffset() 就会引发错误。

此提议的主要问题是，dt.utcoffset() 在引发错误不是选项的情况下在内部使用：例如，在字典查找或列表/集合成员资格检查中。因此，严格的间隙/折叠检查行为需要由一个单独的标志控制，例如 dt.utcoffset(raise_on_gap=True, raise_on_fold=False)。但是，此功能可以在用户代码中轻松实现。

def utcoffset(dt, raise_on_gap=True, raise_on_fold=False):
    u = dt.utcoffset()
    v = dt.replace(fold=not dt.fold).utcoffset()
    if u == v:
        return u
    if (u < v) == dt.fold:
        if raise_on_fold:
            raise AmbiguousTimeError
    else:
        if raise_on_gap:
            raise MissingTimeError
    return u

此外，在问题情况下引发错误只是许多可能解决方案之一。交互式程序可以向用户请求其他输入，而服务器进程可以记录警告并采取适当的默认操作。我们不可能为所有可能的用户信息需求提供函数，但本 PEP 提供了在几行代码中实现任何所需行为的方法。