Aware and Naive Objects¶

Date and time objects may be categorized as “aware” or “naive” depending onwhether or not they include time zone 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 time zone 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 time zones with fixed offsets from UTC, such as UTC itself orNorth American EST and EDT time zones. Supporting time zones 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 is 1.

datetime.MAXYEAR¶

The largest year number allowed in adate ordatetime object.MAXYEAR is 9999.

datetime.UTC¶

Alias for the UTC time zone singletondatetime.timezone.utc.

Added in version 3.11.

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 twodatetimeordate 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.

Added in version 3.2.

Objects of these types are immutable.

Subclass relationships:

objecttimedeltatzinfotimezonetimedatedatetime

timedelta Objects¶

Atimedelta object represents a duration, the difference between twodatetime ordate instances.

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

All arguments are optional and default to 0. 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)

Since the string representation oftimedelta objects can be confusing,use the following recipe to produce a more readable format:

>>>defpretty_timedelta(td):...iftd.days>=0:...returnstr(td)...returnf'-({-td!s})'...>>>d=timedelta(hours=-1)>>>str(d)# not human-friendly'-1 day, 23:00:00'>>>pretty_timedelta(d)'-(1:00:00)'

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 is greater than-timedelta.min.-timedelta.max is not representable as atimedelta object.

Instance attributes (read-only):

timedelta.days¶

Between -999,999,999 and 999,999,999 inclusive.

timedelta.seconds¶

Between 0 and 86,399 inclusive.

Caution

It is a somewhat common bug for code to unintentionally use this attributewhen it is actually intended to get atotal_seconds()value instead:

>>>fromdatetimeimporttimedelta>>>duration=timedelta(seconds=11235813)>>>duration.days,duration.seconds(130, 3813)>>>duration.total_seconds()11235813.0

timedelta.microseconds¶

Between 0 and 999,999 inclusive.

Supported operations:

Notes:

1. This is exact but may overflow.

2. This is exact and cannot overflow.

3. Division by zero 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).

timedelta objects support equality and order comparisons.

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.

Added 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 any validISO 8601 format, with the following exceptions:

1. Reduced precision dates are not currently supported (YYYY-MM,YYYY).

2. Extended date representations are not currently supported(±YYYYYY-MM-DD).

3. Ordinal dates are not currently supported (YYYY-OOO).

Examples:

>>>fromdatetimeimportdate>>>date.fromisoformat('2019-12-04')datetime.date(2019, 12, 4)>>>date.fromisoformat('20191204')datetime.date(2019, 12, 4)>>>date.fromisoformat('2021-W01-1')datetime.date(2021, 1, 4)

Added in version 3.7.

Changed in version 3.11:Previously, this method only supported the formatYYYY-MM-DD.

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

Added 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, anddate2+timedelta==date1 after.

4. date objects are equal if they represent the same date.

   date objects that are not alsodatetime instancesare never equal todatetime objects, even if they representthe same date.

5. date1 is considered less thandate2 whendate1 precedesdate2 in time.In other words,date1<date2 if and only ifdate1.toordinal()<date2.toordinal().

   Order comparison between adate object that is not also adatetime instance and adatetime object raisesTypeError.

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 newdate object with the same values, but with specifiedparameters updated.

Example:

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

The generic functioncopy.replace() also supportsdateobjects.

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 with 1 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 anamed tuple object with three components:year,week andweekday.

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()datetime.IsoCalendarDate(year=2004, week=1, weekday=1)>>>date(2004,1,4).isocalendar()datetime.IsoCalendarDate(year=2004, week=1, weekday=7)

Changed in version 3.9:Result changed from a tuple to anamed tuple.

date.isoformat()¶

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

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

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.See alsostrftime() and strptime() Behavior anddate.isoformat().

date.__format__(format)¶

Same asdate.strftime(). This makes it possible to specify a formatstring for adate object informatted stringliterals and when usingstr.format().See alsostrftime() and strptime() Behavior anddate.isoformat().

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

