属性

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

构造函数

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

方法

datetime.time 和 datetime.datetime 类的 replace() 方法将获得一个名为 fold 的新关键字-only参数。它的行为将与其他 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)

返回一个具有指定年、月、日、时、分、秒、微秒和 fold 的 datetime.datetime 对象。

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

返回一个具有指定小时、分钟、秒、微秒和 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 实例到“感知”datetime 实例的转换。

astimezone() 方法现在将对“天真”的 self 起作用。在这种情况下，将假定系统本地时区，并使用 fold 标志来确定在模糊情况下哪个本地时区生效。

例如，在一个设置为美国/东部时区的系统上

>>> 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 属性。

例如，在一个设置为美国/东部时区的系统上

>>> 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 中较小的值，否则返回较大的值。

例如，在一个设置为美国/东部时区的系统上

>>> 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 的值，它对应于在 UTC 偏移量始终与间隙之前偏移量相同的时区中的 dt，另一个是类似的值，但在 UTC 偏移量始终与间隙之后偏移量相同的时区中。

给定缺失的 dt 时，dt.timestamp() 返回的值，如果 dt.fold == 0，则为两个“最好知道”值中较大的一个，否则为较小的一个。（这不是笔误——它有意与模糊时间的规则相反。）

例如，在一个设置为美国/东部时区的系统上

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

感知 datetime 实例

预-PEP tzinfo 实现的用户将不会看到其感知 datetime 实例的行为有任何变化。两个这样的实例，如果仅在 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

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

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

一个非技术性的回答

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

• 鲍勃：爱丽丝 - 明天凌晨 01:30 举行观星派对吧！
• 爱丽丝：你知道，鲍勃，明天凌晨 01:30 会出现两次。你指的是哪个时间？
• 鲍勃：我没想到这个，但我们选第一个吧。

（同人物，一小时后）

• 鲍勃：爱丽丝 - 我的 Py-O-Clock 小工具让我明天凌晨 01:30 设置时选择 fold=0 还是 fold=1。我该怎么办？
• 爱丽丝：我从没听说过 Py-O-Clock，但我猜 fold=0 是第一个凌晨 01:30，fold=1 是第二个。

一个技术原因

尽管 time.struct_time 对象的 tm_isdst 字段可用于消除折叠中本地时间的歧义，但这种消歧的语义与本 PEP 中的提议完全不同。

tm_isdst 字段的主要问题是，如果不了解时区细节，就无法知道 tm_isdst 的适当值，而这些细节只有 tzinfo 实现才能获得。因此，尽管 tm_isdst 在 time.localtime 等方法的*输出*中有用，但作为 time.mktime 等方法的*输入*却很麻烦。

如果程序员对 time.mktime 错误地指定了非负值的 tm_isdst，结果将是偏差 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) 仅适用于在系统时区中恰好处于折叠或间隙中的“天真”datetime。在所有其他情况下，转换中将忽略 fold 的值，除非实例使用“fold”感知 tzinfo，而这在预-PEP 程序中是不可用的。同样，对此类程序而言，对“天真”实例调用 astimezone() 将不可用，因为 astimezone() 目前不适用于“天真”datetime。

这使我们只剩下一种情况，现有程序在实现此 PEP 后可能开始产生不同的结果：当对恰好处于折叠或间隙中的“天真”datetime 实例调用 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 根据其余字段确定给定时间是否处于夏令时）是实践中唯一有用的选择。

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

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

换句话说，本 PEP 不缺少 tm_isdst=-1 行为。相反，它是以两种不同且明确定义的风味提供的唯一行为。缺失的行为是当给定的本地小时因 tm_isdst 错误指定而被解释为不同的本地小时时。

例如，在北半球实行夏令时（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.utcoffset() 在 dt 表示模糊或缺失本地时间时应引发错误。

此提议的主要问题在于，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 提供了以几行代码实现任何所需行为的方法。