Aware and Naive Objects¶

Date and time objects may be categorized as “aware” or “naive” depending onwhether or not they include timezone information.

With sufficient knowledge of applicable algorithmic and political timeadjustments, such as time zone and daylight saving time information,anaware object can locate itself relative to other aware objects.An aware object represents a specific moment in time that is not open tointerpretation.1

Anaive object does not contain enough information to unambiguously locateitself relative to other date/time objects. Whether a naive object representsCoordinated Universal Time (UTC), local time, or time in some other timezone ispurely up to the program, just like it is up to the program whether aparticular number represents metres, miles, or mass. Naive objects are easy tounderstand and to work with, at the cost of ignoring some aspects of reality.

For applications requiring aware objects,datetime andtimeobjects have an optional time zone information attribute,tzinfo, thatcan be set to an instance of a subclass of the abstracttzinfo class.Thesetzinfo objects capture information about the offset from UTCtime, the time zone name, and whether daylight saving time is in effect.

Only one concretetzinfo class, thetimezone class, issupplied by thedatetime module. Thetimezone class canrepresent simple timezones with fixed offsets from UTC, such as UTC itself orNorth American EST and EDT timezones. Supporting timezones at deeper levels ofdetail is up to the application. The rules for time adjustment across theworld are more political than rational, change frequently, and there is nostandard suitable for every application aside from UTC.

Constants¶

Thedatetime module exports the following constants:

datetime.MINYEAR¶

The smallest year number allowed in adate ordatetime object.MINYEAR is1.

datetime.MAXYEAR¶

The largest year number allowed in adate ordatetime object.MAXYEAR is9999.

Available Types¶

classdatetime.date

An idealized naive date, assuming the current Gregorian calendar always was, andalways will be, in effect. Attributes:year,month, andday.

classdatetime.time

An idealized time, independent of any particular day, assuming that every dayhas exactly 24*60*60 seconds. (There is no notion of “leap seconds” here.)Attributes:hour,minute,second,microsecond,andtzinfo.

classdatetime.datetime

A combination of a date and a time. Attributes:year,month,day,hour,minute,second,microsecond,andtzinfo.

classdatetime.timedelta

A duration expressing the difference between twodate,time,ordatetime instances to microsecond resolution.

classdatetime.tzinfo

An abstract base class for time zone information objects. These are used by thedatetime andtime classes to provide a customizable notion oftime adjustment (for example, to account for time zone and/or daylight savingtime).

classdatetime.timezone

A class that implements thetzinfo abstract base class as afixed offset from the UTC.

New in version 3.2.

Objects of these types are immutable.

Subclass relationships:

objecttimedeltatzinfotimezonetimedatedatetime

timedelta Objects¶

Atimedelta object represents a duration, the difference between twodates or times.

classdatetime.timedelta(days=0,seconds=0,microseconds=0,milliseconds=0,minutes=0,hours=0,weeks=0)¶

All arguments are optional and default to0. Arguments may be integersor floats, and may be positive or negative.

Onlydays,seconds andmicroseconds are stored internally.Arguments are converted to those units:

• A millisecond is converted to 1000 microseconds.

• A minute is converted to 60 seconds.

• An hour is converted to 3600 seconds.

• A week is converted to 7 days.

and days, seconds and microseconds are then normalized so that therepresentation is unique, with

• 0<=microseconds<1000000

• 0<=seconds<3600*24 (the number of seconds in one day)

• -999999999<=days<=999999999

The following example illustrates how any arguments besidesdays,seconds andmicroseconds are “merged” and normalized into thosethree resulting attributes:

>>>fromdatetimeimporttimedelta>>>delta=timedelta(...days=50,...seconds=27,...microseconds=10,...milliseconds=29000,...minutes=5,...hours=8,...weeks=2...)>>># Only days, seconds, and microseconds remain>>>deltadatetime.timedelta(days=64, seconds=29156, microseconds=10)

If any argument is a float and there are fractional microseconds,the fractional microseconds left over from all arguments arecombined and their sum is rounded to the nearest microsecond usinground-half-to-even tiebreaker. If no argument is a float, theconversion and normalization processes are exact (no information islost).

If the normalized value of days lies outside the indicated range,OverflowError is raised.

Note that normalization of negative values may be surprising at first. Forexample:

>>>fromdatetimeimporttimedelta>>>d=timedelta(microseconds=-1)>>>(d.days,d.seconds,d.microseconds)(-1, 86399, 999999)

Class attributes:

timedelta.min¶

The most negativetimedelta object,timedelta(-999999999).

timedelta.max¶

The most positivetimedelta object,timedelta(days=999999999,hours=23,minutes=59,seconds=59,microseconds=999999).

timedelta.resolution¶

The smallest possible difference between non-equaltimedelta objects,timedelta(microseconds=1).

Note that, because of normalization,timedelta.max >-timedelta.min.-timedelta.max is not representable as atimedelta object.

Instance attributes (read-only):

Supported operations:

Notes:

1. This is exact but may overflow.

2. This is exact and cannot overflow.

3. Division by 0 raisesZeroDivisionError.

4. -timedelta.max is not representable as atimedelta object.

5. String representations oftimedelta objects are normalizedsimilarly to their internal representation. This leads to somewhatunusual results for negative timedeltas. For example:

   >>>timedelta(hours=-5)datetime.timedelta(days=-1, seconds=68400)>>>print(_)-1 day, 19:00:00

6. The expressiont2-t3 will always be equal to the expressiont2+(-t3) exceptwhen t3 is equal totimedelta.max; in that case the former will produce a resultwhile the latter will overflow.

In addition to the operations listed above,timedelta objects supportcertain additions and subtractions withdate anddatetimeobjects (see below).

Comparisons oftimedelta objects are supported, with some caveats.

The comparisons== or!=always return abool, no matterthe type of the compared object:

>>>fromdatetimeimporttimedelta>>>delta1=timedelta(seconds=57)>>>delta2=timedelta(hours=25,seconds=2)>>>delta2!=delta1True>>>delta2==5False

For all other comparisons (such as< and>), when atimedeltaobject is compared to an object of a different type,TypeErroris raised:

>>>delta2>delta1True>>>delta2>5Traceback (most recent call last):  File"<stdin>", line1, in<module>TypeError:'>' not supported between instances of 'datetime.timedelta' and 'int'

In Boolean contexts, atimedelta object isconsidered to be true if and only if it isn’t equal totimedelta(0).

Instance methods:

timedelta.total_seconds()¶

Return the total number of seconds contained in the duration. Equivalent totd/timedelta(seconds=1). For interval units other than seconds, use thedivision form directly (e.g.td/timedelta(microseconds=1)).

Note that for very large time intervals (greater than 270 years onmost platforms) this method will lose microsecond accuracy.

New in version 3.2.

>>># Components of another_year add up to exactly 365 days>>>fromdatetimeimporttimedelta>>>year=timedelta(days=365)>>>another_year=timedelta(weeks=40,days=84,hours=23,...minutes=50,seconds=600)>>>year==another_yearTrue>>>year.total_seconds()31536000.0

>>>fromdatetimeimporttimedelta>>>year=timedelta(days=365)>>>ten_years=10*year>>>ten_yearsdatetime.timedelta(days=3650)>>>ten_years.days//36510>>>nine_years=ten_years-year>>>nine_yearsdatetime.timedelta(days=3285)>>>three_years=nine_years//3>>>three_years,three_years.days//365(datetime.timedelta(days=1095), 3)

date Objects¶

Adate object represents a date (year, month and day) in an idealizedcalendar, the current Gregorian calendar indefinitely extended in bothdirections.

January 1 of year 1 is called day number 1, January 2 of year 1 iscalled day number 2, and so on.2

classdatetime.date(year,month,day)¶

All arguments are required. Arguments must be integers, in the followingranges:

• MINYEAR<=year<=MAXYEAR

• 1<=month<=12

• 1<=day<=numberofdaysinthegivenmonthandyear

If an argument outside those ranges is given,ValueError is raised.

Other constructors, all class methods:

classmethoddate.today()¶

Return the current local date.

This is equivalent todate.fromtimestamp(time.time()).

