Text of peps.python.org › pep-0495 as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 495 – Local Time Disambiguation | peps.python.org

PEP 495 – Local Time Disambiguation PEP 495 – Local Time Disambiguation Author : Alexander Belopolsky <alexander.belopolsky at gmail.com>, Tim Peters <tim.peters at gmail.com> Discussions-To : Datetime-SIG list Status : Final Type : Standards Track Created : 02-Aug-2015 Python-Version : 3.6 Resolution : Datetime-SIG message Table of Contents Abstract Rationale Terminology Proposal The “fold” attribute Affected APIs Attributes Constructors Methods C-API Affected Behaviors What time is it?

Conversion from naive to aware Conversion from POSIX seconds from EPOCH Conversion to POSIX seconds from EPOCH Aware datetime instances Combining and splitting date and time Pickles Implementations of tzinfo in the Standard Library Guidelines for New tzinfo Implementations Ignorance is Bliss In the Fold Mind the Gap Summary of Rules at a Transition The DST Transitions Temporal Arithmetic and Comparison Operators Aware datetime Equality Comparison Backward and Forward Compatibility Questions and Answers Why not call the new flag “isdst”?

A non-technical answer A technical reason Why “fold”? What is “first”? Are two values enough? Backward Compatibility Analogy with tm_isdst Strict Invalid Time Checking Implementation Copyright Picture Credit Abstract This PEP adds a new attribute fold to instances of the datetime.time and datetime.datetime classes that can be used to differentiate between two moments in time for which local times are the same.

The allowed values for the fold attribute will be 0 and 1 with 0 corresponding to the earlier and 1 to the later of the two possible readings of an ambiguous local time. Rationale In most world locations, there have been and will be times when local clocks are moved back. [1] In those times, intervals are introduced in which local clocks show the same time twice in the same day. In these situations, the information displayed on a local clock (or stored in a Python datetime instance) is insufficient to identify a particular moment in time.

The proposed solution is to add an attribute to the datetime instances taking values of 0 and 1 that will enumerate the two ambiguous times. Terminology When clocks are moved back, we say that a fold [2] is created in time. When the clocks are moved forward, a gap is created. A local time that falls in the fold is called ambiguous . A local time that falls in the gap is called missing . Proposal The “fold” attribute We propose adding an attribute called fold to instances of the datetime.time and datetime.datetime classes.

This attribute should have the value 0 for all instances except those that represent the second (chronologically) moment in time in an ambiguous case. For those instances, the value will be 1. [3] Affected APIs Attributes Instances of datetime.time and datetime.datetime classes will get a new attribute fold with two possible values: 0 and 1. Constructors The __new__ methods of the datetime.time and datetime.datetime classes will get a new keyword-only argument called fold with the default value 0.

The value of the fold argument will be used to initialize the value of the fold attribute in the returned instance. Methods The replace() methods of the datetime.time and datetime.datetime classes will get a new keyword-only argument called fold . It will behave similarly to the other replace() arguments: if the fold argument is specified and given a value 0 or 1, the new instance returned by replace() will have its fold attribute set to that value.

In CPython, any non-integer value of fold will raise a TypeError , but other implementations may allow the value None to behave the same as when fold is not given. [4] (This is a nod to the existing difference in treatment of None arguments in other positions of this method across Python implementations; it is not intended to leave the door open for future alternative interpretation of fold=None .) If the fold argument is not specified, the original value of the fold attribute is copied to the result.

C-API Access macros will be defined to extract the value of fold from PyDateTime_DateTime and PyDateTime_Time objects. int PyDateTime_DATE_GET_FOLD ( PyDateTime_DateTime * o ) Return the value of fold as a C int . int PyDateTime_TIME_GET_FOLD ( PyDateTime_Time * o ) Return the value of fold as a C int . New constructors will be defined that will take an additional argument to specify the value of fold in the created instance: PyObject * PyDateTime_FromDateAndTimeAndFold ( int year , int month , int day , int hour , int minute , int second , int usecond , int fold ) Return a datetime.datetime object with the specified year, month, day, hour, minute, second, microsecond and fold.

PyObject * PyTime_FromTimeAndFold ( int hour , int minute , int second , int usecond , int fold ) Return a datetime.time object with the specified hour, minute, second, microsecond and fold. Affected Behaviors What time is it? The datetime.now() method called without arguments will set fold=1 when returning the second of the two ambiguous times in a system local time fold. When called with a tzinfo argument, the value of the fold will be determined by the tzinfo.fromutc() implementation.

When an instance of the datetime.timezone class (the stdlib’s fixed-offset tzinfo subclass, e.g. datetime.timezone.utc ) is passed as tzinfo , the returned datetime instance will always have fold=0 . The datetime.utcnow() method is unaffected. Conversion from naive to aware A new feature is proposed to facilitate conversion from naive datetime instances to aware. The astimezone() method will now work for naive self .

The system local timezone will be assumed in this case and the fold flag will be used to determine which local timezone is in effect in the ambiguous case. For example, on a system set to US/Eastern timezone: >>> 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' An implication is that datetime.now(tz) is fully equivalent to datetime.now().astimezone(tz) (assuming tz is an instance of a post-PEP tzinfo implementation, i.e. one that correctly handles and sets fold ).

Conversion from POSIX seconds from EPOCH The fromtimestamp() static method of datetime.datetime will set the fold attribute appropriately in the returned object. For example, on a system set to US/Eastern timezone: >>> datetime . fromtimestamp ( 1414906200 ) datetime.datetime(2014, 11, 2, 1, 30) >>> datetime . fromtimestamp ( 1414906200 + 3600 ) datetime.datetime(2014, 11, 2, 1, 30, fold=1) Conversion to POSIX seconds from EPOCH The timestamp() method of datetime.datetime will return different values for datetime.datetime instances that differ only by the value of their fold attribute if and only if these instances represent an ambiguous or a missing time.

When a datetime.datetime instance dt represents an ambiguous time, there are two values s0 and s1 such that: datetime . fromtimestamp ( s0 ) == datetime . fromtimestamp ( s1 ) == dt (This is because == disregards the value of fold – see below.) In this case, dt.timestamp() will return the smaller of s0 and s1 values if dt.fold == 0 and the larger otherwise. For example, on a system set to US/Eastern timezone: >>> datetime ( 2014 , 11 , 2 , 1 , 30 , fold = 0 ) . timestamp () 1414906200.0 >>> datetime ( 2014 , 11 , 2 , 1 , 30 , fold = 1 ) . timestamp () 1414909800.0 When a datetime.datetime instance dt represents a missing time, there is no value s for which: datetime . fromtimestamp ( s ) == dt but we can form two “nice to know” values of s that differ by the size of the gap in seconds.

One is the value of s that would correspond to dt in a timezone where the UTC offset is always the same as the offset right before the gap and the other is the similar value but in a timezone the UTC offset is always the same as the offset right after the gap. The value ret

The rest of this page is on the live site.