Attributes

Instances ofdatetime.time anddatetime.datetime classes willget a new attributefold with two possible values: 0 and 1.

Constructors

The__new__ methods of thedatetime.time anddatetime.datetime classes will get a new keyword-only argumentcalledfold with the default value 0. The value of thefold argument will be used to initialize the value of thefold attribute in the returned instance.

Methods

Thereplace() methods of thedatetime.time anddatetime.datetime classes will get a new keyword-only argumentcalledfold. It will behave similarly to the otherreplace()arguments: if thefold argument is specified and given a value 0or 1, the new instance returned byreplace() will have itsfold attribute set to that value. In CPython, any non-integervalue offold will raise aTypeError, but otherimplementations may allow the valueNone to behave the same aswhenfold is not given.[4] (This isa nod to the existing difference in treatment ofNone argumentsin other positions of this method across Python implementations;it is not intended to leave the door open for future alternativeinterpretation offold=None.) If thefold argument is notspecified, the original value of thefold attribute is copied tothe result.

C-API

Access macros will be defined to extract the value offold fromPyDateTime_DateTime andPyDateTime_Time objects.

intPyDateTime_DATE_GET_FOLD(PyDateTime_DateTime*o)

Return the value offold as a Cint.

intPyDateTime_TIME_GET_FOLD(PyDateTime_Time*o)

Return the value offold as a Cint.

New constructors will be defined that will take an additionalargument to specify the value offold in the createdinstance:

PyObject*PyDateTime_FromDateAndTimeAndFold(intyear,intmonth,intday,inthour,intminute,intsecond,intusecond,intfold)

Return adatetime.datetime object with the specified year, month,day, hour, minute, second, microsecond and fold.

PyObject*PyTime_FromTimeAndFold(inthour,intminute,intsecond,intusecond,intfold)

Return adatetime.time object with the specified hour, minute,second, microsecond and fold.

What time is it?

Thedatetime.now() method called without arguments will setfold=1 when returning the second of the two ambiguous times in asystem local time fold. When called with atzinfo argument, thevalue of thefold will be determined by thetzinfo.fromutc()implementation. When an instance of thedatetime.timezone class(the stdlib’s fixed-offsettzinfo subclass,e.g.datetime.timezone.utc) is passed astzinfo, thereturned datetime instance will always havefold=0.Thedatetime.utcnow() method is unaffected.

Conversion from naive to aware

A new feature is proposed to facilitate conversion from naive datetimeinstances to aware.

Theastimezone() method will now work for naiveself. Thesystem local timezone will be assumed in this case and thefoldflag will be used to determine which local timezone is in effectin 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 thatdatetime.now(tz) is fully equivalent todatetime.now().astimezone(tz) (assumingtz is an instance of apost-PEPtzinfo implementation, i.e. one that correctly handlesand setsfold).

Conversion from POSIX seconds from EPOCH

Thefromtimestamp() static method ofdatetime.datetime willset thefold 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

Thetimestamp() method ofdatetime.datetime will return differentvalues fordatetime.datetime instances that differ only by the valueof theirfold attribute if and only if these instances represent anambiguous or a missing time.

When adatetime.datetime instancedt represents an ambiguoustime, there are two valuess0 ands1 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 ofs0ands1 values ifdt.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 adatetime.datetime instancedt represents a missingtime, there is no values for which:

datetime.fromtimestamp(s)==dt

but we can form two “nice to know” values ofs that differby the size of the gap in seconds. One is the value ofsthat would correspond todt in a timezone where the UTC offsetis always the same as the offset right before the gap and theother is the similar value but in a timezone the UTC offsetis always the same as the offset right after the gap.

The value returned bydt.timestamp() given a missingdt will be the greater of the two “nice to know” valuesifdt.fold==0 and the smaller otherwise.(This is not a typo – it’s intentionally backwards from the rule forambiguous times.)

For example, on a system set to US/Eastern timezone:

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