classmethoddate.fromtimestamp(timestamp)¶

Return the local date corresponding to the POSIX timestamp, such as isreturned bytime.time().

This may raiseOverflowError, if the timestamp is outof the range of values supported by the platform Clocaltime()function, andOSError onlocaltime() failure.It’s common for this to be restricted to years from 1970 through 2038. Notethat on non-POSIX systems that include leap seconds in their notion of atimestamp, leap seconds are ignored byfromtimestamp().

Changed in version 3.3:RaiseOverflowError instead ofValueError if the timestampis out of the range of values supported by the platform Clocaltime() function. RaiseOSError instead ofValueError onlocaltime() failure.

classmethoddate.fromordinal(ordinal)¶

Return the date corresponding to the proleptic Gregorian ordinal, whereJanuary 1 of year 1 has ordinal 1.

ValueError is raised unless1<=ordinal<=date.max.toordinal(). For any dated,date.fromordinal(d.toordinal())==d.

classmethoddate.fromisoformat(date_string)¶

Return adate corresponding to adate_string given in the formatYYYY-MM-DD:

>>>fromdatetimeimportdate>>>date.fromisoformat('2019-12-04')datetime.date(2019, 12, 4)

This is the inverse ofdate.isoformat(). It only supports the formatYYYY-MM-DD.

New in version 3.7.

classmethoddate.fromisocalendar(year,week,day)¶

Return adate corresponding to the ISO calendar date specified byyear, week and day. This is the inverse of the functiondate.isocalendar().

New in version 3.8.

Class attributes:

date.min¶

The earliest representable date,date(MINYEAR,1,1).

date.max¶

The latest representable date,date(MAXYEAR,12,31).

date.resolution¶

The smallest possible difference between non-equal date objects,timedelta(days=1).

Instance attributes (read-only):

date.year¶

BetweenMINYEAR andMAXYEAR inclusive.

date.month¶

Between 1 and 12 inclusive.

date.day¶

Between 1 and the number of days in the given month of the given year.

Supported operations:

Notes:

1. date2 is moved forward in time iftimedelta.days>0, or backward iftimedelta.days<0. Afterwarddate2-date1==timedelta.days.timedelta.seconds andtimedelta.microseconds are ignored.OverflowError is raised ifdate2.year would be smaller thanMINYEAR or larger thanMAXYEAR.

2. timedelta.seconds andtimedelta.microseconds are ignored.

3. This is exact, and cannot overflow. timedelta.seconds andtimedelta.microseconds are 0, and date2 + timedelta == date1 after.

4. In other words,date1<date2 if and only ifdate1.toordinal()<date2.toordinal(). Date comparison raisesTypeError ifthe other comparand isn’t also adate object. However,NotImplemented is returned instead if the other comparand has atimetuple() attribute. This hook gives other kinds of date objects achance at implementing mixed-type comparison. If not, when adateobject is compared to an object of a different type,TypeError is raisedunless the comparison is== or!=. The latter cases returnFalse orTrue, respectively.

In Boolean contexts, alldate objects are considered to be true.

Instance methods:

date.replace(year=self.year,month=self.month,day=self.day)¶

Return a date with the same value, except for those parameters given newvalues by whichever keyword arguments are specified.

Example:

>>>fromdatetimeimportdate>>>d=date(2002,12,31)>>>d.replace(day=26)datetime.date(2002, 12, 26)

date.timetuple()¶

Return atime.struct_time such as returned bytime.localtime().

The hours, minutes and seconds are 0, and the DST flag is -1.

d.timetuple() is equivalent to:

time.struct_time((d.year,d.month,d.day,0,0,0,d.weekday(),yday,-1))

whereyday=d.toordinal()-date(d.year,1,1).toordinal()+1is the day number within the current year starting with1 for January 1st.

date.toordinal()¶

Return the proleptic Gregorian ordinal of the date, where January 1 of year 1has ordinal 1. For anydate objectd,date.fromordinal(d.toordinal())==d.

date.weekday()¶

Return the day of the week as an integer, where Monday is 0 and Sunday is 6.For example,date(2002,12,4).weekday()==2, a Wednesday. See alsoisoweekday().

date.isoweekday()¶

Return the day of the week as an integer, where Monday is 1 and Sunday is 7.For example,date(2002,12,4).isoweekday()==3, a Wednesday. See alsoweekday(),isocalendar().

date.isocalendar()¶

Return a 3-tuple, (ISO year, ISO week number, ISO weekday).

The ISO calendar is a widely used variant of the Gregorian calendar.3

The ISO year consists of 52 or 53 full weeks, and where a week starts on aMonday and ends on a Sunday. The first week of an ISO year is the first(Gregorian) calendar week of a year containing a Thursday. This is called weeknumber 1, and the ISO year of that Thursday is the same as its Gregorian year.

For example, 2004 begins on a Thursday, so the first week of ISO year 2004begins on Monday, 29 Dec 2003 and ends on Sunday, 4 Jan 2004:

>>>fromdatetimeimportdate>>>date(2003,12,29).isocalendar()(2004, 1, 1)>>>date(2004,1,4).isocalendar()(2004, 1, 7)

date.isoformat()¶

Return a string representing the date in ISO 8601 format,YYYY-MM-DD:

>>>fromdatetimeimportdate>>>date(2002,12,4).isoformat()'2002-12-04'

This is the inverse ofdate.fromisoformat().

date.__str__()¶

For a dated,str(d) is equivalent tod.isoformat().

date.ctime()¶

Return a string representing the date:

>>>fromdatetimeimportdate>>>date(2002,12,4).ctime()'Wed Dec  4 00:00:00 2002'

d.ctime() is equivalent to:

time.ctime(time.mktime(d.timetuple()))

on platforms where the native Cctime() function (whichtime.ctime() invokes, but whichdate.ctime() does not invoke) conforms to the C standard.

date.strftime(format)¶

Return a string representing the date, controlled by an explicit format string.Format codes referring to hours, minutes or seconds will see 0 values. For acomplete list of formatting directives, seestrftime() and strptime() Behavior.

date.__format__(format)¶

Same asdate.strftime(). This makes it possible to specify a formatstring for adate object informatted stringliterals and when usingstr.format(). For acomplete list of formatting directives, seestrftime() and strptime() Behavior.

>>>importtime>>>fromdatetimeimportdate>>>today=date.today()>>>todaydatetime.date(2007, 12, 5)>>>today==date.fromtimestamp(time.time())True>>>my_birthday=date(today.year,6,24)>>>ifmy_birthday<today:...my_birthday=my_birthday.replace(year=today.year+1)>>>my_birthdaydatetime.date(2008, 6, 24)>>>time_to_birthday=abs(my_birthday-today)>>>time_to_birthday.days202

>>>fromdatetimeimportdate>>>d=date.fromordinal(730920)# 730920th day after 1. 1. 0001>>>ddatetime.date(2002, 3, 11)>>># Methods related to formatting string output>>>d.isoformat()'2002-03-11'>>>d.strftime("%d/%m/%y")'11/03/02'>>>d.strftime("%A%d. %B %Y")'Monday 11. March 2002'>>>d.ctime()'Mon Mar 11 00:00:00 2002'>>>'The{1} is {0:%d}, the{2} is {0:%B}.'.format(d,"day","month")'The day is 11, the month is March.'>>># Methods for to extracting 'components' under different calendars>>>t=d.timetuple()>>>foriint:...print(i)2002                # year3                   # month11                  # day0000                   # weekday (0 = Monday)70                  # 70th day in the year-1>>>ic=d.isocalendar()>>>foriinic:...print(i)2002                # ISO year11                  # ISO week number1                   # ISO day number ( 1 = Monday )>>># A date object is immutable; all operations produce a new object>>>d.replace(year=2005)datetime.date(2005, 3, 11)

datetime Objects¶

Adatetime object is a single object containing all the informationfrom adate object and atime object.

Like adate object,datetime assumes the current Gregoriancalendar extended in both directions; like atime object,datetime assumes there are exactly 3600*24 seconds in every day.

Constructor:

classdatetime.datetime(year,month,day,hour=0,minute=0,second=0,microsecond=0,tzinfo=None,*,fold=0)¶