Changed in version 3.6:Added thefold parameter.

Other constructors, all class methods:

classmethoddatetime.today()¶

Return the current local date and time, 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().

Note

Subsequent calls todatetime.now() may return the sameinstant depending on the precision of the underlying clock.

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

Deprecated since version 3.12:Usedatetime.now() withUTC instead.

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.

Deprecated since version 3.12:Usedatetime.fromtimestamp() withUTC instead.

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=time.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. If thedate argument is adatetime object, its time componentsandtzinfo attributes are ignored.

For anydatetime objectd,d==datetime.combine(d.date(),d.time(),d.tzinfo).

Changed in version 3.6:Added thetzinfo argument.

classmethoddatetime.fromisoformat(date_string)¶

Return adatetime corresponding to adate_string in any validISO 8601 format, with the following exceptions:

1. Time zone offsets may have fractional seconds.

2. TheT separator may be replaced by any single unicode character.

3. Fractional hours and minutes are not supported.

4. Reduced precision dates are not currently supported (YYYY-MM,YYYY).

5. Extended date representations are not currently supported(±YYYYYY-MM-DD).

6. Ordinal dates are not currently supported (YYYY-OOO).

Examples:

>>>fromdatetimeimportdatetime>>>datetime.fromisoformat('2011-11-04')datetime.datetime(2011, 11, 4, 0, 0)>>>datetime.fromisoformat('20111104')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-04T00:05:23Z')datetime.datetime(2011, 11, 4, 0, 5, 23, tzinfo=datetime.timezone.utc)>>>datetime.fromisoformat('20111104T000523')datetime.datetime(2011, 11, 4, 0, 5, 23)>>>datetime.fromisoformat('2011-W01-2T00:05:23.283')datetime.datetime(2011, 1, 4, 0, 5, 23, 283000)>>>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)))

Added in version 3.7.

Changed in version 3.11:Previously, this method only supported formats that could be emitted bydate.isoformat() ordatetime.isoformat().

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

Added in version 3.8.

classmethoddatetime.strptime(date_string,format)¶

Return adatetime corresponding todate_string, parsed according toformat.

Ifformat does not contain microseconds or time zone information, 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. See alsostrftime() and strptime() Behavior anddatetime.fromisoformat().

Changed in version 3.13:Ifformat specifies a day of month without a year aDeprecationWarning is now emitted. This is to avoid a quadrennialleap year bug in code seeking to parse only a month and day as thedefault year used in absence of one in the format is not a leap year.Suchformat values may raise an error as of Python 3.15. Theworkaround is to always include a year in yourformat. If parsingdate_string values that do not have a year, explicitly add a year thatis a leap year before parsing:

>>>fromdatetimeimportdatetime>>>date_string="02/29">>>when=datetime.strptime(f"{date_string};1984","%m/%d;%Y")# Avoids leap year bug.>>>when.strftime("%B%d")'February 29'

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 values 0 and 1 represent, respectively, the earlier and later of the twomoments with the same wall time representation.

Added in version 3.6.

Supported operations:

1. datetime2 is a duration oftimedelta removed fromdatetime1, 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 thedatetime2 such thatdatetime2+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. Theresult is(a.replace(tzinfo=None)-a.utcoffset())-(b.replace(tzinfo=None)-b.utcoffset()) except that the implementation never overflows.

4. datetime objects are equal if they represent the same dateand time, taking into account the time zone.

   Naive and awaredatetime objects are never equal.

   If both comparands are aware, and have the sametzinfo attribute,thetzinfo andfold attributes are ignored andthe base datetimes are compared.If both comparands are aware and have differenttzinfoattributes, the comparison acts as comparands were first converted to UTCdatetimes except that the implementation never overflows.datetime instances in a repeated interval are never equal todatetime instances in other time zone.