Aware datetime instances

Users of pre-PEP implementations oftzinfo will not see anychanges in the behavior of their aware datetime instances. Two suchinstances that differ only by the value of thefold attribute willnot be distinguishable by any means other than an explicit access tothefold value. (This is because these pre-PEP implementationsare not using thefold attribute.)

On the other hand, if an object’stzinfo is set to a fold-awareimplementation, then in a fold or gap the value offold willaffect the result of several methods:utcoffset(),dst(),tzname(),astimezone(),strftime() (if the “%Z” or “%z” directive is used in the formatspecification),isoformat(), andtimetuple().

Combining and splitting date and time

Thedatetime.datetime.combine() method will copy the value of thefold attribute to the resultingdatetime.datetime instance.

Thedatetime.datetime.time() method will copy the value of thefold attribute to the resultingdatetime.time instance.

Pickles

The value of the fold attribute will only be saved in pickles createdwith protocol version 4 (introduced in Python 3.4) or greater.

Pickle sizes for thedatetime.datetime anddatetime.timeobjects will not change. Thefold value will be encoded in thefirst bit of the 3rd byte of thedatetime.datetimepickle payload; and in the first bit of the 1st byte of thedatetime.time payload. In thecurrent implementationthese bytes are used to store the month (1-12) and hour (0-23) valuesand the first bit is always 0. We picked these bytes because they arethe only bytes that are checked by the current unpickle code. Thusloading post-PEPfold=1 pickles in a pre-PEP Python will result inan exception rather than an instance with out of range components.

A non-technical answer

• Alice: Bob - let’s have a stargazing party at 01:30 AM tomorrow!
• Bob: Should I presume initially that Daylight Saving Time is or isnot in effect for the specified time?
• Alice: Huh?

• Bob: Alice - let’s have a stargazing party at 01:30 AM tomorrow!
• Alice: You know, Bob, 01:30 AM will happen twice tomorrow. Which time do you have in mind?
• Bob: I did not think about it, but let’s pick the first.

(same characters, an hour later)

• Bob: Alice - this Py-O-Clock gadget of mine asks me to choosebetween fold=0 and fold=1 when I set it for tomorrow 01:30 AM.What should I do?
• Alice: I’ve never hear of a Py-O-Clock, but I guess fold=0 isthe first 01:30 AM and fold=1 is the second.

A technical reason

While thetm_isdst field of thetime.struct_time object can beused to disambiguate local times in the fold, the semantics of suchdisambiguation are completely different from the proposal in this PEP.

The main problem with thetm_isdst field is that it is impossibleto know what value is appropriate fortm_isdst without knowing thedetails about the time zone that are only available to thetzinfoimplementation. Thus whiletm_isdst is useful in theoutput ofmethods such astime.localtime, it is cumbersome as aninput ofmethods such astime.mktime.

If the programmer misspecified a non-negative value oftm_isdst totime.mktime, the result will be time that is 1 hour off and sincethere is rarely a way to know anything about DSTbefore a call totime.mktime is made, the only sane choice is usuallytm_isdst=-1.

Unliketm_isdst, the proposedfold attribute has no effect onthe interpretation of the datetime instance unless without thatattribute two (or no) interpretations are possible.

Since it would be very confusing to have something calledisdstthat does not have the same semantics astm_isdst, we need adifferent name. Moreover, thedatetime.datetime class already hasa method calleddst() and if we calledfold “isdst”, we wouldnecessarily have situations when “isdst” is zero butdst() is notor the other way around.

Backward Compatibility

It has been suggested that backward compatibility can be improved ifthe default value of thefold flag wasNone which wouldsignal that pre-PEP behavior is requested. Based on the analysisbelow, we believe that the proposed changes with thefold=0default are sufficiently backward compatible.

This PEP provides only three ways for a program to discover that twootherwise identical datetime instances have different values offold: (1) an explicit check of thefold attribute; (2) ifthe instances are naive - conversion to another timezone using theastimezone() method; and (3) conversion tofloat using thetimestamp() method.