Theyear,month andday arguments are required.tzinfo may beNone, or aninstance of atzinfo subclass. The remaining arguments must be integersin the following ranges:

• MINYEAR<=year<=MAXYEAR,

• 1<=month<=12,

• 1<=day<=numberofdaysinthegivenmonthandyear,

• 0<=hour<24,

• 0<=minute<60,

• 0<=second<60,

• 0<=microsecond<1000000,

• foldin[0,1].

If an argument outside those ranges is given,ValueError is raised.

New in version 3.6:Added thefold argument.

Other constructors, all class methods:

classmethoddatetime.today()¶

Return the current local datetime, withtzinfoNone.

Equivalent to:

datetime.fromtimestamp(time.time())

See alsonow(),fromtimestamp().

This method is functionally equivalent tonow(), but without atz parameter.

classmethoddatetime.now(tz=None)¶

Return the current local date and time.

If optional argumenttz isNoneor not specified, this is liketoday(), but, if possible, supplies moreprecision than can be gotten from going through atime.time() timestamp(for example, this may be possible on platforms supplying the Cgettimeofday() function).

Iftz is notNone, it must be an instance of atzinfo subclass,and the current date and time are converted totz’s time zone.

This function is preferred overtoday() andutcnow().

classmethoddatetime.utcnow()¶

Return the current UTC date and time, withtzinfoNone.

This is likenow(), but returns the current UTC date and time, as a naivedatetime object. An aware current UTC datetime can be obtained bycallingdatetime.now(timezone.utc). See alsonow().

Warning

Because naivedatetime objects are treated by manydatetime methodsas local times, it is preferred to use aware datetimes to represent timesin UTC. As such, the recommended way to create an object representing thecurrent time in UTC is by callingdatetime.now(timezone.utc).

classmethoddatetime.fromtimestamp(timestamp,tz=None)¶

Return the local date and time corresponding to the POSIX timestamp, such as isreturned bytime.time(). If optional argumenttz isNone or notspecified, the timestamp is converted to the platform’s local date and time, andthe returneddatetime object is naive.

Iftz is notNone, it must be an instance of atzinfo subclass, and thetimestamp is converted totz’s time zone.

fromtimestamp() may raiseOverflowError, if the timestamp is out ofthe range of values supported by the platform Clocaltime() orgmtime() functions, andOSError onlocaltime() orgmtime() failure.It’s common for this to be restricted to years in1970 through 2038. Note that on non-POSIX systems that include leap seconds intheir notion of a timestamp, leap seconds are ignored byfromtimestamp(),and then it’s possible to have two timestamps differing by a second that yieldidenticaldatetime objects. This method is preferred overutcfromtimestamp().

Changed in version 3.3:RaiseOverflowError instead ofValueError if the timestampis out of the range of values supported by the platform Clocaltime() orgmtime() functions. RaiseOSErrorinstead ofValueError onlocaltime() orgmtime()failure.

Changed in version 3.6:fromtimestamp() may return instances withfold set to 1.

classmethoddatetime.utcfromtimestamp(timestamp)¶

Return the UTCdatetime corresponding to the POSIX timestamp, withtzinfoNone. (The resulting object is naive.)

This may raiseOverflowError, if the timestamp isout of the range of values supported by the platform Cgmtime() function,andOSError ongmtime() failure.It’s common for this to be restricted to years in 1970 through 2038.

To get an awaredatetime object, callfromtimestamp():

datetime.fromtimestamp(timestamp,timezone.utc)

On the POSIX compliant platforms, it is equivalent to the followingexpression:

datetime(1970,1,1,tzinfo=timezone.utc)+timedelta(seconds=timestamp)

except the latter formula always supports the full years range: betweenMINYEAR andMAXYEAR inclusive.

Warning

Because naivedatetime objects are treated by manydatetime methodsas local times, it is preferred to use aware datetimes to represent timesin UTC. As such, the recommended way to create an object representing aspecific timestamp in UTC is by callingdatetime.fromtimestamp(timestamp,tz=timezone.utc).

Changed in version 3.3:RaiseOverflowError instead ofValueError if the timestampis out of the range of values supported by the platform Cgmtime() function. RaiseOSError instead ofValueError ongmtime() failure.

classmethoddatetime.fromordinal(ordinal)¶

Return thedatetime corresponding to the proleptic Gregorian ordinal,where January 1 of year 1 has ordinal 1.ValueError is raised unless1<=ordinal<=datetime.max.toordinal(). The hour, minute, second andmicrosecond of the result are all 0, andtzinfo isNone.

classmethoddatetime.combine(date,time,tzinfo=self.tzinfo)¶

Return a newdatetime object whose date components are equal to thegivendate object’s, and whose time componentsare equal to the giventime object’s. If thetzinfoargument is provided, its value is used to set thetzinfo attributeof the result, otherwise thetzinfo attribute of thetime argumentis used.

For anydatetime objectd,d==datetime.combine(d.date(),d.time(),d.tzinfo). If date is adatetime object, its time components andtzinfo attributesare ignored.

Changed in version 3.6:Added thetzinfo argument.

classmethoddatetime.fromisoformat(date_string)¶

Return adatetime corresponding to adate_string in one of theformats emitted bydate.isoformat() anddatetime.isoformat().

Specifically, this function supports strings in the format:

YYYY-MM-DD[*HH[:MM[:SS[.fff[fff]]]][+HH:MM[:SS[.ffffff]]]]

where* can match any single character.

Caution

This doesnot support parsing arbitrary ISO 8601 strings - it is only intendedas the inverse operation ofdatetime.isoformat(). A more full-featuredISO 8601 parser,dateutil.parser.isoparse is available in the third-party packagedateutil.

Examples:

>>>fromdatetimeimportdatetime>>>datetime.fromisoformat('2011-11-04')datetime.datetime(2011, 11, 4, 0, 0)>>>datetime.fromisoformat('2011-11-04T00:05:23')datetime.datetime(2011, 11, 4, 0, 5, 23)>>>datetime.fromisoformat('2011-11-04 00:05:23.283')datetime.datetime(2011, 11, 4, 0, 5, 23, 283000)>>>datetime.fromisoformat('2011-11-04 00:05:23.283+00:00')datetime.datetime(2011, 11, 4, 0, 5, 23, 283000, tzinfo=datetime.timezone.utc)>>>datetime.fromisoformat('2011-11-04T00:05:23+04:00')datetime.datetime(2011, 11, 4, 0, 5, 23,    tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))

New in version 3.7.

classmethoddatetime.fromisocalendar(year,week,day)¶

Return adatetime corresponding to the ISO calendar date specifiedby year, week and day. The non-date components of the datetime are populatedwith their normal default values. This is the inverse of the functiondatetime.isocalendar().

New in version 3.8.

classmethoddatetime.strptime(date_string,format)¶

Return adatetime corresponding todate_string, parsed according toformat.

This is equivalent to:

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

ValueError is raised if the date_string and formatcan’t be parsed bytime.strptime() or if it returns a value which isn’t atime tuple. For a complete list of formatting directives, seestrftime() and strptime() Behavior.

Class attributes:

datetime.min¶

The earliest representabledatetime,datetime(MINYEAR,1,1,tzinfo=None).

datetime.max¶

The latest representabledatetime,datetime(MAXYEAR,12,31,23,59,59,999999,tzinfo=None).

datetime.resolution¶

The smallest possible difference between non-equaldatetime objects,timedelta(microseconds=1).

Instance attributes (read-only):

datetime.year¶

BetweenMINYEAR andMAXYEAR inclusive.

datetime.month¶

Between 1 and 12 inclusive.

datetime.day¶

Between 1 and the number of days in the given month of the given year.

datetime.hour¶

Inrange(24).

datetime.minute¶

Inrange(60).

datetime.second¶

Inrange(60).

datetime.microsecond¶

Inrange(1000000).

datetime.tzinfo¶

The object passed as thetzinfo argument to thedatetime constructor,orNone if none was passed.

datetime.fold¶

