Thedatetime module supplies classes for manipulating dates and times inboth simple and complex ways. While date and time arithmetic is supported, thefocus of the implementation is on efficient attribute extraction for outputformatting and manipulation. For related functionality, see also thetime andcalendar modules.
There are two kinds of date and time objects: “naive” and “aware”.
An aware object has sufficient knowledge of applicable algorithmic andpolitical time adjustments, such as time zone and daylight saving timeinformation, to locate itself relative to other aware objects. An aware objectis used to represent a specific moment in time that is not open tointerpretation[1].
A naive 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. Notethat only one concretetzinfo class, thetimezone class, issupplied by thedatetime module. Thetimezone class canrepresent simple timezones with fixed offset 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.
Thedatetime module exports the following constants:
An idealized naive date, assuming the current Gregorian calendar always was, andalways will be, in effect. Attributes:year,month, andday.
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.
A combination of a date and a time. Attributes:year,month,day,hour,minute,second,microsecond,andtzinfo.
A duration expressing the difference between twodate,time,ordatetime instances to microsecond resolution.
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).
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.
Objects of thedate type are always naive.
An object of typetime ordatetime may be naive or aware.Adatetime objectd is aware ifd.tzinfo is notNone andd.tzinfo.utcoffset(d) does not returnNone. Ifd.tzinfo isNone, or ifd.tzinfo is notNone butd.tzinfo.utcoffset(d)returnsNone,d is naive. Atime objectt is awareift.tzinfo is notNone andt.tzinfo.utcoffset(None) does not returnNone. Otherwise,t is naive.
The distinction between naive and aware doesn’t apply totimedeltaobjects.
Subclass relationships:
objecttimedeltatzinfotimezonetimedatedatetime
Atimedelta object represents a duration, the difference between twodates or times.
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 areconverted to those units:
and days, seconds and microseconds are then normalized so that therepresentation is unique, with
If any argument is a float and there are fractional microseconds, the fractionalmicroseconds left over from all arguments are combined and their sum is roundedto the nearest microsecond. If no argument is a float, the conversion andnormalization processes are exact (no information is lost).
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 are:
The most positivetimedelta object,timedelta(days=999999999,hours=23,minutes=59,seconds=59,microseconds=999999).
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):
| Attribute | Value |
|---|---|
| days | Between -999999999 and 999999999 inclusive |
| seconds | Between 0 and 86399 inclusive |
| microseconds | Between 0 and 999999 inclusive |
Supported operations:
| Operation | Result |
|---|---|
| t1=t2+t3 | Sum oft2 andt3. Afterwardst1-t2 ==t3 andt1-t3 ==t2 are true. (1) |
| t1=t2-t3 | Difference oft2 andt3. Afterwardst1==t2 -t3 andt2 ==t1 +t3 aretrue. (1) |
| t1=t2*iort1=i*t2 | Delta multiplied by an integer.Afterwardst1 // i ==t2 is true,providedi!=0. |
| In general,t1 * i ==t1 * (i-1) +t1is true. (1) | |
| t1=t2*fort1=f*t2 | Delta multiplied by a float. The result isrounded to the nearest multiple oftimedelta.resolution using round-half-to-even. |
| f=t2/t3 | Division (3) oft2 byt3. Returns afloat object. |
| t1=t2/fort1=t2/i | Delta divided by a float or an int. The resultis rounded to the nearest multiple oftimedelta.resolution using round-half-to-even. |
| t1=t2//i ort1=t2//t3 | The floor is computed and the remainder (ifany) is thrown away. In the second case, aninteger is returned. (3) |
| t1=t2%t3 | The remainder is computed as atimedelta object. (3) |
| q,r=divmod(t1,t2) | Computes the quotient and the remainder:q=t1//t2 (3) andr=t1%t2.q is an integer and r is atimedeltaobject. |
| +t1 | Returns atimedelta object with thesame value. (2) |
| -t1 | equivalent totimedelta(-t1.days, -t1.seconds,-t1.microseconds), and tot1* -1. (1)(4) |
| abs(t) | equivalent to +t whent.days>=0, andto -t whent.days<0. (2) |
| str(t) | Returns a string in the form[Dday[s],][H]H:MM:SS[.UUUUUU], where Dis negative for negativet. (5) |
| repr(t) | Returns a string in the formdatetime.timedelta(D[,S[,U]]), where Dis negative for negativet. (5) |
Notes:
This is exact, but may overflow.
This is exact, and cannot overflow.
Division by 0 raisesZeroDivisionError.
-timedelta.max is not representable as atimedelta object.
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(-1, 68400)>>>print(_)-1 day, 19:00:00
In addition to the operations listed abovetimedelta objects supportcertain additions and subtractions withdate anddatetimeobjects (see below).
Changed in version 3.2:Floor division and true division of atimedelta object by anothertimedelta object are now supported, as are remainder operations andthedivmod() function. True division and multiplication of atimedelta object by afloat object are now supported.
Comparisons oftimedelta objects are supported with thetimedelta object representing the smaller duration considered to be thesmaller timedelta. In order to stop mixed-type comparisons from falling back tothe default comparison by object address, when atimedelta object iscompared to an object of a different type,TypeError is raised unless thecomparison is== or!=. The latter cases returnFalse orTrue, respectively.
timedelta objects arehashable (usable as dictionary keys), supportefficient pickling, and in Boolean contexts, atimedelta object isconsidered to be true if and only if it isn’t equal totimedelta(0).
Instance methods:
Return the total number of seconds contained in the duration. Equivalent totd/timedelta(seconds=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.
Example usage:
>>>fromdatetimeimporttimedelta>>>year=timedelta(days=365)>>>another_year=timedelta(weeks=40,days=84,hours=23,...minutes=50,seconds=600)# adds up to 365 days>>>year.total_seconds()31536000.0>>>year==another_yearTrue>>>ten_years=10*year>>>ten_years,ten_years.days//365(datetime.timedelta(3650), 10)>>>nine_years=ten_years-year>>>nine_years,nine_years.days//365(datetime.timedelta(3285), 9)>>>three_years=nine_years//3;>>>three_years,three_years.days//365(datetime.timedelta(1095), 3)>>>abs(three_years-ten_years)==2*three_years+yearTrue
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. This matches the definition of the “prolepticGregorian” calendar in Dershowitz and Reingold’s book Calendrical Calculations,where it’s the base calendar for all computations. See the book for algorithmsfor converting between proleptic Gregorian ordinals and many other calendarsystems.
All arguments are required. Arguments may be integers, in the followingranges:
If an argument outside those ranges is given,ValueError is raised.
Other constructors, all class methods:
Return the current local date. This is equivalent todate.fromtimestamp(time.time()).
Return the local date corresponding to the POSIX timestamp, such as is returnedbytime.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.
Return the date corresponding to the proleptic Gregorian ordinal, where January1 of year 1 has ordinal 1.ValueError is raised unless1<=ordinal<=date.max.toordinal(). For any dated,date.fromordinal(d.toordinal())==d.
Class attributes:
The earliest representable date,date(MINYEAR,1,1).
The latest representable date,date(MAXYEAR,12,31).
The smallest possible difference between non-equal date objects,timedelta(days=1).
Instance attributes (read-only):
Between 1 and 12 inclusive.
Between 1 and the number of days in the given month of the given year.
Supported operations:
| Operation | Result |
|---|---|
| date2=date1+timedelta | date2 istimedelta.days days removedfromdate1. (1) |
| date2=date1-timedelta | Computesdate2 such thatdate2+timedelta==date1. (2) |
| timedelta=date1-date2 | (3) |
| date1<date2 | date1 is considered less thandate2 whendate1 precedesdate2 in time. (4) |
Notes:
Dates can be used as dictionary keys. In Boolean contexts, alldateobjects are considered to be true.
Instance methods:
Return a date with the same value, except for those parameters given newvalues by whichever keyword arguments are specified. For example, ifd==date(2002,12,31), thend.replace(day=26)==date(2002,12,26).
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 totime.struct_time((d.year,d.month,d.day,0,0,0,d.weekday(),yday,-1)), whereyday=d.toordinal()-date(d.year,1,1).toordinal()+1 is the day number within the current year starting with1 for January 1st.
Return the proleptic Gregorian ordinal of the date, where January 1 of year 1has ordinal 1. For anydate objectd,date.fromordinal(d.toordinal())==d.
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().
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().
Return a 3-tuple, (ISO year, ISO week number, ISO weekday).
The ISO calendar is a widely used variant of the Gregorian calendar. Seehttp://www.phys.uu.nl/~vgent/calendar/isocalendar.htm for a goodexplanation.
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, so thatdate(2003,12,29).isocalendar()==(2004,1,1) anddate(2004,1,4).isocalendar()==(2004,1,7).
Return a string representing the date in ISO 8601 format, ‘YYYY-MM-DD’. Forexample,date(2002,12,4).isoformat()=='2002-12-04'.
For a dated,str(d) is equivalent tod.isoformat().
Return a string representing the date, for exampledate(2002,12,4).ctime()=='WedDec400:00:002002'.d.ctime() is equivalent totime.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.
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.
Same asdate.strftime(). This makes it possible to specify formatstring for adate object when usingstr.format(). For acomplete list of formatting directives, seestrftime() and strptime() Behavior.
Example of counting days to an event:
>>>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
Example of working withdate:
>>>fromdatetimeimportdate>>>d=date.fromordinal(730920)# 730920th day after 1. 1. 0001>>>ddatetime.date(2002, 3, 11)>>>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 )>>>d.isoformat()'2002-03-11'>>>d.strftime("%d/%m/%y")'11/03/02'>>>d.strftime("%A %d. %B %Y")'Monday 11. March 2002'>>>'The {1} is {0:%d}, the {2} is {0:%B}.'.format(d,"day","month")'The day is 11, the month is March.'
Adatetime object is a single object containing all the informationfrom adate object and atime object. Like adateobject,datetime assumes the current Gregorian calendar extended inboth directions; like a time object,datetime assumes there are exactly3600*24 seconds in every day.
Constructor:
The year, month and day arguments are required.tzinfo may beNone, or aninstance of atzinfo subclass. The remaining arguments may be integers,in the following ranges:
If an argument outside those ranges is given,ValueError is raised.
Other constructors, all class methods:
Return the current local datetime, withtzinfoNone. This isequivalent todatetime.fromtimestamp(time.time()). See alsonow(),fromtimestamp().
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).
Elsetz must be an instance of a classtzinfo subclass, and thecurrent date and time are converted totz‘s time zone. In this case theresult is equivalent totz.fromutc(datetime.utcnow().replace(tzinfo=tz)).See alsotoday(),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().
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.
Elsetz must be an instance of a classtzinfo subclass, and thetimestamp is converted totz‘s time zone. In this case the result isequivalent totz.fromutc(datetime.utcfromtimestamp(timestamp).replace(tzinfo=tz)).
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. See alsoutcfromtimestamp().
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.
Return the UTCdatetime corresponding to the POSIX timestamp, withtzinfoNone. 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. See alsofromtimestamp().
On the POSIX compliant platforms,utcfromtimestamp(timestamp)is equivalent to the following expression:
datetime(1970,1,1)+timedelta(seconds=timestamp)
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.
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.
Return a newdatetime object whose date components are equal to thegivendate object’s, and whose time components andtzinfoattributes are equal to the giventime object’s. For anydatetime objectd,d==datetime.combine(d.date(),d.timetz()). If date is adatetime object, its time components andtzinfo attributesare ignored.
Return adatetime corresponding todate_string, parsed according toformat. This is equivalent todatetime(*(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:
The smallest possible difference between non-equaldatetime objects,timedelta(microseconds=1).
Instance attributes (read-only):
Between 1 and 12 inclusive.
Between 1 and the number of days in the given month of the given year.
Inrange(24).
Inrange(60).
Inrange(60).
Inrange(1000000).
The object passed as thetzinfo argument to thedatetime constructor,orNone if none was passed.
Supported operations:
| Operation | Result |
|---|---|
| datetime2=datetime1+timedelta | (1) |
| datetime2=datetime1-timedelta | (2) |
| timedelta=datetime1-datetime2 | (3) |
| datetime1<datetime2 | Comparesdatetime todatetime. (4) |
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.
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.This isn’t quite equivalent to datetime1 + (-timedelta), because -timedeltain isolation can overflow in cases where datetime1 - timedelta does not.
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.
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 naive and awaredatetimeinstances 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.
datetime objects can be used as dictionary keys. In Boolean contexts,alldatetime objects are considered to be true.
Instance methods:
Returntime object with same hour, minute, second and microsecond.tzinfo isNone. See also methodtimetz().
Returntime object with same hour, minute, second, microsecond, andtzinfo attributes. See also methodtime().
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.
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.self mustbe aware (self.tzinfo must not beNone, andself.utcoffset() mustnot returnNone).
If called without arguments (or withtz=None) the system localtimezone is assumed. Thetzinfo 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 time zonetz, representing the same UTC time asself: afterastz=dt.astimezone(tz),astz-astz.utcoffset() will usually havethe same date and time data asdt-dt.utcoffset(). The discussionof classtzinfo explains the cases at Daylight Saving Time transitionboundaries where this cannot be achieved (an issue only iftz models bothstandard and daylight time).
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.
Iftzinfo isNone, returnsNone, else returnsself.tzinfo.utcoffset(self), and raises an exception if the latter doesn’treturnNone, or atimedelta object representing a whole number ofminutes with magnitude less than one day.
Iftzinfo isNone, returnsNone, else returnsself.tzinfo.dst(self), and raises an exception if the latter doesn’t returnNone, or atimedelta object representing a whole number of minuteswith magnitude less than one day.
Iftzinfo isNone, returnsNone, else returnsself.tzinfo.tzname(self), raises an exception if the latter doesn’t returnNone or a string object,
Return atime.struct_time such as returned bytime.localtime().d.timetuple() is equivalent totime.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()+1 is the day number withinthe current year starting with1 for January 1st. Thetm_isdst flagof the result is set according to thedst() method:tzinfo isNone ordst() returnsNone,tm_isdst is set to-1;else ifdst() returns a non-zero value,tm_isdst is set to1;elsetm_isdst is set to0.
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.
Return the proleptic Gregorian ordinal of the date. The same asself.date().toordinal().
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.
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)
Return the day of the week as an integer, where Monday is 0 and Sunday is 6.The same asself.date().weekday(). See alsoisoweekday().
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().
Return a 3-tuple, (ISO year, ISO week number, ISO weekday). The same asself.date().isocalendar().
Return a string representing the date and time in ISO 8601 format,YYYY-MM-DDTHH:MM:SS.mmmmmm or, ifmicrosecond is 0,YYYY-MM-DDTHH:MM:SS
Ifutcoffset() does not returnNone, a 6-character string isappended, giving the UTC offset in (signed) hours and minutes:YYYY-MM-DDTHH:MM:SS.mmmmmm+HH:MM or, ifmicrosecond is 0YYYY-MM-DDTHH:MM:SS+HH:MM
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):...defutcoffset(self,dt):returntimedelta(minutes=-399)...>>>datetime(2002,12,25,tzinfo=TZ()).isoformat(' ')'2002-12-25 00:00:00-06:39'
Return a string representing the date and time, for exampledatetime(2002,12,4,20,30,40).ctime()=='WedDec 420:30:402002'.d.ctime() isequivalent totime.ctime(time.mktime(d.timetuple())) on platforms where thenative Cctime() function (whichtime.ctime() invokes, but whichdatetime.ctime() does not invoke) conforms to the C standard.
Return a string representing the date and time, controlled by an explicit formatstring. For a complete list of formatting directives, seestrftime() and strptime() Behavior.
Same asdatetime.strftime(). This makes it possible to specify formatstring for adatetime object when usingstr.format(). For acomplete list of formatting directives, seestrftime() and strptime() Behavior.
Examples of working with datetime objects:
>>>fromdatetimeimportdatetime,date,time>>># 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() or datetime.utcnow()>>>datetime.now()datetime.datetime(2007, 12, 6, 16, 29, 43, 79043) # GMT +1>>>datetime.utcnow()datetime.datetime(2007, 12, 6, 15, 29, 43, 79060)>>># 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 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.'
Using datetime with tzinfo:
>>>fromdatetimeimporttimedelta,datetime,tzinfo>>>classGMT1(tzinfo):...defutcoffset(self,dt):...returntimedelta(hours=1)+self.dst(dt)...defdst(self,dt):...# DST starts last Sunday in March...d=datetime(dt.year,4,1)# ends last Sunday in October...self.dston=d-timedelta(days=d.weekday()+1)...d=datetime(dt.year,11,1)...self.dstoff=d-timedelta(days=d.weekday()+1)...ifself.dston<=dt.replace(tzinfo=None)<self.dstoff:...returntimedelta(hours=1)...else:...returntimedelta(0)...deftzname(self,dt):...return"GMT +1"...>>>classGMT2(tzinfo):...defutcoffset(self,dt):...returntimedelta(hours=2)+self.dst(dt)...defdst(self,dt):...d=datetime(dt.year,4,1)...self.dston=d-timedelta(days=d.weekday()+1)...d=datetime(dt.year,11,1)...self.dstoff=d-timedelta(days=d.weekday()+1)...ifself.dston<=dt.replace(tzinfo=None)<self.dstoff:...returntimedelta(hours=1)...else:...returntimedelta(0)...deftzname(self,dt):...return"GMT +2"...>>>gmt1=GMT1()>>># Daylight Saving Time>>>dt1=datetime(2006,11,21,16,30,tzinfo=gmt1)>>>dt1.dst()datetime.timedelta(0)>>>dt1.utcoffset()datetime.timedelta(0, 3600)>>>dt2=datetime(2006,6,14,13,0,tzinfo=gmt1)>>>dt2.dst()datetime.timedelta(0, 3600)>>>dt2.utcoffset()datetime.timedelta(0, 7200)>>># Convert datetime to another time zone>>>dt3=dt2.astimezone(GMT2())>>>dt3datetime.datetime(2006, 6, 14, 14, 0, tzinfo=<GMT2 object at 0x...>)>>>dt2datetime.datetime(2006, 6, 14, 13, 0, tzinfo=<GMT1 object at 0x...>)>>>dt2.utctimetuple()==dt3.utctimetuple()True
A time object represents a (local) time of day, independent of any particularday, and subject to adjustment via atzinfo object.
All arguments are optional.tzinfo may beNone, or an instance of atzinfo subclass. The remaining arguments may be integers, in thefollowing ranges:
If an argument outside those ranges is given,ValueError is raised. Alldefault to0 excepttzinfo, which defaults toNone.
Class attributes:
The smallest possible difference between non-equaltime objects,timedelta(microseconds=1), although note that arithmetic ontime objects is not supported.
Instance attributes (read-only):
Inrange(24).
Inrange(60).
Inrange(60).
Inrange(1000000).
The object passed as the tzinfo argument to thetime constructor, orNone if none was passed.
Supported operations:
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.
hash, use as dict key
efficient pickling
in Boolean contexts, atime object is considered to be true if andonly if, after converting it to minutes and subtractingutcoffset() (or0 if that’sNone), the result is non-zero.
Instance methods:
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.
Return a string representing the time in ISO 8601 format, HH:MM:SS.mmmmmm or, ifself.microsecond is 0, HH:MM:SS Ifutcoffset() does not returnNone, a6-character string is appended, giving the UTC offset in (signed) hours andminutes: HH:MM:SS.mmmmmm+HH:MM or, if self.microsecond is 0, HH:MM:SS+HH:MM
For a timet,str(t) is equivalent tot.isoformat().
Return a string representing the time, controlled by an explicit formatstring. For a complete list of formatting directives, seestrftime() and strptime() Behavior.
Same astime.strftime(). This makes it possible to specify format stringfor atime object when usingstr.format(). For acomplete list of formatting directives, seestrftime() and strptime() Behavior.
Iftzinfo isNone, returnsNone, else returnsself.tzinfo.utcoffset(None), and raises an exception if the latter doesn’treturnNone or atimedelta object representing a whole number ofminutes with magnitude less than one day.
Iftzinfo isNone, returnsNone, else returnsself.tzinfo.dst(None), and raises an exception if the latter doesn’t returnNone, or atimedelta object representing a whole number of minuteswith magnitude less than one day.
Iftzinfo isNone, returnsNone, else returnsself.tzinfo.tzname(None), or raises an exception if the latter doesn’treturnNone or a string object.
Example:
>>>fromdatetimeimporttime,tzinfo>>>classGMT1(tzinfo):...defutcoffset(self,dt):...returntimedelta(hours=1)...defdst(self,dt):...returntimedelta(0)...deftzname(self,dt):...return"Europe/Prague"...>>>t=time(12,10,30,tzinfo=GMT1())>>>tdatetime.time(12, 10, 30, tzinfo=<GMT1 object at 0x...>)>>>gmt=GMT1()>>>t.isoformat()'12:10:30+01:00'>>>t.dst()datetime.timedelta(0)>>>t.tzname()'Europe/Prague'>>>t.strftime("%H:%M:%S %Z")'12:10:30 Europe/Prague'>>>'The {} is {:%H:%M}.'.format("time",t)'The time is 12:10.'
tzinfo is an abstract base class, meaning that this class should not beinstantiated directly. You need to derive a concrete subclass, and (at least)supply implementations of the standardtzinfo methods needed by thedatetime methods you use. Thedatetime module suppliesa simple concrete subclass oftzinfotimezone which can representtimezones with fixed offset from UTC such as UTC itself or North American EST andEDT.
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.
Special requirement for pickling: Atzinfo subclass must have an__init__() method that can be called with no arguments, else 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.
Return offset of local time from UTC, in minutes east of UTC. If local time iswest of UTC, this should be negative. Note that this is intended to be thetotal offset from UTC; for example, if atzinfo object represents bothtime zone and DST adjustments,utcoffset() should return their sum. Ifthe UTC offset isn’t known, returnNone. Else the value returned must be atimedelta object specifying a whole number of minutes in the range-1439 to 1439 inclusive (1440 = 24*60; the magnitude of the offset must be lessthan one day). Most implementations ofutcoffset() will probably looklike 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.
Return the daylight saving time (DST) adjustment, in minutes east of UTC, orNone if DST information isn’t known. Returntimedelta(0) if DST is notin 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. Thenifdston<=dt.replace(tzinfo=None)<dstoff:returntimedelta(hours=1)else:returntimedelta(0)
The default implementation ofdst() raisesNotImplementedError.
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:
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
Exampletzinfo classes:
fromdatetimeimporttzinfo,timedelta,datetimeZERO=timedelta(0)HOUR=timedelta(hours=1)# A UTC class.classUTC(tzinfo):"""UTC"""defutcoffset(self,dt):returnZEROdeftzname(self,dt):return"UTC"defdst(self,dt):returnZEROutc=UTC()# A class building tzinfo objects for fixed-offset time zones.# Note that FixedOffset(0, "UTC") is a different way to build a# UTC tzinfo object.classFixedOffset(tzinfo):"""Fixed offset in minutes east from UTC."""def__init__(self,offset,name):self.__offset=timedelta(minutes=offset)self.__name=namedefutcoffset(self,dt):returnself.__offsetdeftzname(self,dt):returnself.__namedefdst(self,dt):returnZERO# A class capturing the platform's idea of local time.importtimeas_timeSTDOFFSET=timedelta(seconds=-_time.timezone)if_time.daylight:DSTOFFSET=timedelta(seconds=-_time.altzone)else:DSTOFFSET=STDOFFSETDSTDIFF=DSTOFFSET-STDOFFSETclassLocalTimezone(tzinfo):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; 1am standard time) on the first Sunday of Nov.DSTEND_2007=datetime(1,11,1,1)# 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; 1am standard 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,1)# 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;# 1am standard 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_2006classUSTimeZone(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.tzinfoisself# Find start and end times for US DST. For years before 1967, return# ZERO for no DST.if2006<dt.year:dststart,dstend=DSTSTART_2007,DSTEND_2007elif1986<dt.year<2007:dststart,dstend=DSTSTART_1987_2006,DSTEND_1987_2006elif1966<dt.year<1987:dststart,dstend=DSTSTART_1967_1986,DSTEND_1967_1986else:returnZEROstart=first_sunday_on_or_after(dststart.replace(year=dt.year))end=first_sunday_on_or_after(dstend.replace(year=dt.year))# Can't compare naive to aware objects, so strip the timezone from# dt first.ifstart<=dt.replace(tzinfo=None)<end:returnHOURelse:returnZEROEastern=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. In order forastimezone() to make this guarantee, thetzinfo.dst() method must consider times in the “missing hour” (2:MM forEastern) to be in daylight time.
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. In order forastimezone() to make this guarantee, thetzinfo.dst() method mustconsider times in the “repeated hour” to be in standard time. This is easilyarranged, as in the example, by expressing DST switch times in the time zone’sstandard local time.
Applications that can’t bear such ambiguities should 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)).
See also
The standard library has notzinfo instances except for UTC, butthere exists a third-party library which brings theIANA timezonedatabase (also known as the Olson database) to Python:pytz.
pytz contains up-to-date information and its usage is recommended.
Thetimezone class is a subclass oftzinfo, eachinstance of which represents a timezone defined by a fixed offset fromUTC. Note that objects of this class cannot be used to representtimezone information in the locations where different offsets are usedin different days of the year or where historical changes have beenmade to civil time.
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) and represent a whole number of minutes,otherwiseValueError is raised.
Thename argument is optional. If specified it must be a string thatis used as the value returned by thetzname(dt) method. Otherwise,tzname(dt) returns a string ‘UTCsHH:MM’, where s is the sign ofoffset, HH and MM are two digits ofoffset.hours andoffset.minutes respectively.
Return the fixed value specified when thetimezone instance isconstructed. Thedt argument is ignored. The return value is atimedelta instance equal to the difference between thelocal time and UTC.
Return the fixed value specified when thetimezone instance isconstructed or a string ‘UTCsHH:MM’, where s is the sign ofoffset, HH and MM are two digits ofoffset.hours andoffset.minutes respectively.
Always returnsNone.
Returndt+offset. Thedt argument must be an awaredatetime instance, withtzinfo set toself.
Class attributes:
The UTC timezone,timezone(timedelta(0)).
date,datetime, andtime objects all support astrftime(format) method, to create a string representing the time under thecontrol of an explicit format string. Broadly speaking,d.strftime(fmt)acts like thetime module’stime.strftime(fmt,d.timetuple())although not all objects support atimetuple() method.
Conversely, thedatetime.strptime() class method creates adatetime object from a string representing a date and time and acorresponding format string.datetime.strptime(date_string,format) isequivalent todatetime(*(time.strptime(date_string,format)[0:6])).
Fortime objects, the format codes for year, month, and day should notbe used, as time objects have no such values. If they’re used anyway,1900is substituted for the year, and1 for the month and day.
Fordate objects, the format codes for hours, minutes, seconds, andmicroseconds should not be used, asdate objects have no suchvalues. If they’re used anyway,0 is substituted for them.
The full set of format codes supported varies across platforms, because Pythoncalls the platform C library’sstrftime() function, and platformvariations are common. To see the full set of format codes supported on yourplatform, consult thestrftime(3) documentation.
The following is a list of all the format codes that the C standard (1989version) requires, and these work on all platforms with a standard Cimplementation. Note that the 1999 version of the C standard added additionalformat codes.
| Directive | Meaning | Example | Notes |
|---|---|---|---|
| %a | Weekday as locale’sabbreviated name. | Sun, Mon, ..., Sat(en_US); So, Mo, ..., Sa(de_DE) | (1) |
| %A | Weekday as locale’s full name. | Sunday, Monday, ...,Saturday (en_US); Sonntag, Montag, ...,Samstag (de_DE) | (1) |
| %w | Weekday as a decimal number,where 0 is Sunday and 6 isSaturday. | 0, 1, ..., 6 | |
| %d | Day of the month as azero-padded decimal number. | 01, 02, ..., 31 | |
| %b | Month as locale’s abbreviatedname. | Jan, Feb, ..., Dec(en_US); Jan, Feb, ..., Dez(de_DE) | (1) |
| %B | Month as locale’s full name. | January, February,..., December (en_US); Januar, Februar, ...,Dezember (de_DE) | (1) |
| %m | Month as a zero-paddeddecimal number. | 01, 02, ..., 12 | |
| %y | Year without century as azero-padded decimal number. | 00, 01, ..., 99 | |
| %Y | Year with century as a decimalnumber. | 0001, 0002, ..., 2013,2014, ..., 9998, 9999 | (2) |
| %H | Hour (24-hour clock) as azero-padded decimal number. | 00, 01, ..., 23 | |
| %I | Hour (12-hour clock) as azero-padded decimal number. | 01, 02, ..., 12 | |
| %p | Locale’s equivalent of eitherAM or PM. | AM, PM (en_US); am, pm (de_DE) | (1),(3) |
| %M | Minute as a zero-paddeddecimal number. | 00, 01, ..., 59 | |
| %S | Second as a zero-paddeddecimal number. | 00, 01, ..., 59 | (4) |
| %f | Microsecond as a decimalnumber, zero-padded on theleft. | 000000, 000001, ...,999999 | (5) |
| %z | UTC offset in the form +HHMMor -HHMM (empty string if thethe object is naive). | (empty), +0000, -0400,+1030 | (6) |
| %Z | Time zone name (empty stringif the object is naive). | (empty), UTC, EST, CST | |
| %j | Day of the year as azero-padded decimal number. | 001, 002, ..., 366 | |
| %U | Week number of the year(Sunday as the first day ofthe week) as a zero paddeddecimal number. All days in anew year preceding the firstSunday are considered to be inweek 0. | 00, 01, ..., 53 | (7) |
| %W | Week number of the year(Monday as the first day ofthe week) as a decimal number.All days in a new yearpreceding the first Mondayare considered to be inweek 0. | 00, 01, ..., 53 | (7) |
| %c | Locale’s appropriate date andtime representation. | Tue Aug 16 21:30:001988 (en_US); Di 16 Aug 21:30:001988 (de_DE) | (1) |
| %x | Locale’s appropriate daterepresentation. | 08/16/88 (None); 08/16/1988 (en_US); 16.08.1988 (de_DE) | (1) |
| %X | Locale’s appropriate timerepresentation. | 21:30:00 (en_US); 21:30:00 (de_DE) | (1) |
| %% | A literal'%' character. | % |
Notes:
Because the format depends on the current locale, care should be taken whenmaking assumptions about the output value. Field orderings will vary (forexample, “month/day/year” versus “day/month/year”), and the output maycontain Unicode characters encoded using the locale’s default encoding (forexample, if the current locale isja_JP, the default encoding could beany one ofeucJP,SJIS, orutf-8; uselocale.getlocale()to determine the current locale’s encoding).
Thestrptime() method can parse years in the full [1, 9999] range, butyears < 1000 must be zero-filled to 4-digit width.
Changed in version 3.2:In previous versions,strftime() method was restricted toyears >= 1900.
Changed in version 3.3:In version 3.2,strftime() method was restricted toyears >= 1000.
When used with thestrptime() method, the%p directive only affectsthe output hour field if the%I directive is used to parse the hour.
Unlike thetime module, thedatetime module does not supportleap seconds.
When used with thestrptime() method, the%f directiveaccepts from one to six digits and zero pads on the right.%f isan extension to the set of format characters in the C standard (butimplemented separately in datetime objects, and therefore alwaysavailable).
For a naive object, the%z and%Z format codes are replaced by emptystrings.
For an aware object:
utcoffset() is transformed into a 5-character string of the form+HHMM or -HHMM, where HH is a 2-digit string giving the number of UTCoffset hours, and MM is a 2-digit string giving the number of UTC offsetminutes. For example, ifutcoffset() returnstimedelta(hours=-3,minutes=-30),%z is replaced with the string'-0330'.
Iftzname() returnsNone,%Z is replaced by an emptystring. Otherwise%Z is replaced by the returned value, which mustbe a string.
When used with thestrptime() method,%U and%W are only usedin calculations when the day of the week and the year are specified.
Footnotes
| [1] | If, that is, we ignore the effects of Relativity |
8.2.calendar — General calendar-related functions
Enter search terms or a module, class or function name.