5. datetime1 is considered less thandatetime2 whendatetime1 precedesdatetime2 in time, taking into account the time zone.

   Order comparison between naive and awaredatetime objectsraisesTypeError.

   If both comparands are aware, and have the sametzinfo attribute,thetzinfo andfold attributes are ignored andthe base datetimes are compared.If both comparands are aware and have differenttzinfoattributes, the comparison acts as comparands were first converted to UTCdatetimes except that the implementation never overflows.

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 newdatetime object with the same attributes, but withspecified parameters updated. Note thattzinfo=None can be specified tocreate a naive datetime from an aware datetime with no conversion of dateand time data.

datetime objects are also supported by generic functioncopy.replace().

Changed in version 3.6:Added thefold parameter.

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 time zone.

If called without arguments (or withtz=None) the system localtime zone is assumed for the target time zone. 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 time zonetz, 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 atimezone objecttz to a datetimedt withoutadjustment of date and time data, usedt.replace(tzinfo=tz). If youmerely want to remove thetimezone 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 timezone 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 with 1 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 to 1; elsetm_isdst isset to 0.

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, usingdatetime.utctimetuple() 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 orOSErrorfor times far in 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()

Added 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 time zone 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 anamed tuple with three components:year,weekandweekday. 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'

Changed in version 3.6:Added thetimespec parameter.

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 format string.See alsostrftime() and strptime() Behavior anddatetime.isoformat().

datetime.__format__(format)¶

Same asdatetime.strftime(). This makes it possible to specify a formatstring for adatetime object informatted stringliterals and when usingstr.format().See alsostrftime() and strptime() Behavior anddatetime.isoformat().

>>>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 to 0 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 values 0 and 1 represent, respectively, the earlier and later of the twomoments with the same wall time representation.

Added in version 3.6.

time objects support equality and order comparisons,wherea is considered less thanb whena precedesb in time.

Naive and awaretime objects are never equal.Order comparison between naive and awaretime objects raisesTypeError.

If both comparands are aware, and have the sametzinfoattribute, thetzinfo andfold attributes areignored 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 Boolean contexts, atime object is always considered to be true.

Other constructor:

classmethodtime.fromisoformat(time_string)¶

Return atime corresponding to atime_string in any validISO 8601 format, with the following exceptions:

1. Time zone offsets may have fractional seconds.

2. The leadingT, normally required in cases where there may be ambiguity betweena date and a time, is not required.

3. Fractional seconds may have any number of digits (anything beyond 6 willbe truncated).

4. Fractional hours and minutes are not supported.

Examples:

>>>fromdatetimeimporttime>>>time.fromisoformat('04:23:01')datetime.time(4, 23, 1)>>>time.fromisoformat('T04:23:01')datetime.time(4, 23, 1)>>>time.fromisoformat('T042301')datetime.time(4, 23, 1)>>>time.fromisoformat('04:23:01.000384')datetime.time(4, 23, 1, 384)>>>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)))>>>time.fromisoformat('04:23:01Z')datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)>>>time.fromisoformat('04:23:01+00:00')datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)

Added in version 3.7.

Changed in version 3.11:Previously, this method only supported formats that could be emitted bytime.isoformat().

Instance methods:

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

Return a newtime with the same values, but with specifiedparameters updated. Note thattzinfo=None can be specified to create anaivetime from an awaretime, without conversion of thetime data.

time objects are also supported by generic functioncopy.replace().

Changed in version 3.6:Added thefold parameter.

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'

Changed in version 3.6:Added thetimespec parameter.

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. See alsostrftime() and strptime() Behavior andtime.isoformat().

time.__format__(format)¶

Same astime.strftime(). This makes it possible to specifya format string for atime object informatted stringliterals and when usingstr.format().See alsostrftime() and strptime() Behavior andtime.isoformat().

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 time zones 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/NewYork" 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 time zones.

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# https://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")