In[0,1]. Used to disambiguate wall times during a repeated interval. (Arepeated interval occurs when clocks are rolled back at the end of daylight savingtime or when the UTC offset for the current zone is decreased for political reasons.)The value 0 (1) represents the earlier (later) of the two moments with the same walltime representation.

New in version 3.6.

Supported operations:

1. datetime2 is a duration of timedelta removed from datetime1, moving forward intime iftimedelta.days > 0, or backward iftimedelta.days < 0. Theresult has the sametzinfo attribute as the input datetime, anddatetime2 - datetime1 == timedelta after.OverflowError is raised ifdatetime2.year would be smaller thanMINYEAR or larger thanMAXYEAR. Note that no time zone adjustments are done even if theinput is an aware object.

2. Computes the datetime2 such that datetime2 + timedelta == datetime1. As foraddition, the result has the sametzinfo attribute as the inputdatetime, and no time zone adjustments are done even if the input is aware.

3. Subtraction of adatetime from adatetime is defined only ifboth operands are naive, or if both are aware. If one is aware and the other isnaive,TypeError is raised.

   If both are naive, or both are aware and have the sametzinfo attribute,thetzinfo attributes are ignored, and the result is atimedeltaobjectt such thatdatetime2+t==datetime1. No time zone adjustmentsare done in this case.

   If both are aware and have differenttzinfo attributes,a-b actsas ifa andb were first converted to naive UTC datetimes first. Theresult is(a.replace(tzinfo=None)-a.utcoffset())-(b.replace(tzinfo=None)-b.utcoffset()) except that the implementation never overflows.

4. datetime1 is considered less thandatetime2 whendatetime1 precedesdatetime2 in time.

   If one comparand is naive and the other is aware,TypeErroris raised if an order comparison is attempted. For equalitycomparisons, naive instances are never equal to aware instances.

   If both comparands are aware, and have the sametzinfo attribute, thecommontzinfo attribute is ignored and the base datetimes arecompared. If both comparands are aware and have differenttzinfoattributes, the comparands are first adjusted by subtracting their UTCoffsets (obtained fromself.utcoffset()).

   Changed in version 3.3:Equality comparisons between aware and naivedatetimeinstances don’t raiseTypeError.

   Note

   In order to stop comparison from falling back to the default scheme of comparingobject addresses, datetime comparison normally raisesTypeError if theother comparand isn’t also adatetime object. However,NotImplemented is returned instead if the other comparand has atimetuple() attribute. This hook gives other kinds of date objects achance at implementing mixed-type comparison. If not, when adatetimeobject is compared to an object of a different type,TypeError is raisedunless the comparison is== or!=. The latter cases returnFalse orTrue, respectively.

Instance methods:

datetime.date()¶

Returndate object with same year, month and day.

datetime.time()¶

Returntime object with same hour, minute, second, microsecond and fold.tzinfo isNone. See also methodtimetz().

Changed in version 3.6:The fold value is copied to the returnedtime object.

datetime.timetz()¶

Returntime object with same hour, minute, second, microsecond, fold, andtzinfo attributes. See also methodtime().

Changed in version 3.6:The fold value is copied to the returnedtime object.

datetime.replace(year=self.year,month=self.month,day=self.day,hour=self.hour,minute=self.minute,second=self.second,microsecond=self.microsecond,tzinfo=self.tzinfo,*,fold=0)¶

Return a datetime with the same attributes, except for those attributes givennew values by whichever keyword arguments are specified. Note thattzinfo=None can be specified to create a naive datetime from an awaredatetime with no conversion of date and time data.

New in version 3.6:Added thefold argument.

datetime.astimezone(tz=None)¶

Return adatetime object with newtzinfo attributetz,adjusting the date and time data so the result is the same UTC time asself, but intz’s local time.

If provided,tz must be an instance of atzinfo subclass, and itsutcoffset() anddst() methods must not returnNone. Ifselfis naive, it is presumed to represent time in the system timezone.

If called without arguments (or withtz=None) the system localtimezone is assumed for the target timezone. The.tzinfo attribute of the converteddatetime instance will be set to an instance oftimezonewith the zone name and offset obtained from the OS.

Ifself.tzinfo istz,self.astimezone(tz) is equal toself: noadjustment of date or time data is performed. Else the result is localtime in the timezonetz, representing the same UTC time asself: afterastz=dt.astimezone(tz),astz-astz.utcoffset() will havethe same date and time data asdt-dt.utcoffset().

If you merely want to attach a time zone objecttz to a datetimedt withoutadjustment of date and time data, usedt.replace(tzinfo=tz). If youmerely want to remove the time zone object from an aware datetimedt withoutconversion of date and time data, usedt.replace(tzinfo=None).

Note that the defaulttzinfo.fromutc() method can be overridden in atzinfo subclass to affect the result returned byastimezone().Ignoring error cases,astimezone() acts like:

defastimezone(self,tz):ifself.tzinfoistz:returnself# Convert self to UTC, and attach the new time zone object.utc=(self-self.utcoffset()).replace(tzinfo=tz)# Convert from UTC to tz's local time.returntz.fromutc(utc)

Changed in version 3.3:tz now can be omitted.

Changed in version 3.6:Theastimezone() method can now be called on naive instances thatare presumed to represent system local time.

datetime.utcoffset()¶

Iftzinfo isNone, returnsNone, else returnsself.tzinfo.utcoffset(self), and raises an exception if the latter doesn’treturnNone or atimedelta object with magnitude less than one day.

Changed in version 3.7:The UTC offset is not restricted to a whole number of minutes.

datetime.dst()¶

Iftzinfo isNone, returnsNone, else returnsself.tzinfo.dst(self), and raises an exception if the latter doesn’t returnNone or atimedelta object with magnitude less than one day.

Changed in version 3.7:The DST offset is not restricted to a whole number of minutes.

datetime.tzname()¶

Iftzinfo isNone, returnsNone, else returnsself.tzinfo.tzname(self), raises an exception if the latter doesn’t returnNone or a string object,

datetime.timetuple()¶

Return atime.struct_time such as returned bytime.localtime().

d.timetuple() is equivalent to:

time.struct_time((d.year,d.month,d.day,d.hour,d.minute,d.second,d.weekday(),yday,dst))

whereyday=d.toordinal()-date(d.year,1,1).toordinal()+1is the day number within the current year starting with1 for January1st. Thetm_isdst flag of the result is set according to thedst() method:tzinfo isNone ordst() returnsNone,tm_isdst is set to-1; else ifdst() returns anon-zero value,tm_isdst is set to1; elsetm_isdst isset to0.

datetime.utctimetuple()¶

Ifdatetime instanced is naive, this is the same asd.timetuple() except thattm_isdst is forced to 0 regardless of whatd.dst() returns. DST is never in effect for a UTC time.

Ifd is aware,d is normalized to UTC time, by subtractingd.utcoffset(), and atime.struct_time for thenormalized time is returned.tm_isdst is forced to 0. Notethat anOverflowError may be raised ifd.year wasMINYEAR orMAXYEAR and UTC adjustment spills over a yearboundary.

Warning

Because naivedatetime objects are treated by manydatetime methodsas local times, it is preferred to use aware datetimes to represent timesin UTC; as a result, usingutcfromtimetuple may give misleadingresults. If you have a naivedatetime representing UTC, usedatetime.replace(tzinfo=timezone.utc) to make it aware, at which pointyou can usedatetime.timetuple().

datetime.toordinal()¶

Return the proleptic Gregorian ordinal of the date. The same asself.date().toordinal().

datetime.timestamp()¶

Return POSIX timestamp corresponding to thedatetimeinstance. The return value is afloat similar to thatreturned bytime.time().

Naivedatetime instances are assumed to represent localtime and this method relies on the platform Cmktime()function to perform the conversion. Sincedatetimesupports wider range of values thanmktime() on manyplatforms, this method may raiseOverflowError for times farin the past or far in the future.

For awaredatetime instances, the return value is computedas:

(dt-datetime(1970,1,1,tzinfo=timezone.utc)).total_seconds()

New in version 3.3.

Changed in version 3.6:Thetimestamp() method uses thefold attribute todisambiguate the times during a repeated interval.

Note