Sincefold is a new attribute, the first option is not availableto the existing programs. Note that option (2) only works for naivedatetimes that happen to be in a fold or a gap in the system timezone. In all other cases, the value offold will be ignored inthe conversion unless the instances use afold-awaretzinfowhich would not be available in a pre-PEP program. Similarly, theastimezone() called on a naive instance will not be available insuch program becauseastimezone() does not currently work withnaive datetimes.

This leaves us with only one situation where an existing program canstart producing different results after the implementation of this PEP:when adatetime.timestamp() method is called on a naive datetimeinstance that happen to be in the fold or the gap. In the currentimplementation, the result is undefined. Depending on the systemmktime implementation, the programs can see different results orerrors in those cases. With this PEP in place, the value of timestampwill be well-defined in those cases but will depend on the value ofthefold flag. We consider the change indatetime.timestamp() method behavior a bug fix enabled by thisPEP. The old behavior can still be emulated by the users who dependon it by writingtime.mktime(dt.timetuple())+1e-6*dt.microsecondinstead ofdt.timestamp().

Analogy with tm_isdst

Thetime.mktime interface allows three values for thetm_isdstflag: -1, 0, and 1. As we explained above, -1 (askingmktime todetermine whether DST is in effect for the given time from the rest ofthe fields) is the only choice that is useful in practice.

With thefold flag, however,datetime.timestamp() will returnthe same value asmktime withtm_isdst=-1 in 99.98% of thetime for most time zones with DST transitions. Moreover,tm_isdst=-1-like behavior is specifiedregardless of the valueoffold.

It is only in the 0.02% cases (2 hours per year) that thedatetime.timestamp() andmktime withtm_isdst=-1 maydisagree. However, even in this case, most of themktimeimplementations will return thefold=0 or thefold=1value even though relevant standards allowmktime to return -1 andset an error code in those cases.

In other words,tm_isdst=-1 behavior is not missing from this PEP.To the contrary, it is the only behavior provided in two differentwell-defined flavors. The behavior that is missing is when a givenlocal hour is interpreted as a different local hour because of themisspecifiedtm_isdst.

For example, in the DST-observing time zones in the Northernhemisphere (where DST is in effect in June) one can get

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

Note that 12:00 was interpreted as 13:00 bymktime. With thedatetime.timestamp,datetime.fromtimestamp, it is currentlyguaranteed that

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

This PEP extends the same guarantee to both values offold:

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

Thus one of the suggested uses forfold=-1 – to match the legacybehavior – is not needed. Either choice offold will match theold behavior except in the few cases where the old behavior wasundefined.

Strict Invalid Time Checking

Another suggestion was to usefold=-1 orfold=None toindicate that the program truly has no means to deal with the foldsand gaps anddt.utcoffset() should raise an error wheneverdtrepresents an ambiguous or missing local time.

The main problem with this proposal, is thatdt.utcoffset() isused internally in situations where raising an error is not an option:for example, in dictionary lookups or list/set membership checks. Sostrict gap/fold checking behavior would need to be controlled by aseparate flag, saydt.utcoffset(raise_on_gap=True,raise_on_fold=False). However, this functionality can be easilyimplemented in user code:

defutcoffset(dt,raise_on_gap=True,raise_on_fold=False):u=dt.utcoffset()v=dt.replace(fold=notdt.fold).utcoffset()ifu==v:returnuif(u<v)==dt.fold:ifraise_on_fold:raiseAmbiguousTimeErrorelse:ifraise_on_gap:raiseMissingTimeErrorreturnu

Moreover, raising an error in the problem cases is only one of manypossible solutions. An interactive program can ask the user foradditional input, while a server process may log a warning and take anappropriate default action. We cannot possibly provide functions forall possible user requirements, but this PEP provides the means toimplement any desired behavior in a few lines of code.