There is no method to obtain the POSIX timestamp directly from anaivedatetime instance representing UTC time. If yourapplication uses this convention and your system timezone is notset to UTC, you can obtain the POSIX timestamp by supplyingtzinfo=timezone.utc:

timestamp=dt.replace(tzinfo=timezone.utc).timestamp()

or by calculating the timestamp directly:

timestamp=(dt-datetime(1970,1,1))/timedelta(seconds=1)

datetime.weekday()¶

Return the day of the week as an integer, where Monday is 0 and Sunday is 6.The same asself.date().weekday(). See alsoisoweekday().

datetime.isoweekday()¶

Return the day of the week as an integer, where Monday is 1 and Sunday is 7.The same asself.date().isoweekday(). See alsoweekday(),isocalendar().

datetime.isocalendar()¶

Return a 3-tuple, (ISO year, ISO week number, ISO weekday). The same asself.date().isocalendar().

datetime.isoformat(sep='T',timespec='auto')¶

Return a string representing the date and time in ISO 8601 format:

• YYYY-MM-DDTHH:MM:SS.ffffff, ifmicrosecond is not 0

• YYYY-MM-DDTHH:MM:SS, ifmicrosecond is 0

Ifutcoffset() does not returnNone, a string isappended, giving the UTC offset:

• YYYY-MM-DDTHH:MM:SS.ffffff+HH:MM[:SS[.ffffff]], ifmicrosecondis not 0

• YYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]], ifmicrosecond is 0

Examples:

>>>fromdatetimeimportdatetime,timezone>>>datetime(2019,5,18,15,17,8,132263).isoformat()'2019-05-18T15:17:08.132263'>>>datetime(2019,5,18,15,17,tzinfo=timezone.utc).isoformat()'2019-05-18T15:17:00+00:00'

The optional argumentsep (default'T') is a one-character separator,placed between the date and time portions of the result. For example:

>>>fromdatetimeimporttzinfo,timedelta,datetime>>>classTZ(tzinfo):..."""A time zone with an arbitrary, constant -06:39 offset."""...defutcoffset(self,dt):...returntimedelta(hours=-6,minutes=-39)...>>>datetime(2002,12,25,tzinfo=TZ()).isoformat(' ')'2002-12-25 00:00:00-06:39'>>>datetime(2009,11,27,microsecond=100,tzinfo=TZ()).isoformat()'2009-11-27T00:00:00.000100-06:39'

The optional argumenttimespec specifies the number of additionalcomponents of the time to include (the default is'auto').It can be one of the following:

• 'auto': Same as'seconds' ifmicrosecond is 0,same as'microseconds' otherwise.

• 'hours': Include thehour in the two-digitHH format.

• 'minutes': Includehour andminute inHH:MM format.

• 'seconds': Includehour,minute, andsecondinHH:MM:SS format.

• 'milliseconds': Include full time, but truncate fractional secondpart to milliseconds.HH:MM:SS.sss format.

• 'microseconds': Include full time inHH:MM:SS.ffffff format.

Note

Excluded time components are truncated, not rounded.

ValueError will be raised on an invalidtimespec argument:

>>>fromdatetimeimportdatetime>>>datetime.now().isoformat(timespec='minutes')'2002-12-25T00:00'>>>dt=datetime(2015,1,1,12,30,59,0)>>>dt.isoformat(timespec='microseconds')'2015-01-01T12:30:59.000000'

New in version 3.6:Added thetimespec argument.

datetime.__str__()¶

For adatetime instanced,str(d) is equivalent tod.isoformat('').

datetime.ctime()¶

Return a string representing the date and time:

>>>fromdatetimeimportdatetime>>>datetime(2002,12,4,20,30,40).ctime()'Wed Dec  4 20:30:40 2002'

The output string willnot include time zone information, regardlessof whether the input is aware or naive.

d.ctime() is equivalent to:

time.ctime(time.mktime(d.timetuple()))

on platforms where the native Cctime() function(whichtime.ctime() invokes, but whichdatetime.ctime() does not invoke) conforms to the C standard.

datetime.strftime(format)¶

Return a string representing the date and time, controlled by an explicit formatstring. For a complete list of formatting directives, seestrftime() and strptime() Behavior.

datetime.__format__(format)¶

Same asdatetime.strftime(). This makes it possible to specify a formatstring for adatetime object informatted stringliterals and when usingstr.format(). For acomplete list of formatting directives, seestrftime() and strptime() Behavior.

>>>fromdatetimeimportdatetime,date,time,timezone>>># Using datetime.combine()>>>d=date(2005,7,14)>>>t=time(12,30)>>>datetime.combine(d,t)datetime.datetime(2005, 7, 14, 12, 30)>>># Using datetime.now()>>>datetime.now()datetime.datetime(2007, 12, 6, 16, 29, 43, 79043)   # GMT +1>>>datetime.now(timezone.utc)datetime.datetime(2007, 12, 6, 15, 29, 43, 79060, tzinfo=datetime.timezone.utc)>>># Using datetime.strptime()>>>dt=datetime.strptime("21/11/06 16:30","%d/%m/%y %H:%M")>>>dtdatetime.datetime(2006, 11, 21, 16, 30)>>># Using datetime.timetuple() to get tuple of all attributes>>>tt=dt.timetuple()>>>foritintt:...print(it)...2006    # year11      # month21      # day16      # hour30      # minute0       # second1       # weekday (0 = Monday)325     # number of days since 1st January-1      # dst - method tzinfo.dst() returned None>>># Date in ISO format>>>ic=dt.isocalendar()>>>foritinic:...print(it)...2006    # ISO year47      # ISO week2       # ISO weekday>>># Formatting a datetime>>>dt.strftime("%A,%d. %B %Y %I:%M%p")'Tuesday, 21. November 2006 04:30PM'>>>'The{1} is {0:%d}, the{2} is {0:%B}, the{3} is {0:%I:%M%p}.'.format(dt,"day","month","time")'The day is 21, the month is November, the time is 04:30PM.'

fromdatetimeimporttimedelta,datetime,tzinfo,timezoneclassKabulTz(tzinfo):# Kabul used +4 until 1945, when they moved to +4:30UTC_MOVE_DATE=datetime(1944,12,31,20,tzinfo=timezone.utc)defutcoffset(self,dt):ifdt.year<1945:returntimedelta(hours=4)elif(1945,1,1,0,0)<=dt.timetuple()[:5]<(1945,1,1,0,30):# An ambiguous ("imaginary") half-hour range representing# a 'fold' in time due to the shift from +4 to +4:30.# If dt falls in the imaginary range, use fold to decide how# to resolve. See PEP495.returntimedelta(hours=4,minutes=(30ifdt.foldelse0))else:returntimedelta(hours=4,minutes=30)deffromutc(self,dt):# Follow same validations as in datetime.tzinfoifnotisinstance(dt,datetime):raiseTypeError("fromutc() requires a datetime argument")ifdt.tzinfoisnotself:raiseValueError("dt.tzinfo is not self")# A custom implementation is required for fromutc as# the input to this function is a datetime with utc values# but with a tzinfo set to self.# See datetime.astimezone or fromtimestamp.ifdt.replace(tzinfo=timezone.utc)>=self.UTC_MOVE_DATE:returndt+timedelta(hours=4,minutes=30)else:returndt+timedelta(hours=4)defdst(self,dt):# Kabul does not observe daylight saving time.returntimedelta(0)deftzname(self,dt):ifdt>=self.UTC_MOVE_DATE:return"+04:30"return"+04"

>>>tz1=KabulTz()>>># Datetime before the change>>>dt1=datetime(1900,11,21,16,30,tzinfo=tz1)>>>print(dt1.utcoffset())4:00:00>>># Datetime after the change>>>dt2=datetime(2006,6,14,13,0,tzinfo=tz1)>>>print(dt2.utcoffset())4:30:00>>># Convert datetime to another time zone>>>dt3=dt2.astimezone(timezone.utc)>>>dt3datetime.datetime(2006, 6, 14, 8, 30, tzinfo=datetime.timezone.utc)>>>dt2datetime.datetime(2006, 6, 14, 13, 0, tzinfo=KabulTz())>>>dt2==dt3True

time Objects¶

Atime object represents a (local) time of day, independent of any particularday, and subject to adjustment via atzinfo object.

classdatetime.time(hour=0,minute=0,second=0,microsecond=0,tzinfo=None,*,fold=0)¶

All arguments are optional.tzinfo may beNone, or an instance of atzinfo subclass. The remaining arguments must be integers in thefollowing ranges:

• 0<=hour<24,

• 0<=minute<60,

• 0<=second<60,

• 0<=microsecond<1000000,

• foldin[0,1].

If an argument outside those ranges is given,ValueError is raised. Alldefault to0 excepttzinfo, which defaults toNone.

Class attributes:

time.min¶

The earliest representabletime,time(0,0,0,0).

time.max¶

The latest representabletime,time(23,59,59,999999).

time.resolution¶

The smallest possible difference between non-equaltime objects,timedelta(microseconds=1), although note that arithmetic ontime objects is not supported.

Instance attributes (read-only):

time.hour¶

Inrange(24).

time.minute¶

Inrange(60).

time.second¶

Inrange(60).

time.microsecond¶

Inrange(1000000).

time.tzinfo¶

The object passed as the tzinfo argument to thetime constructor, orNone if none was passed.

time.fold¶

In[0,1]. Used to disambiguate wall times during a repeated interval. (Arepeated interval occurs when clocks are rolled back at the end of daylight savingtime or when the UTC offset for the current zone is decreased for political reasons.)The value 0 (1) represents the earlier (later) of the two moments with the same walltime representation.

New in version 3.6.

time objects support comparison oftime totime,wherea is considered lessthanb whena precedesb in time. If one comparand is naive and the otheris aware,TypeError is raised if an order comparison is attempted. For equalitycomparisons, naive instances are never equal to aware instances.

If both comparands are aware, and havethe sametzinfo attribute, the commontzinfo attribute isignored and the base times are compared. If both comparands are aware andhave differenttzinfo attributes, the comparands are first adjusted bysubtracting their UTC offsets (obtained fromself.utcoffset()). In orderto stop mixed-type comparisons from falling back to the default comparison byobject address, when atime object is compared to an object of adifferent type,TypeError is raised unless the comparison is== or!=. The latter cases returnFalse orTrue, respectively.

In Boolean contexts, atime object is always considered to be true.

Other constructor:

classmethodtime.fromisoformat(time_string)¶

Return atime corresponding to atime_string in one of theformats emitted bytime.isoformat(). Specifically, this function supportsstrings in the format:

HH[:MM[:SS[.fff[fff]]]][+HH:MM[:SS[.ffffff]]]

Caution

This doesnot support parsing arbitrary ISO 8601 strings. It is onlyintended as the inverse operation oftime.isoformat().

Examples:

>>>fromdatetimeimporttime>>>time.fromisoformat('04:23:01')datetime.time(4, 23, 1)>>>time.fromisoformat('04:23:01.000384')datetime.time(4, 23, 1, 384)>>>time.fromisoformat('04:23:01+04:00')datetime.time(4, 23, 1, tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))

New in version 3.7.

Instance methods:

time.replace(hour=self.hour,minute=self.minute,second=self.second,microsecond=self.microsecond,tzinfo=self.tzinfo,*,fold=0)¶

Return atime with the same value, except for those attributes givennew values by whichever keyword arguments are specified. Note thattzinfo=None can be specified to create a naivetime from anawaretime, without conversion of the time data.

New in version 3.6:Added thefold argument.

time.isoformat(timespec='auto')¶

Return a string representing the time in ISO 8601 format, one of:

• HH:MM:SS.ffffff, ifmicrosecond is not 0

• HH:MM:SS, ifmicrosecond is 0

• HH:MM:SS.ffffff+HH:MM[:SS[.ffffff]], ifutcoffset() does not returnNone

• HH:MM:SS+HH:MM[:SS[.ffffff]], ifmicrosecond is 0 andutcoffset() does not returnNone

The optional argumenttimespec specifies the number of additionalcomponents of the time to include (the default is'auto').It can be one of the following:

• 'auto': Same as'seconds' ifmicrosecond is 0,same as'microseconds' otherwise.

• 'hours': Include thehour in the two-digitHH format.

• 'minutes': Includehour andminute inHH:MM format.

• 'seconds': Includehour,minute, andsecondinHH:MM:SS format.

• 'milliseconds': Include full time, but truncate fractional secondpart to milliseconds.HH:MM:SS.sss format.

• 'microseconds': Include full time inHH:MM:SS.ffffff format.

Note

Excluded time components are truncated, not rounded.

ValueError will be raised on an invalidtimespec argument.

Example:

>>>fromdatetimeimporttime>>>time(hour=12,minute=34,second=56,microsecond=123456).isoformat(timespec='minutes')'12:34'>>>dt=time(hour=12,minute=34,second=56,microsecond=0)>>>dt.isoformat(timespec='microseconds')'12:34:56.000000'>>>dt.isoformat(timespec='auto')'12:34:56'

New in version 3.6:Added thetimespec argument.

time.__str__()¶

For a timet,str(t) is equivalent tot.isoformat().

time.strftime(format)¶

Return a string representing the time, controlled by an explicit formatstring. For a complete list of formatting directives, seestrftime() and strptime() Behavior.

time.__format__(format)¶

Same astime.strftime(). This makes it possible to specify a format stringfor atime object informatted stringliterals and when usingstr.format(). For acomplete list of formatting directives, seestrftime() and strptime() Behavior.

time.utcoffset()¶

Iftzinfo isNone, returnsNone, else returnsself.tzinfo.utcoffset(None), and raises an exception if the latter doesn’treturnNone or atimedelta object with magnitude less than one day.

Changed in version 3.7:The UTC offset is not restricted to a whole number of minutes.

time.dst()¶

Iftzinfo isNone, returnsNone, else returnsself.tzinfo.dst(None), and raises an exception if the latter doesn’t returnNone, or atimedelta object with magnitude less than one day.

Changed in version 3.7:The DST offset is not restricted to a whole number of minutes.

time.tzname()¶

Iftzinfo isNone, returnsNone, else returnsself.tzinfo.tzname(None), or raises an exception if the latter doesn’treturnNone or a string object.

>>>fromdatetimeimporttime,tzinfo,timedelta>>>classTZ1(tzinfo):...defutcoffset(self,dt):...returntimedelta(hours=1)...defdst(self,dt):...returntimedelta(0)...deftzname(self,dt):...return"+01:00"...def__repr__(self):...returnf"{self.__class__.__name__}()"...>>>t=time(12,10,30,tzinfo=TZ1())>>>tdatetime.time(12, 10, 30, tzinfo=TZ1())>>>t.isoformat()'12:10:30+01:00'>>>t.dst()datetime.timedelta(0)>>>t.tzname()'+01:00'>>>t.strftime("%H:%M:%S %Z")'12:10:30 +01:00'>>>'The{} is {:%H:%M}.'.format("time",t)'The time is 12:10.'

tzinfo Objects¶

classdatetime.tzinfo¶

This is an abstract base class, meaning that this class should not beinstantiated directly. Define a subclass oftzinfo to captureinformation about a particular time zone.

An instance of (a concrete subclass of)tzinfo can be passed to theconstructors fordatetime andtime objects. The latter objectsview their attributes as being in local time, and thetzinfo objectsupports methods revealing offset of local time from UTC, the name of the timezone, and DST offset, all relative to a date or time object passed to them.

You need to derive a concrete subclass, and (at least)supply implementations of the standardtzinfo methods needed by thedatetime methods you use. Thedatetime module providestimezone, a simple concrete subclass oftzinfo which canrepresent timezones with fixed offset from UTC such as UTC itself or NorthAmerican EST and EDT.

Special requirement for pickling: Atzinfo subclass must have an__init__() method that can be called with no arguments, otherwise it can bepickled but possibly not unpickled again. This is a technical requirement thatmay be relaxed in the future.

A concrete subclass oftzinfo may need to implement the followingmethods. Exactly which methods are needed depends on the uses made of awaredatetime objects. If in doubt, simply implement all of them.

tzinfo.utcoffset(dt)¶

Return offset of local time from UTC, as atimedelta object that ispositive east of UTC. If local time is west of UTC, this should be negative.

This represents thetotal offset from UTC; for example, if atzinfo object represents both time zone and DST adjustments,utcoffset() should return their sum. If the UTC offset isn’t known,returnNone. Else the value returned must be atimedelta objectstrictly between-timedelta(hours=24) andtimedelta(hours=24)(the magnitude of the offset must be less than one day). Most implementationsofutcoffset() will probably look like one of these two:

returnCONSTANT# fixed-offset classreturnCONSTANT+self.dst(dt)# daylight-aware class

Ifutcoffset() does not returnNone,dst() should not returnNone either.

The default implementation ofutcoffset() raisesNotImplementedError.

Changed in version 3.7:The UTC offset is not restricted to a whole number of minutes.

tzinfo.dst(dt)¶

Return the daylight saving time (DST) adjustment, as atimedeltaobject orNone if DST information isn’t known.

Returntimedelta(0) if DST is not in effect.If DST is in effect, return the offset as atimedelta object(seeutcoffset() for details). Note that DST offset, if applicable, hasalready been added to the UTC offset returned byutcoffset(), so there’sno need to consultdst() unless you’re interested in obtaining DST infoseparately. For example,datetime.timetuple() calls itstzinfoattribute’sdst() method to determine how thetm_isdst flagshould be set, andtzinfo.fromutc() callsdst() to account forDST changes when crossing time zones.

An instancetz of atzinfo subclass that models both standard anddaylight times must be consistent in this sense:

tz.utcoffset(dt)-tz.dst(dt)

must return the same result for everydatetimedt withdt.tzinfo==tz For sanetzinfo subclasses, this expression yields the timezone’s “standard offset”, which should not depend on the date or the time, butonly on geographic location. The implementation ofdatetime.astimezone()relies on this, but cannot detect violations; it’s the programmer’sresponsibility to ensure it. If atzinfo subclass cannot guaranteethis, it may be able to override the default implementation oftzinfo.fromutc() to work correctly withastimezone() regardless.

Most implementations ofdst() will probably look like one of these two:

defdst(self,dt):# a fixed-offset class:  doesn't account for DSTreturntimedelta(0)

or:

defdst(self,dt):# Code to set dston and dstoff to the time zone's DST# transition times based on the input dt.year, and expressed# in standard local time.ifdston<=dt.replace(tzinfo=None)<dstoff:returntimedelta(hours=1)else:returntimedelta(0)

The default implementation ofdst() raisesNotImplementedError.

Changed in version 3.7:The DST offset is not restricted to a whole number of minutes.

tzinfo.tzname(dt)¶

Return the time zone name corresponding to thedatetime objectdt, asa string. Nothing about string names is defined by thedatetime module,and there’s no requirement that it mean anything in particular. For example,“GMT”, “UTC”, “-500”, “-5:00”, “EDT”, “US/Eastern”, “America/New York” are allvalid replies. ReturnNone if a string name isn’t known. Note that this isa method rather than a fixed string primarily because sometzinfosubclasses will wish to return different names depending on the specific valueofdt passed, especially if thetzinfo class is accounting fordaylight time.

The default implementation oftzname() raisesNotImplementedError.

These methods are called by adatetime ortime object, inresponse to their methods of the same names. Adatetime object passesitself as the argument, and atime object passesNone as theargument. Atzinfo subclass’s methods should therefore be prepared toaccept adt argument ofNone, or of classdatetime.

WhenNone is passed, it’s up to the class designer to decide the bestresponse. For example, returningNone is appropriate if the class wishes tosay that time objects don’t participate in thetzinfo protocols. Itmay be more useful forutcoffset(None) to return the standard UTC offset, asthere is no other convention for discovering the standard offset.

When adatetime object is passed in response to adatetimemethod,dt.tzinfo is the same object asself.tzinfo methods canrely on this, unless user code callstzinfo methods directly. Theintent is that thetzinfo methods interpretdt as being in localtime, and not need worry about objects in other timezones.

There is one moretzinfo method that a subclass may wish to override:

tzinfo.fromutc(dt)¶

This is called from the defaultdatetime.astimezone()implementation. When called from that,dt.tzinfo isself, anddt’sdate and time data are to be viewed as expressing a UTC time. The purposeoffromutc() is to adjust the date and time data, returning anequivalent datetime inself’s local time.

Mosttzinfo subclasses should be able to inherit the defaultfromutc() implementation without problems. It’s strong enough to handlefixed-offset time zones, and time zones accounting for both standard anddaylight time, and the latter even if the DST transition times differ indifferent years. An example of a time zone the defaultfromutc()implementation may not handle correctly in all cases is one where the standardoffset (from UTC) depends on the specific date and time passed, which can happenfor political reasons. The default implementations ofastimezone() andfromutc() may not produce the result you want if the result is one of thehours straddling the moment the standard offset changes.

Skipping code for error cases, the defaultfromutc() implementation actslike:

deffromutc(self,dt):# raise ValueError error if dt.tzinfo is not selfdtoff=dt.utcoffset()dtdst=dt.dst()# raise ValueError if dtoff is None or dtdst is Nonedelta=dtoff-dtdst# this is self's standard offsetifdelta:dt+=delta# convert to standard local timedtdst=dt.dst()# raise ValueError if dtdst is Noneifdtdst:returndt+dtdstelse:returndt

In the followingtzinfo_examples.py file there are some examples oftzinfo classes:

fromdatetimeimporttzinfo,timedelta,datetimeZERO=timedelta(0)HOUR=timedelta(hours=1)SECOND=timedelta(seconds=1)# A class capturing the platform's idea of local time.# (May result in wrong values on historical times in#  timezones where UTC offset and/or the DST rules had#  changed in the past.)importtimeas_timeSTDOFFSET=timedelta(seconds=-_time.timezone)if_time.daylight:DSTOFFSET=timedelta(seconds=-_time.altzone)else:DSTOFFSET=STDOFFSETDSTDIFF=DSTOFFSET-STDOFFSETclassLocalTimezone(tzinfo):deffromutc(self,dt):assertdt.tzinfoisselfstamp=(dt-datetime(1970,1,1,tzinfo=self))//SECONDargs=_time.localtime(stamp)[:6]dst_diff=DSTDIFF//SECOND# Detect foldfold=(args==_time.localtime(stamp-dst_diff))returndatetime(*args,microsecond=dt.microsecond,tzinfo=self,fold=fold)defutcoffset(self,dt):ifself._isdst(dt):returnDSTOFFSETelse:returnSTDOFFSETdefdst(self,dt):ifself._isdst(dt):returnDSTDIFFelse:returnZEROdeftzname(self,dt):return_time.tzname[self._isdst(dt)]def_isdst(self,dt):tt=(dt.year,dt.month,dt.day,dt.hour,dt.minute,dt.second,dt.weekday(),0,0)stamp=_time.mktime(tt)tt=_time.localtime(stamp)returntt.tm_isdst>0Local=LocalTimezone()# A complete implementation of current DST rules for major US time zones.deffirst_sunday_on_or_after(dt):days_to_go=6-dt.weekday()ifdays_to_go:dt+=timedelta(days_to_go)returndt# US DST Rules## This is a simplified (i.e., wrong for a few cases) set of rules for US# DST start and end times. For a complete and up-to-date set of DST rules# and timezone definitions, visit the Olson Database (or try pytz):# http://www.twinsun.com/tz/tz-link.htm# http://sourceforge.net/projects/pytz/ (might not be up-to-date)## In the US, since 2007, DST starts at 2am (standard time) on the second# Sunday in March, which is the first Sunday on or after Mar 8.DSTSTART_2007=datetime(1,3,8,2)# and ends at 2am (DST time) on the first Sunday of Nov.DSTEND_2007=datetime(1,11,1,2)# From 1987 to 2006, DST used to start at 2am (standard time) on the first# Sunday in April and to end at 2am (DST time) on the last# Sunday of October, which is the first Sunday on or after Oct 25.DSTSTART_1987_2006=datetime(1,4,1,2)DSTEND_1987_2006=datetime(1,10,25,2)# From 1967 to 1986, DST used to start at 2am (standard time) on the last# Sunday in April (the one on or after April 24) and to end at 2am (DST time)# on the last Sunday of October, which is the first Sunday# on or after Oct 25.DSTSTART_1967_1986=datetime(1,4,24,2)DSTEND_1967_1986=DSTEND_1987_2006defus_dst_range(year):# Find start and end times for US DST. For years before 1967, return# start = end for no DST.if2006<year:dststart,dstend=DSTSTART_2007,DSTEND_2007elif1986<year<2007:dststart,dstend=DSTSTART_1987_2006,DSTEND_1987_2006elif1966<year<1987:dststart,dstend=DSTSTART_1967_1986,DSTEND_1967_1986else:return(datetime(year,1,1),)*2start=first_sunday_on_or_after(dststart.replace(year=year))end=first_sunday_on_or_after(dstend.replace(year=year))returnstart,endclassUSTimeZone(tzinfo):def__init__(self,hours,reprname,stdname,dstname):self.stdoffset=timedelta(hours=hours)self.reprname=reprnameself.stdname=stdnameself.dstname=dstnamedef__repr__(self):returnself.reprnamedeftzname(self,dt):ifself.dst(dt):returnself.dstnameelse:returnself.stdnamedefutcoffset(self,dt):returnself.stdoffset+self.dst(dt)defdst(self,dt):ifdtisNoneordt.tzinfoisNone:# An exception may be sensible here, in one or both cases.# It depends on how you want to treat them.  The default# fromutc() implementation (called by the default astimezone()# implementation) passes a datetime with dt.tzinfo is self.returnZEROassertdt.tzinfoisselfstart,end=us_dst_range(dt.year)# Can't compare naive to aware objects, so strip the timezone from# dt first.dt=dt.replace(tzinfo=None)ifstart+HOUR<=dt<end-HOUR:# DST is in effect.returnHOURifend-HOUR<=dt<end:# Fold (an ambiguous hour): use dt.fold to disambiguate.returnZEROifdt.foldelseHOURifstart<=dt<start+HOUR:# Gap (a non-existent hour): reverse the fold rule.returnHOURifdt.foldelseZERO# DST is off.returnZEROdeffromutc(self,dt):assertdt.tzinfoisselfstart,end=us_dst_range(dt.year)start=start.replace(tzinfo=self)end=end.replace(tzinfo=self)std_time=dt+self.stdoffsetdst_time=std_time+HOURifend<=dst_time<end+HOUR:# Repeated hourreturnstd_time.replace(fold=1)ifstd_time<startordst_time>=end:# Standard timereturnstd_timeifstart<=std_time<end-HOUR:# Daylight saving timereturndst_timeEastern=USTimeZone(-5,"Eastern","EST","EDT")Central=USTimeZone(-6,"Central","CST","CDT")Mountain=USTimeZone(-7,"Mountain","MST","MDT")Pacific=USTimeZone(-8,"Pacific","PST","PDT")

Note that there are unavoidable subtleties twice per year in atzinfosubclass accounting for both standard and daylight time, at the DST transitionpoints. For concreteness, consider US Eastern (UTC -0500), where EDT begins theminute after 1:59 (EST) on the second Sunday in March, and ends the minute after1:59 (EDT) on the first Sunday in November:

UTC3:MM4:MM5:MM6:MM7:MM8:MMEST22:MM23:MM0:MM1:MM2:MM3:MMEDT23:MM0:MM1:MM2:MM3:MM4:MMstart22:MM23:MM0:MM1:MM3:MM4:MMend23:MM0:MM1:MM1:MM2:MM3:MM

When DST starts (the “start” line), the local wall clock leaps from 1:59 to3:00. A wall time of the form 2:MM doesn’t really make sense on that day, soastimezone(Eastern) won’t deliver a result withhour==2 on the day DSTbegins. For example, at the Spring forward transition of 2016, we get:

>>>fromdatetimeimportdatetime,timezone>>>fromtzinfo_examplesimportHOUR,Eastern>>>u0=datetime(2016,3,13,5,tzinfo=timezone.utc)>>>foriinrange(4):...u=u0+i*HOUR...t=u.astimezone(Eastern)...print(u.time(),'UTC =',t.time(),t.tzname())...05:00:00 UTC = 00:00:00 EST06:00:00 UTC = 01:00:00 EST07:00:00 UTC = 03:00:00 EDT08:00:00 UTC = 04:00:00 EDT

When DST ends (the “end” line), there’s a potentially worse problem: there’s anhour that can’t be spelled unambiguously in local wall time: the last hour ofdaylight time. In Eastern, that’s times of the form 5:MM UTC on the daydaylight time ends. The local wall clock leaps from 1:59 (daylight time) backto 1:00 (standard time) again. Local times of the form 1:MM are ambiguous.astimezone() mimics the local clock’s behavior by mapping two adjacent UTChours into the same local hour then. In the Eastern example, UTC times of theform 5:MM and 6:MM both map to 1:MM when converted to Eastern, but earlier timeshave thefold attribute set to 0 and the later times have it set to 1.For example, at the Fall back transition of 2016, we get:

>>>u0=datetime(2016,11,6,4,tzinfo=timezone.utc)>>>foriinrange(4):...u=u0+i*HOUR...t=u.astimezone(Eastern)...print(u.time(),'UTC =',t.time(),t.tzname(),t.fold)...04:00:00 UTC = 00:00:00 EDT 005:00:00 UTC = 01:00:00 EDT 006:00:00 UTC = 01:00:00 EST 107:00:00 UTC = 02:00:00 EST 0

Note that thedatetime instances that differ only by the value of thefold attribute are considered equal in comparisons.

Applications that can’t bear wall-time ambiguities should explicitly check thevalue of thefold attribute or avoid using hybridtzinfo subclasses; there are no ambiguities when usingtimezone,or any other fixed-offsettzinfo subclass (such as a class representingonly EST (fixed offset -5 hours), or only EDT (fixed offset -4 hours)).

timezone Objects¶

Thetimezone class is a subclass oftzinfo, eachinstance of which represents a timezone defined by a fixed offset fromUTC.

Objects of this class cannot be used to represent timezone information in thelocations where different offsets are used in different days of the year orwhere historical changes have been made to civil time.

classdatetime.timezone(offset,name=None)¶

Theoffset argument must be specified as atimedeltaobject representing the difference between the local time and UTC. It mustbe strictly between-timedelta(hours=24) andtimedelta(hours=24), otherwiseValueError is raised.

Thename argument is optional. If specified it must be a string thatwill be used as the value returned by thedatetime.tzname() method.

New in version 3.2.

Changed in version 3.7:The UTC offset is not restricted to a whole number of minutes.

timezone.utcoffset(dt)¶

Return the fixed value specified when thetimezone instance isconstructed.

Thedt argument is ignored. The return value is atimedeltainstance equal to the difference between the local time and UTC.

Changed in version 3.7:The UTC offset is not restricted to a whole number of minutes.

timezone.tzname(dt)¶

Return the fixed value specified when thetimezone instanceis constructed.

Ifname is not provided in the constructor, the name returned bytzname(dt) is generated from the value of theoffset as follows. Ifoffset istimedelta(0), the name is “UTC”, otherwise it is a string inthe formatUTC±HH:MM, where ± is the sign ofoffset, HH and MM aretwo digits ofoffset.hours andoffset.minutes respectively.

Changed in version 3.6:Name generated fromoffset=timedelta(0) is now plain‘UTC’, not'UTC+00:00'.

timezone.dst(dt)¶

Always returnsNone.

timezone.fromutc(dt)¶

Returndt+offset. Thedt argument must be an awaredatetime instance, withtzinfo set toself.

Class attributes:

timezone.utc¶

The UTC timezone,timezone(timedelta(0)).

strftime() andstrptime() Behavior¶

date,datetime, andtime objects all support astrftime(format) method, to create a string representing the time under thecontrol of an explicit format string.

Conversely, thedatetime.strptime() class method creates adatetime object from a string representing a date and time and acorresponding format string.

The table below provides a high-level comparison ofstrftime()versusstrptime():

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