| % XXX what order should the types be discussed in? |
| |
| \section{\module{datetime} --- |
| Basic date and time types} |
| |
| \declaremodule{builtin}{datetime} |
| \modulesynopsis{Basic date and time types.} |
| \moduleauthor{Tim Peters}{tim@zope.com} |
| \sectionauthor{Tim Peters}{tim@zope.com} |
| \sectionauthor{A.M. Kuchling}{amk@amk.ca} |
| |
| \versionadded{2.3} |
| |
| |
| The \module{datetime} module supplies classes for manipulating dates |
| and times in both simple and complex ways. While date and time |
| arithmetic is supported, the focus of the implementation is on |
| efficient member extraction for output formatting and manipulation. |
| |
| There are two kinds of date and time objects: ``naive'' and ``aware''. |
| This distinction refers to whether the object has any notion of time |
| zone, daylight saving time, or other kind of algorithmic or political |
| time adjustment. Whether a naive \class{datetime} object represents |
| Coordinated Universal Time (UTC), local time, or time in some other |
| timezone is purely up to the program, just like it's up to the program |
| whether a particular number represents meters, miles, or mass. Naive |
| \class{datetime} objects are easy to understand and to work with, at |
| the cost of ignoring some aspects of reality. |
| |
| For applications requiring more, \class{datetime} and \class{time} |
| objects have an optional time zone information member, |
| \member{tzinfo}, that can contain an instance of a subclass of |
| the abstract \class{tzinfo} class. These \class{tzinfo} objects |
| capture information about the offset from UTC time, the time zone |
| name, and whether Daylight Saving Time is in effect. Note that no |
| concrete \class{tzinfo} classes are supplied by the \module{datetime} |
| module. Supporting timezones at whatever level of detail is required |
| is up to the application. The rules for time adjustment across the |
| world are more political than rational, and there is no standard |
| suitable for every application. |
| |
| The \module{datetime} module exports the following constants: |
| |
| \begin{datadesc}{MINYEAR} |
| The smallest year number allowed in a \class{date} or |
| \class{datetime} object. \constant{MINYEAR} |
| is \code{1}. |
| \end{datadesc} |
| |
| \begin{datadesc}{MAXYEAR} |
| The largest year number allowed in a \class{date} or \class{datetime} |
| object. \constant{MAXYEAR} is \code{9999}. |
| \end{datadesc} |
| |
| \begin{seealso} |
| \seemodule{calendar}{General calendar related functions.} |
| \seemodule{time}{Time access and conversions.} |
| \end{seealso} |
| |
| \subsection{Available Types} |
| |
| \begin{classdesc*}{date} |
| An idealized naive date, assuming the current Gregorian calendar |
| always was, and always will be, in effect. |
| Attributes: \member{year}, \member{month}, and \member{day}. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{time} |
| An idealized time, independent of any particular day, assuming |
| that every day has exactly 24*60*60 seconds (there is no notion |
| of "leap seconds" here). |
| Attributes: \member{hour}, \member{minute}, \member{second}, |
| \member{microsecond}, and \member{tzinfo}. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{datetime} |
| A combination of a date and a time. |
| Attributes: \member{year}, \member{month}, \member{day}, |
| \member{hour}, \member{minute}, \member{second}, |
| \member{microsecond}, and \member{tzinfo}. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{timedelta} |
| A duration expressing the difference between two \class{date}, |
| \class{time}, or \class{datetime} instances to microsecond |
| resolution. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{tzinfo} |
| An abstract base class for time zone information objects. These |
| are used by the \class{datetime} and \class{time} classes to |
| provide a customizable notion of time adjustment (for example, to |
| account for time zone and/or daylight saving time). |
| \end{classdesc*} |
| |
| Objects of these types are immutable. |
| |
| Objects of the \class{date} type are always naive. |
| |
| An object \var{d} of type \class{time} or \class{datetime} may be |
| naive or aware. \var{d} is aware if \code{\var{d}.tzinfo} is not |
| \code{None} and \code{\var{d}.tzinfo.utcoffset(\var{d})} does not return |
| \code{None}. If \code{\var{d}.tzinfo} is \code{None}, or if |
| \code{\var{d}.tzinfo} is not \code{None} but |
| \code{\var{d}.tzinfo.utcoffset(\var{d})} returns \code{None}, \var{d} |
| is naive. |
| |
| The distinction between naive and aware doesn't apply to |
| \code{timedelta} objects. |
| |
| Subclass relationships: |
| |
| \begin{verbatim} |
| object |
| timedelta |
| tzinfo |
| time |
| date |
| datetime |
| \end{verbatim} |
| |
| \subsection{\class{timedelta} Objects \label{datetime-timedelta}} |
| |
| A \class{timedelta} object represents a duration, the difference |
| between two dates or times. |
| |
| \begin{classdesc}{timedelta}{days=0, seconds=0, microseconds=0, |
| milliseconds=0, minutes=0, hours=0, weeks=0} |
| |
| All arguments are optional. Arguments may be ints, longs, or floats, |
| and may be positive or negative. |
| |
| Only \var{days}, \var{seconds} and \var{microseconds} are stored |
| internally. Arguments are converted to those units: |
| |
| \begin{itemize} |
| \item A millisecond is converted to 1000 microseconds. |
| \item A minute is converted to 60 seconds. |
| \item An hour is converted to 3600 seconds. |
| \item A week is converted to 7 days. |
| \end{itemize} |
| |
| and days, seconds and microseconds are then normalized so that the |
| representation is unique, with |
| |
| \begin{itemize} |
| \item \code{0 <= \var{microseconds} < 1000000} |
| \item \code{0 <= \var{seconds} < 3600*24} (the number of seconds in one day) |
| \item \code{-999999999 <= \var{days} <= 999999999} |
| \end{itemize} |
| |
| If any argument is a float and there are fractional microseconds, |
| the fractional microseconds left over from all arguments are combined |
| and their sum is rounded to the nearest microsecond. If no |
| argument is a float, the conversion and normalization processes |
| are exact (no information is lost). |
| |
| If the normalized value of days lies outside the indicated range, |
| \exception{OverflowError} is raised. |
| |
| Note that normalization of negative values may be surprising at first. |
| For example, |
| |
| \begin{verbatim} |
| >>> d = timedelta(microseconds=-1) |
| >>> (d.days, d.seconds, d.microseconds) |
| (-1, 86399, 999999) |
| \end{verbatim} |
| \end{classdesc} |
| |
| Class attributes are: |
| |
| \begin{memberdesc}{min} |
| The most negative \class{timedelta} object, |
| \code{timedelta(-999999999)}. |
| \end{memberdesc} |
| |
| \begin{memberdesc}{max} |
| The most positive \class{timedelta} object, |
| \code{timedelta(days=999999999, hours=23, minutes=59, seconds=59, |
| microseconds=999999)}. |
| \end{memberdesc} |
| |
| \begin{memberdesc}{resolution} |
| The smallest possible difference between non-equal |
| \class{timedelta} objects, \code{timedelta(microseconds=1)}. |
| \end{memberdesc} |
| |
| Note that, because of normalization, \code{timedelta.max} \textgreater |
| \code{-timedelta.min}. \code{-timedelta.max} is not representable as |
| a \class{timedelta} object. |
| |
| Instance attributes (read-only): |
| |
| \begin{tableii}{c|l}{code}{Attribute}{Value} |
| \lineii{days}{Between -999999999 and 999999999 inclusive} |
| \lineii{seconds}{Between 0 and 86399 inclusive} |
| \lineii{microseconds}{Between 0 and 999999 inclusive} |
| \end{tableii} |
| |
| Supported operations: |
| |
| % XXX this table is too wide! |
| \begin{tableii}{c|l}{code}{Operation}{Result} |
| \lineii{\var{t1} = \var{t2} + \var{t3}} |
| {Sum of \var{t2} and \var{t3}. |
| Afterwards \var{t1}-\var{t2} == \var{t3} and \var{t1}-\var{t3} |
| == \var{t2} are true. |
| (1)} |
| \lineii{\var{t1} = \var{t2} - \var{t3}} |
| {Difference of \var{t2} and \var{t3}. |
| Afterwards \var{t1} == \var{t2} - \var{t3} and \var{t2} == \var{t1} + \var{t3} are |
| true. |
| (1)} |
| \lineii{\var{t1} = \var{t2} * \var{i} or \var{t1} = \var{i} * \var{t2}} |
| {Delta multiplied by an integer or long. |
| Afterwards \var{t1} // i == \var{t2} is true, |
| provided \code{i != 0}.} |
| \lineii{}{In general, \var{t1} * i == \var{t1} * (i-1) + \var{t1} is true. |
| (1)} |
| \lineii{\var{t1} = \var{t2} // \var{i}} |
| {The floor is computed and the remainder (if any) is thrown away. |
| (3)} |
| \lineii{+\var{t1}} |
| {Returns a \class{timedelta} object with the same value. |
| (2)} |
| \lineii{-\var{t1}} |
| {equivalent to \class{timedelta}(-\var{t1.days}, -\var{t1.seconds}, |
| -\var{t1.microseconds}), and to \var{t1}* -1. |
| (1)(4)} |
| \lineii{abs(\var{t})} |
| {equivalent to +\var{t} when \code{t.days >= 0}, and to |
| -\var{t} when \code{t.days < 0}. |
| (2)} |
| \end{tableii} |
| \noindent |
| Notes: |
| |
| \begin{description} |
| \item[(1)] |
| This is exact, but may overflow. |
| |
| \item[(2)] |
| This is exact, and cannot overflow. |
| |
| \item[(3)] |
| Division by 0 raises \exception{ZeroDivisionError}. |
| |
| \item[(4)] |
| -\var{timedelta.max} is not representable as a \class{timedelta} object. |
| \end{description} |
| |
| In addition to the operations listed above \class{timedelta} objects |
| support certain additions and subtractions with \class{date} and |
| \class{datetime} objects (see below). |
| |
| Comparisons of \class{timedelta} objects are supported with the |
| \class{timedelta} object representing the smaller duration considered |
| to be the smaller timedelta. |
| In order to stop mixed-type comparisons from falling back to the |
| default comparison by object address, when a \class{timedelta} object is |
| compared to an object of a different type, \exception{TypeError} is |
| raised unless the comparison is \code{==} or \code{!=}. The latter |
| cases return \constant{False} or \constant{True}, respectively. |
| |
| \class{timedelta} objects are hashable (usable as dictionary keys), |
| support efficient pickling, and in Boolean contexts, a \class{timedelta} |
| object is considered to be true if and only if it isn't equal to |
| \code{timedelta(0)}. |
| |
| |
| \subsection{\class{date} Objects \label{datetime-date}} |
| |
| A \class{date} object represents a date (year, month and day) in an idealized |
| calendar, the current Gregorian calendar indefinitely extended in both |
| directions. January 1 of year 1 is called day number 1, January 2 of year |
| 1 is called day number 2, and so on. This matches the definition of the |
| "proleptic Gregorian" calendar in Dershowitz and Reingold's book |
| \citetitle{Calendrical Calculations}, where it's the base calendar for all |
| computations. See the book for algorithms for converting between |
| proleptic Gregorian ordinals and many other calendar systems. |
| |
| \begin{classdesc}{date}{year, month, day} |
| All arguments are required. Arguments may be ints or longs, in the |
| following ranges: |
| |
| \begin{itemize} |
| \item \code{MINYEAR <= \var{year} <= MAXYEAR} |
| \item \code{1 <= \var{month} <= 12} |
| \item \code{1 <= \var{day} <= number of days in the given month and year} |
| \end{itemize} |
| |
| If an argument outside those ranges is given, \exception{ValueError} |
| is raised. |
| \end{classdesc} |
| |
| Other constructors, all class methods: |
| |
| \begin{methoddesc}{today}{} |
| Return the current local date. This is equivalent to |
| \code{date.fromtimestamp(time.time())}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{fromtimestamp}{timestamp} |
| Return the local date corresponding to the POSIX timestamp, such |
| as is returned by \function{time.time()}. This may raise |
| \exception{ValueError}, if the timestamp is out of the range of |
| values supported by the platform C \cfunction{localtime()} |
| function. It's common for this to be restricted to years from 1970 |
| through 2038. Note that on non-POSIX systems that include leap |
| seconds in their notion of a timestamp, leap seconds are ignored by |
| \method{fromtimestamp()}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{fromordinal}{ordinal} |
| Return the date corresponding to the proleptic Gregorian ordinal, |
| where January 1 of year 1 has ordinal 1. \exception{ValueError} is |
| raised unless \code{1 <= \var{ordinal} <= date.max.toordinal()}. |
| For any date \var{d}, \code{date.fromordinal(\var{d}.toordinal()) == |
| \var{d}}. |
| \end{methoddesc} |
| |
| Class attributes: |
| |
| \begin{memberdesc}{min} |
| The earliest representable date, \code{date(MINYEAR, 1, 1)}. |
| \end{memberdesc} |
| |
| \begin{memberdesc}{max} |
| The latest representable date, \code{date(MAXYEAR, 12, 31)}. |
| \end{memberdesc} |
| |
| \begin{memberdesc}{resolution} |
| The smallest possible difference between non-equal date |
| objects, \code{timedelta(days=1)}. |
| \end{memberdesc} |
| |
| Instance attributes (read-only): |
| |
| \begin{memberdesc}{year} |
| Between \constant{MINYEAR} and \constant{MAXYEAR} inclusive. |
| \end{memberdesc} |
| |
| \begin{memberdesc}{month} |
| Between 1 and 12 inclusive. |
| \end{memberdesc} |
| |
| \begin{memberdesc}{day} |
| Between 1 and the number of days in the given month of the given |
| year. |
| \end{memberdesc} |
| |
| Supported operations: |
| |
| % XXX rewrite to be a table |
| \begin{tableii}{c|l}{code}{Operation}{Result} |
| \lineii{\var{date2} = \var{date1} + \var{timedelta}} |
| {\var{date2} is \code{\var{timedelta}.days} days removed from |
| \var{date1}. (1)} |
| |
| |
| \lineii{\var{date2} = \var{date1} - \var{timedelta}} |
| {Computes \var{date2} such that \code{\var{date2} + \var{timedelta} |
| == \var{date1}}. (2)} |
| |
| \lineii{\var{timedelta} = \var{date1} - \var{date2}} |
| {(3)} |
| |
| \lineii{\var{date1}<\var{date2}} |
| {\var{date1} is considered less than \var{date2} when \var{date1} |
| precedes \var{date2} in time. (4)} |
| |
| \end{tableii} |
| |
| Notes: |
| \begin{description} |
| |
| \item[(1)] |
| \var{date2} is moved forward in time if \code{\var{timedelta}.days |
| > 0}, or backward if \code{\var{timedelta}.days < 0}. Afterward |
| \code{\var{date2} - \var{date1} == \var{timedelta}.days}. |
| \code{\var{timedelta}.seconds} and |
| \code{\var{timedelta}.microseconds} are ignored. |
| \exception{OverflowError} is raised if \code{\var{date2}.year} |
| would be smaller than \constant{MINYEAR} or larger than |
| \constant{MAXYEAR}. |
| |
| \item[(2)] |
| This isn't quite equivalent to date1 + |
| (-timedelta), because -timedelta in isolation can overflow in cases |
| where date1 - timedelta does not. \code{\var{timedelta}.seconds} |
| and \code{\var{timedelta}.microseconds} are ignored. |
| |
| \item[(3)] |
| This is exact, and cannot overflow. timedelta.seconds and |
| timedelta.microseconds are 0, and date2 + timedelta == date1 |
| after. |
| |
| \item[(4)] |
| In other words, \code{date1 < date2} |
| if and only if \code{\var{date1}.toordinal() < |
| \var{date2}.toordinal()}. |
| In order to stop comparison from falling back to the default |
| scheme of comparing object addresses, date comparison |
| normally raises \exception{TypeError} if the other comparand |
| isn't also a \class{date} object. However, \code{NotImplemented} |
| is returned instead if the other comparand has a |
| \method{timetuple} attribute. This hook gives other kinds of |
| date objects a chance at implementing mixed-type comparison. |
| If not, when a \class{date} object is |
| compared to an object of a different type, \exception{TypeError} is |
| raised unless the comparison is \code{==} or \code{!=}. The latter |
| cases return \constant{False} or \constant{True}, respectively. |
| |
| \end{description} |
| |
| |
| Dates can be used as dictionary keys. In Boolean contexts, all |
| \class{date} objects are considered to be true. |
| |
| Instance methods: |
| |
| \begin{methoddesc}{replace}{year, month, day} |
| Return a date with the same value, except for those members given |
| new values by whichever keyword arguments are specified. For |
| example, if \code{d == date(2002, 12, 31)}, then |
| \code{d.replace(day=26) == date(2000, 12, 26)}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{timetuple}{} |
| Return a 9-element tuple of the form returned by |
| \function{time.localtime()}. The hours, minutes and seconds are |
| 0, and the DST flag is -1. |
| \code{\var{d}.timetuple()} is equivalent to |
| \code{(\var{d}.year, \var{d}.month, \var{d}.day, |
| 0, 0, 0, |
| \var{d}.weekday(), |
| \var{d}.toordinal() - date(\var{d}.year, 1, 1).toordinal() + 1, |
| -1)} |
| \end{methoddesc} |
| |
| \begin{methoddesc}{toordinal}{} |
| Return the proleptic Gregorian ordinal of the date, where January 1 |
| of year 1 has ordinal 1. For any \class{date} object \var{d}, |
| \code{date.fromordinal(\var{d}.toordinal()) == \var{d}}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{weekday}{} |
| Return the day of the week as an integer, where Monday is 0 and |
| Sunday is 6. For example, \code{date(2002, 12, 4).weekday() == 2}, a |
| Wednesday. |
| See also \method{isoweekday()}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{isoweekday}{} |
| Return the day of the week as an integer, where Monday is 1 and |
| Sunday is 7. For example, \code{date(2002, 12, 4).isoweekday() == 3}, a |
| Wednesday. |
| See also \method{weekday()}, \method{isocalendar()}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{isocalendar}{} |
| Return a 3-tuple, (ISO year, ISO week number, ISO weekday). |
| |
| The ISO calendar is a widely used variant of the Gregorian calendar. |
| See \url{http://www.phys.uu.nl/~vgent/calendar/isocalendar.htm} |
| for a good explanation. |
| |
| The ISO year consists of 52 or 53 full weeks, and where a week starts |
| on a Monday 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 week number 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 2004 begins on Monday, 29 Dec 2003 and ends on Sunday, 4 Jan |
| 2004, so that |
| \code{date(2003, 12, 29).isocalendar() == (2004, 1, 1)} |
| and |
| \code{date(2004, 1, 4).isocalendar() == (2004, 1, 7)}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{isoformat}{} |
| Return a string representing the date in ISO 8601 format, |
| 'YYYY-MM-DD'. For example, |
| \code{date(2002, 12, 4).isoformat() == '2002-12-04'}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{__str__}{} |
| For a date \var{d}, \code{str(\var{d})} is equivalent to |
| \code{\var{d}.isoformat()}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{ctime}{} |
| Return a string representing the date, for example |
| date(2002, 12, 4).ctime() == 'Wed Dec 4 00:00:00 2002'. |
| \code{\var{d}.ctime()} is equivalent to |
| \code{time.ctime(time.mktime(\var{d}.timetuple()))} |
| on platforms where the native C \cfunction{ctime()} function |
| (which \function{time.ctime()} invokes, but which |
| \method{date.ctime()} does not invoke) conforms to the C standard. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{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 the section on \method{strftime()} behavior. |
| \end{methoddesc} |
| |
| |
| \subsection{\class{datetime} Objects \label{datetime-datetime}} |
| |
| A \class{datetime} object is a single object containing all the |
| information from a \class{date} object and a \class{time} object. Like a |
| \class{date} object, \class{datetime} assumes the current Gregorian |
| calendar extended in both directions; like a time object, |
| \class{datetime} assumes there are exactly 3600*24 seconds in every |
| day. |
| |
| Constructor: |
| |
| \begin{classdesc}{datetime}{year, month, day, |
| hour=0, minute=0, second=0, microsecond=0, |
| tzinfo=None} |
| The year, month and day arguments are required. \var{tzinfo} may |
| be \code{None}, or an instance of a \class{tzinfo} subclass. The |
| remaining arguments may be ints or longs, in the following ranges: |
| |
| \begin{itemize} |
| \item \code{MINYEAR <= \var{year} <= MAXYEAR} |
| \item \code{1 <= \var{month} <= 12} |
| \item \code{1 <= \var{day} <= number of days in the given month and year} |
| \item \code{0 <= \var{hour} < 24} |
| \item \code{0 <= \var{minute} < 60} |
| \item \code{0 <= \var{second} < 60} |
| \item \code{0 <= \var{microsecond} < 1000000} |
| \end{itemize} |
| |
| If an argument outside those ranges is given, |
| \exception{ValueError} is raised. |
| \end{classdesc} |
| |
| Other constructors, all class methods: |
| |
| \begin{methoddesc}{today}{} |
| Return the current local datetime, with \member{tzinfo} \code{None}. |
| This is equivalent to |
| \code{datetime.fromtimestamp(time.time())}. |
| See also \method{now()}, \method{fromtimestamp()}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{now(tz=None)}{} |
| Return the current local date and time. If optional argument |
| \var{tz} is \code{None} or not specified, this is like |
| \method{today()}, but, if possible, supplies more precision than can |
| be gotten from going through a \function{time.time()} timestamp (for |
| example, this may be possible on platforms supplying the C |
| \cfunction{gettimeofday()} function). |
| |
| Else \var{tz} must be an instance of a class \class{tzinfo} subclass, |
| and the current date and time are converted to \var{tz}'s time |
| zone. In this case the result is equivalent to |
| \code{\var{tz}.fromutc(datetime.utcnow().replace(tzinfo=\var{tz}))}. |
| See also \method{today()}, \method{utcnow()}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{utcnow}{} |
| Return the current UTC date and time, with \member{tzinfo} \code{None}. |
| This is like \method{now()}, but returns the current UTC date and time, |
| as a naive \class{datetime} object. |
| See also \method{now()}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{fromtimestamp}{timestamp, tz=None} |
| Return the local date and time corresponding to the \POSIX{} |
| timestamp, such as is returned by \function{time.time()}. |
| If optional argument \var{tz} is \code{None} or not specified, the |
| timestamp is converted to the platform's local date and time, and |
| the returned \class{datetime} object is naive. |
| |
| Else \var{tz} must be an instance of a class \class{tzinfo} subclass, |
| and the timestamp is converted to \var{tz}'s time zone. In this case |
| the result is equivalent to |
| \code{\var{tz}.fromutc(datetime.utcfromtimestamp(\var{timestamp}).replace(tzinfo=\var{tz}))}. |
| |
| \method{fromtimestamp()} may raise \exception{ValueError}, if the |
| timestamp is out of the range of values supported by the platform C |
| \cfunction{localtime()} or \cfunction{gmtime()} functions. It's common |
| for this to be restricted to years in 1970 through 2038. |
| Note that on non-POSIX systems that include leap seconds in their |
| notion of a timestamp, leap seconds are ignored by |
| \method{fromtimestamp()}, and then it's possible to have two timestamps |
| differing by a second that yield identical \class{datetime} objects. |
| See also \method{utcfromtimestamp()}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{utcfromtimestamp}{timestamp} |
| Return the UTC \class{datetime} corresponding to the \POSIX{} |
| timestamp, with \member{tzinfo} \code{None}. |
| This may raise \exception{ValueError}, if the |
| timestamp is out of the range of values supported by the platform |
| C \cfunction{gmtime()} function. It's common for this to be |
| restricted to years in 1970 through 2038. |
| See also \method{fromtimestamp()}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{fromordinal}{ordinal} |
| Return the \class{datetime} corresponding to the proleptic |
| Gregorian ordinal, where January 1 of year 1 has ordinal 1. |
| \exception{ValueError} is raised unless \code{1 <= ordinal <= |
| datetime.max.toordinal()}. The hour, minute, second and |
| microsecond of the result are all 0, |
| and \member{tzinfo} is \code{None}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{combine}{date, time} |
| Return a new \class{datetime} object whose date members are |
| equal to the given \class{date} object's, and whose time |
| and \member{tzinfo} members are equal to the given \class{time} object's. |
| For any \class{datetime} object \var{d}, \code{\var{d} == |
| datetime.combine(\var{d}.date(), \var{d}.timetz())}. If date is a |
| \class{datetime} object, its time and \member{tzinfo} members are |
| ignored. |
| \end{methoddesc} |
| |
| Class attributes: |
| |
| \begin{memberdesc}{min} |
| The earliest representable \class{datetime}, |
| \code{datetime(MINYEAR, 1, 1, tzinfo=None)}. |
| \end{memberdesc} |
| |
| \begin{memberdesc}{max} |
| The latest representable \class{datetime}, |
| \code{datetime(MAXYEAR, 12, 31, 23, 59, 59, 999999, tzinfo=None)}. |
| \end{memberdesc} |
| |
| \begin{memberdesc}{resolution} |
| The smallest possible difference between non-equal \class{datetime} |
| objects, \code{timedelta(microseconds=1)}. |
| \end{memberdesc} |
| |
| Instance attributes (read-only): |
| |
| \begin{memberdesc}{year} |
| Between \constant{MINYEAR} and \constant{MAXYEAR} inclusive. |
| \end{memberdesc} |
| |
| \begin{memberdesc}{month} |
| Between 1 and 12 inclusive. |
| \end{memberdesc} |
| |
| \begin{memberdesc}{day} |
| Between 1 and the number of days in the given month of the given |
| year. |
| \end{memberdesc} |
| |
| \begin{memberdesc}{hour} |
| In \code{range(24)}. |
| \end{memberdesc} |
| |
| \begin{memberdesc}{minute} |
| In \code{range(60)}. |
| \end{memberdesc} |
| |
| \begin{memberdesc}{second} |
| In \code{range(60)}. |
| \end{memberdesc} |
| |
| \begin{memberdesc}{microsecond} |
| In \code{range(1000000)}. |
| \end{memberdesc} |
| |
| \begin{memberdesc}{tzinfo} |
| The object passed as the \var{tzinfo} argument to the |
| \class{datetime} constructor, or \code{None} if none was passed. |
| \end{memberdesc} |
| |
| Supported operations: |
| |
| \begin{tableii}{c|l}{code}{Operation}{Result} |
| \lineii{\var{datetime2} = \var{datetime1} + \var{timedelta}}{(1)} |
| |
| \lineii{\var{datetime2} = \var{datetime1} - \var{timedelta}}{(2)} |
| |
| \lineii{\var{timedelta} = \var{datetime1} - \var{datetime2}}{(3)} |
| |
| \lineii{\var{datetime1} < \var{datetime2}} |
| {Compares \class{datetime} to \class{datetime}. |
| (4)} |
| |
| \end{tableii} |
| |
| \begin{description} |
| |
| \item[(1)] |
| |
| datetime2 is a duration of timedelta removed from datetime1, moving |
| forward in time if \code{\var{timedelta}.days} > 0, or backward if |
| \code{\var{timedelta}.days} < 0. The result has the same \member{tzinfo} member |
| as the input datetime, and datetime2 - datetime1 == timedelta after. |
| \exception{OverflowError} is raised if datetime2.year would be |
| smaller than \constant{MINYEAR} or larger than \constant{MAXYEAR}. |
| Note that no time zone adjustments are done even if the input is an |
| aware object. |
| |
| \item[(2)] |
| Computes the datetime2 such that datetime2 + timedelta == datetime1. |
| As for addition, the result has the same \member{tzinfo} member |
| as the input datetime, and no time zone adjustments are done even |
| if the input is aware. |
| This isn't quite equivalent to datetime1 + (-timedelta), because |
| -timedelta in isolation can overflow in cases where |
| datetime1 - timedelta does not. |
| |
| \item[(3)] |
| Subtraction of a \class{datetime} from a |
| \class{datetime} is defined only if both |
| operands are naive, or if both are aware. If one is aware and the |
| other is naive, \exception{TypeError} is raised. |
| |
| If both are naive, or both are aware and have the same \member{tzinfo} |
| member, the \member{tzinfo} members are ignored, and the result is |
| a \class{timedelta} object \var{t} such that |
| \code{\var{datetime2} + \var{t} == \var{datetime1}}. No time zone |
| adjustments are done in this case. |
| |
| If both are aware and have different \member{tzinfo} members, |
| \code{a-b} acts as if \var{a} and \var{b} were first converted to |
| naive UTC datetimes first. The result is |
| \code{(\var{a}.replace(tzinfo=None) - \var{a}.utcoffset()) - |
| (\var{b}.replace(tzinfo=None) - \var{b}.utcoffset())} |
| except that the implementation never overflows. |
| |
| \item[(4)] |
| |
| \var{datetime1} is considered less than \var{datetime2} |
| when \var{datetime1} precedes \var{datetime2} in time. |
| |
| If one comparand is naive and |
| the other is aware, \exception{TypeError} is raised. If both |
| comparands are aware, and have the same \member{tzinfo} member, |
| the common \member{tzinfo} member is ignored and the base datetimes |
| are compared. If both comparands are aware and have different |
| \member{tzinfo} members, the comparands are first adjusted by |
| subtracting their UTC offsets (obtained from \code{self.utcoffset()}). |
| \note{In order to stop comparison from falling back to the default |
| scheme of comparing object addresses, datetime comparison |
| normally raises \exception{TypeError} if the other comparand |
| isn't also a \class{datetime} object. However, |
| \code{NotImplemented} is returned instead if the other comparand |
| has a \method{timetuple} attribute. This hook gives other |
| kinds of date objects a chance at implementing mixed-type |
| comparison. If not, when a \class{datetime} object is |
| compared to an object of a different type, \exception{TypeError} |
| is raised unless the comparison is \code{==} or \code{!=}. The |
| latter cases return \constant{False} or \constant{True}, |
| respectively.} |
| |
| \end{description} |
| |
| \class{datetime} objects can be used as dictionary keys. In Boolean |
| contexts, all \class{datetime} objects are considered to be true. |
| |
| |
| Instance methods: |
| |
| \begin{methoddesc}{date}{} |
| Return \class{date} object with same year, month and day. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{time}{} |
| Return \class{time} object with same hour, minute, second and microsecond. |
| \member{tzinfo} is \code{None}. See also method \method{timetz()}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{timetz}{} |
| Return \class{time} object with same hour, minute, second, microsecond, |
| and tzinfo members. See also method \method{time()}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{replace}{year=, month=, day=, hour=, minute=, second=, |
| microsecond=, tzinfo=} |
| Return a datetime with the same members, except for those members given |
| new values by whichever keyword arguments are specified. Note that |
| \code{tzinfo=None} can be specified to create a naive datetime from |
| an aware datetime with no conversion of date and time members. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{astimezone}{tz} |
| Return a \class{datetime} object with new \member{tzinfo} member |
| \var{tz}, adjusting the date and time members so the result is the |
| same UTC time as \var{self}, but in \var{tz}'s local time. |
| |
| \var{tz} must be an instance of a \class{tzinfo} subclass, and its |
| \method{utcoffset()} and \method{dst()} methods must not return |
| \code{None}. \var{self} must be aware (\code{\var{self}.tzinfo} must |
| not be \code{None}, and \code{\var{self}.utcoffset()} must not return |
| \code{None}). |
| |
| If \code{\var{self}.tzinfo} is \var{tz}, |
| \code{\var{self}.astimezone(\var{tz})} is equal to \var{self}: no |
| adjustment of date or time members is performed. |
| Else the result is local time in time zone \var{tz}, representing the |
| same UTC time as \var{self}: after \code{\var{astz} = |
| \var{dt}.astimezone(\var{tz})}, |
| \code{\var{astz} - \var{astz}.utcoffset()} will usually have the same |
| date and time members as \code{\var{dt} - \var{dt}.utcoffset()}. |
| The discussion of class \class{tzinfo} explains the cases at Daylight |
| Saving Time transition boundaries where this cannot be achieved (an issue |
| only if \var{tz} models both standard and daylight time). |
| |
| If you merely want to attach a time zone object \var{tz} to a |
| datetime \var{dt} without adjustment of date and time members, |
| use \code{\var{dt}.replace(tzinfo=\var{tz})}. If |
| you merely want to remove the time zone object from an aware datetime |
| \var{dt} without conversion of date and time members, use |
| \code{\var{dt}.replace(tzinfo=None)}. |
| |
| Note that the default \method{tzinfo.fromutc()} method can be overridden |
| in a \class{tzinfo} subclass to effect the result returned by |
| \method{astimezone()}. Ignoring error cases, \method{astimezone()} |
| acts like: |
| |
| \begin{verbatim} |
| def astimezone(self, tz): |
| if self.tzinfo is tz: |
| return self |
| # 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. |
| return tz.fromutc(utc) |
| \end{verbatim} |
| \end{methoddesc} |
| |
| \begin{methoddesc}{utcoffset}{} |
| If \member{tzinfo} is \code{None}, returns \code{None}, else |
| returns \code{\var{self}.tzinfo.utcoffset(\var{self})}, and |
| raises an exception if the latter doesn't return \code{None}, or |
| a \class{timedelta} object representing a whole number of minutes |
| with magnitude less than one day. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{dst}{} |
| If \member{tzinfo} is \code{None}, returns \code{None}, else |
| returns \code{\var{self}.tzinfo.dst(\var{self})}, and |
| raises an exception if the latter doesn't return \code{None}, or |
| a \class{timedelta} object representing a whole number of minutes |
| with magnitude less than one day. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{tzname}{} |
| If \member{tzinfo} is \code{None}, returns \code{None}, else |
| returns \code{\var{self}.tzinfo.tzname(\var{self})}, |
| raises an exception if the latter doesn't return \code{None} or |
| a string object, |
| \end{methoddesc} |
| |
| \begin{methoddesc}{timetuple}{} |
| Return a 9-element tuple of the form returned by |
| \function{time.localtime()}. |
| \code{\var{d}.timetuple()} is equivalent to |
| \code{(\var{d}.year, \var{d}.month, \var{d}.day, |
| \var{d}.hour, \var{d}.minute, \var{d}.second, |
| \var{d}.weekday(), |
| \var{d}.toordinal() - date(\var{d}.year, 1, 1).toordinal() + 1, |
| dst)} |
| The \member{tm_isdst} flag of the result is set according to |
| the \method{dst()} method: \member{tzinfo} is \code{None} or |
| \method{dst()} returns \code{None}, |
| \member{tm_isdst} is set to \code{-1}; else if \method{dst()} returns |
| a non-zero value, \member{tm_isdst} is set to \code{1}; |
| else \code{tm_isdst} is set to \code{0}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{utctimetuple}{} |
| If \class{datetime} instance \var{d} is naive, this is the same as |
| \code{\var{d}.timetuple()} except that \member{tm_isdst} is forced to 0 |
| regardless of what \code{d.dst()} returns. DST is never in effect |
| for a UTC time. |
| |
| If \var{d} is aware, \var{d} is normalized to UTC time, by subtracting |
| \code{\var{d}.utcoffset()}, and a timetuple for the |
| normalized time is returned. \member{tm_isdst} is forced to 0. |
| Note that the result's \member{tm_year} member may be |
| \constant{MINYEAR}-1 or \constant{MAXYEAR}+1, if \var{d}.year was |
| \code{MINYEAR} or \code{MAXYEAR} and UTC adjustment spills over a |
| year boundary. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{toordinal}{} |
| Return the proleptic Gregorian ordinal of the date. The same as |
| \code{self.date().toordinal()}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{weekday}{} |
| Return the day of the week as an integer, where Monday is 0 and |
| Sunday is 6. The same as \code{self.date().weekday()}. |
| See also \method{isoweekday()}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{isoweekday}{} |
| Return the day of the week as an integer, where Monday is 1 and |
| Sunday is 7. The same as \code{self.date().isoweekday)}. |
| See also \method{weekday()}, \method{isocalendar()}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{isocalendar}{} |
| Return a 3-tuple, (ISO year, ISO week number, ISO weekday). The |
| same as \code{self.date().isocalendar()}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{isoformat}{sep='T'} |
| Return a string representing the date and time in ISO 8601 format, |
| YYYY-MM-DDTHH:MM:SS.mmmmmm |
| or, if \member{microsecond} is 0, |
| YYYY-MM-DDTHH:MM:SS |
| |
| If \method{utcoffset()} does not return \code{None}, a 6-character |
| string is appended, giving the UTC offset in (signed) hours and |
| minutes: |
| YYYY-MM-DDTHH:MM:SS.mmmmmm+HH:MM |
| or, if \member{microsecond} is 0 |
| YYYY-MM-DDTHH:MM:SS+HH:MM |
| |
| The optional argument \var{sep} (default \code{'T'}) is a |
| one-character separator, placed between the date and time portions |
| of the result. For example, |
| |
| \begin{verbatim} |
| >>> from datetime import tzinfo, timedelta, datetime |
| >>> class TZ(tzinfo): |
| ... def utcoffset(self, dt): return timedelta(minutes=-399) |
| ... |
| >>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ') |
| '2002-12-25 00:00:00-06:39' |
| \end{verbatim} |
| \end{methoddesc} |
| |
| \begin{methoddesc}{__str__}{} |
| For a \class{datetime} instance \var{d}, \code{str(\var{d})} is |
| equivalent to \code{\var{d}.isoformat(' ')}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{ctime}{} |
| Return a string representing the date and time, for example |
| \code{datetime(2002, 12, 4, 20, 30, 40).ctime() == |
| 'Wed Dec 4 20:30:40 2002'}. |
| \code{d.ctime()} is equivalent to |
| \code{time.ctime(time.mktime(d.timetuple()))} on platforms where |
| the native C \cfunction{ctime()} function (which |
| \function{time.ctime()} invokes, but which |
| \method{datetime.ctime()} does not invoke) conforms to the C |
| standard. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{strftime}{format} |
| Return a string representing the date and time, controlled by an |
| explicit format string. See the section on \method{strftime()} |
| behavior. |
| \end{methoddesc} |
| |
| |
| \subsection{\class{time} Objects \label{datetime-time}} |
| |
| A time object represents a (local) time of day, independent of any |
| particular day, and subject to adjustment via a \class{tzinfo} object. |
| |
| \begin{classdesc}{time}{hour=0, minute=0, second=0, microsecond=0, |
| tzinfo=None} |
| All arguments are optional. \var{tzinfo} may be \code{None}, or |
| an instance of a \class{tzinfo} subclass. The remaining arguments |
| may be ints or longs, in the following ranges: |
| |
| \begin{itemize} |
| \item \code{0 <= \var{hour} < 24} |
| \item \code{0 <= \var{minute} < 60} |
| \item \code{0 <= \var{second} < 60} |
| \item \code{0 <= \var{microsecond} < 1000000}. |
| \end{itemize} |
| |
| If an argument outside those ranges is given, |
| \exception{ValueError} is raised. |
| \end{classdesc} |
| |
| Class attributes: |
| |
| \begin{memberdesc}{min} |
| The earliest representable \class{time}, \code{time(0, 0, 0, 0)}. |
| \end{memberdesc} |
| |
| \begin{memberdesc}{max} |
| The latest representable \class{time}, \code{time(23, 59, 59, 999999)}. |
| \end{memberdesc} |
| |
| \begin{memberdesc}{resolution} |
| The smallest possible difference between non-equal \class{time} |
| objects, \code{timedelta(microseconds=1)}, although note that |
| arithmetic on \class{time} objects is not supported. |
| \end{memberdesc} |
| |
| Instance attributes (read-only): |
| |
| \begin{memberdesc}{hour} |
| In \code{range(24)}. |
| \end{memberdesc} |
| |
| \begin{memberdesc}{minute} |
| In \code{range(60)}. |
| \end{memberdesc} |
| |
| \begin{memberdesc}{second} |
| In \code{range(60)}. |
| \end{memberdesc} |
| |
| \begin{memberdesc}{microsecond} |
| In \code{range(1000000)}. |
| \end{memberdesc} |
| |
| \begin{memberdesc}{tzinfo} |
| The object passed as the tzinfo argument to the \class{time} |
| constructor, or \code{None} if none was passed. |
| \end{memberdesc} |
| |
| Supported operations: |
| |
| \begin{itemize} |
| \item |
| comparison of \class{time} to \class{time}, |
| where \var{a} is considered less than \var{b} when \var{a} precedes |
| \var{b} in time. If one comparand is naive and the other is aware, |
| \exception{TypeError} is raised. If both comparands are aware, and |
| have the same \member{tzinfo} member, the common \member{tzinfo} |
| member is ignored and the base times are compared. If both |
| comparands are aware and have different \member{tzinfo} members, |
| the comparands are first adjusted by subtracting their UTC offsets |
| (obtained from \code{self.utcoffset()}). |
| In order to stop mixed-type comparisons from falling back to the |
| default comparison by object address, when a \class{time} object is |
| compared to an object of a different type, \exception{TypeError} is |
| raised unless the comparison is \code{==} or \code{!=}. The latter |
| cases return \constant{False} or \constant{True}, respectively. |
| |
| \item |
| hash, use as dict key |
| |
| \item |
| efficient pickling |
| |
| \item |
| in Boolean contexts, a \class{time} object is considered to be |
| true if and only if, after converting it to minutes and |
| subtracting \method{utcoffset()} (or \code{0} if that's |
| \code{None}), the result is non-zero. |
| \end{itemize} |
| |
| Instance methods: |
| |
| \begin{methoddesc}{replace}(hour=, minute=, second=, microsecond=, tzinfo=) |
| Return a \class{time} with the same value, except for those members given |
| new values by whichever keyword arguments are specified. Note that |
| \code{tzinfo=None} can be specified to create a naive \class{time} from |
| an aware \class{time}, without conversion of the time members. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{isoformat}{} |
| Return a string representing the time in ISO 8601 format, |
| HH:MM:SS.mmmmmm |
| or, if self.microsecond is 0, |
| HH:MM:SS |
| If \method{utcoffset()} does not return \code{None}, a 6-character |
| string is appended, giving the UTC offset in (signed) hours and |
| minutes: |
| HH:MM:SS.mmmmmm+HH:MM |
| or, if self.microsecond is 0, |
| HH:MM:SS+HH:MM |
| \end{methoddesc} |
| |
| \begin{methoddesc}{__str__}{} |
| For a time \var{t}, \code{str(\var{t})} is equivalent to |
| \code{\var{t}.isoformat()}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{strftime}{format} |
| Return a string representing the time, controlled by an explicit |
| format string. See the section on \method{strftime()} behavior. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{utcoffset}{} |
| If \member{tzinfo} is \code{None}, returns \code{None}, else |
| returns \code{\var{self}.tzinfo.utcoffset(None)}, and |
| raises an exception if the latter doesn't return \code{None} or |
| a \class{timedelta} object representing a whole number of minutes |
| with magnitude less than one day. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{dst}{} |
| If \member{tzinfo} is \code{None}, returns \code{None}, else |
| returns \code{\var{self}.tzinfo.dst(None)}, and |
| raises an exception if the latter doesn't return \code{None}, or |
| a \class{timedelta} object representing a whole number of minutes |
| with magnitude less than one day. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{tzname}{} |
| If \member{tzinfo} is \code{None}, returns \code{None}, else |
| returns \code{\var{self}.tzinfo.tzname(None)}, or |
| raises an exception if the latter doesn't return \code{None} or |
| a string object. |
| \end{methoddesc} |
| |
| |
| \subsection{\class{tzinfo} Objects \label{datetime-tzinfo}} |
| |
| \class{tzinfo} is an abstract base clase, meaning that this class |
| should not be instantiated directly. You need to derive a concrete |
| subclass, and (at least) supply implementations of the standard |
| \class{tzinfo} methods needed by the \class{datetime} methods you |
| use. The \module{datetime} module does not supply any concrete |
| subclasses of \class{tzinfo}. |
| |
| An instance of (a concrete subclass of) \class{tzinfo} can be passed |
| to the constructors for \class{datetime} and \class{time} objects. |
| The latter objects view their members as being in local time, and the |
| \class{tzinfo} object supports methods revealing offset of local time |
| from UTC, the name of the time zone, and DST offset, all relative to a |
| date or time object passed to them. |
| |
| Special requirement for pickling: A \class{tzinfo} subclass must have an |
| \method{__init__} method that can be called with no arguments, else it |
| can be pickled but possibly not unpickled again. This is a technical |
| requirement that may be relaxed in the future. |
| |
| A concrete subclass of \class{tzinfo} may need to implement the |
| following methods. Exactly which methods are needed depends on the |
| uses made of aware \module{datetime} objects. If in doubt, simply |
| implement all of them. |
| |
| \begin{methoddesc}{utcoffset}{self, dt} |
| Return offset of local time from UTC, in minutes east of UTC. If |
| local time is west of UTC, this should be negative. Note that this |
| is intended to be the total offset from UTC; for example, if a |
| \class{tzinfo} object represents both time zone and DST adjustments, |
| \method{utcoffset()} should return their sum. If the UTC offset |
| isn't known, return \code{None}. Else the value returned must be |
| a \class{timedelta} object specifying a whole number of minutes in the |
| range -1439 to 1439 inclusive (1440 = 24*60; the magnitude of the offset |
| must be less than one day). Most implementations of |
| \method{utcoffset()} will probably look like one of these two: |
| |
| \begin{verbatim} |
| return CONSTANT # fixed-offset class |
| return CONSTANT + self.dst(dt) # daylight-aware class |
| \end{verbatim} |
| |
| If \method{utcoffset()} does not return \code{None}, |
| \method{dst()} should not return \code{None} either. |
| |
| The default implementation of \method{utcoffset()} raises |
| \exception{NotImplementedError}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{dst}{self, dt} |
| Return the daylight saving time (DST) adjustment, in minutes east of |
| UTC, or \code{None} if DST information isn't known. Return |
| \code{timedelta(0)} if DST is not in effect. |
| If DST is in effect, return the offset as a |
| \class{timedelta} object (see \method{utcoffset()} for details). |
| Note that DST offset, if applicable, has |
| already been added to the UTC offset returned by |
| \method{utcoffset()}, so there's no need to consult \method{dst()} |
| unless you're interested in obtaining DST info separately. For |
| example, \method{datetime.timetuple()} calls its \member{tzinfo} |
| member's \method{dst()} method to determine how the |
| \member{tm_isdst} flag should be set, and |
| \method{tzinfo.fromutc()} calls \method{dst()} to account for |
| DST changes when crossing time zones. |
| |
| An instance \var{tz} of a \class{tzinfo} subclass that models both |
| standard and daylight times must be consistent in this sense: |
| |
| \code{\var{tz}.utcoffset(\var{dt}) - \var{tz}.dst(\var{dt})} |
| |
| must return the same result for every \class{datetime} \var{dt} |
| with \code{\var{dt}.tzinfo==\var{tz}} For sane \class{tzinfo} |
| subclasses, this expression yields the time zone's "standard offset", |
| which should not depend on the date or the time, but only on geographic |
| location. The implementation of \method{datetime.astimezone()} relies |
| on this, but cannot detect violations; it's the programmer's |
| responsibility to ensure it. If a \class{tzinfo} subclass cannot |
| guarantee this, it may be able to override the default implementation |
| of \method{tzinfo.fromutc()} to work correctly with \method{astimezone()} |
| regardless. |
| |
| Most implementations of \method{dst()} will probably look like one |
| of these two: |
| |
| \begin{verbatim} |
| return timedelta(0) # a fixed-offset class: doesn't account for DST |
| |
| or |
| |
| # 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. Then |
| |
| if dston <= dt.replace(tzinfo=None) < dstoff: |
| return timedelta(hours=1) |
| else: |
| return timedelta(0) |
| \end{verbatim} |
| |
| The default implementation of \method{dst()} raises |
| \exception{NotImplementedError}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{tzname}{self, dt} |
| Return the time zone name corresponding to the \class{datetime} |
| object \var{dt}, as a string. |
| Nothing about string names is defined by the |
| \module{datetime} 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 all valid replies. Return |
| \code{None} if a string name isn't known. Note that this is a method |
| rather than a fixed string primarily because some \class{tzinfo} |
| subclasses will wish to return different names depending on the specific |
| value of \var{dt} passed, especially if the \class{tzinfo} class is |
| accounting for daylight time. |
| |
| The default implementation of \method{tzname()} raises |
| \exception{NotImplementedError}. |
| \end{methoddesc} |
| |
| These methods are called by a \class{datetime} or \class{time} object, |
| in response to their methods of the same names. A \class{datetime} |
| object passes itself as the argument, and a \class{time} object passes |
| \code{None} as the argument. A \class{tzinfo} subclass's methods should |
| therefore be prepared to accept a \var{dt} argument of \code{None}, or of |
| class \class{datetime}. |
| |
| When \code{None} is passed, it's up to the class designer to decide the |
| best response. For example, returning \code{None} is appropriate if the |
| class wishes to say that time objects don't participate in the |
| \class{tzinfo} protocols. It may be more useful for \code{utcoffset(None)} |
| to return the standard UTC offset, as there is no other convention for |
| discovering the standard offset. |
| |
| When a \class{datetime} object is passed in response to a |
| \class{datetime} method, \code{dt.tzinfo} is the same object as |
| \var{self}. \class{tzinfo} methods can rely on this, unless |
| user code calls \class{tzinfo} methods directly. The intent is that |
| the \class{tzinfo} methods interpret \var{dt} as being in local time, |
| and not need worry about objects in other timezones. |
| |
| There is one more \class{tzinfo} method that a subclass may wish to |
| override: |
| |
| \begin{methoddesc}{fromutc}{self, dt} |
| This is called from the default \class{datetime.astimezone()} |
| implementation. When called from that, \code{\var{dt}.tzinfo} is |
| \var{self}, and \var{dt}'s date and time members are to be viewed as |
| expressing a UTC time. The purpose of \method{fromutc()} is to |
| adjust the date and time members, returning an equivalent datetime in |
| \var{self}'s local time. |
| |
| Most \class{tzinfo} subclasses should be able to inherit the default |
| \method{fromutc()} implementation without problems. It's strong enough |
| to handle fixed-offset time zones, and time zones accounting for both |
| standard and daylight time, and the latter even if the DST transition |
| times differ in different years. An example of a time zone the default |
| \method{fromutc()} implementation may not handle correctly in all cases |
| is one where the standard offset (from UTC) depends on the specific date |
| and time passed, which can happen for political reasons. |
| The default implementations of \method{astimezone()} and |
| \method{fromutc()} may not produce the result you want if the result is |
| one of the hours straddling the moment the standard offset changes. |
| |
| Skipping code for error cases, the default \method{fromutc()} |
| implementation acts like: |
| |
| \begin{verbatim} |
| def fromutc(self, dt): |
| # raise ValueError error if dt.tzinfo is not self |
| dtoff = dt.utcoffset() |
| dtdst = dt.dst() |
| # raise ValueError if dtoff is None or dtdst is None |
| delta = dtoff - dtdst # this is self's standard offset |
| if delta: |
| dt += delta # convert to standard local time |
| dtdst = dt.dst() |
| # raise ValueError if dtdst is None |
| if dtdst: |
| return dt + dtdst |
| else: |
| return dt |
| \end{verbatim} |
| \end{methoddesc} |
| |
| Example \class{tzinfo} classes: |
| |
| \verbatiminput{tzinfo-examples.py} |
| |
| Note that there are unavoidable subtleties twice per year in a |
| \class{tzinfo} |
| subclass accounting for both standard and daylight time, at the DST |
| transition points. For concreteness, consider US Eastern (UTC -0500), |
| where EDT begins the minute after 1:59 (EST) on the first Sunday in |
| April, and ends the minute after 1:59 (EDT) on the last Sunday in October: |
| |
| \begin{verbatim} |
| UTC 3:MM 4:MM 5:MM 6:MM 7:MM 8:MM |
| EST 22:MM 23:MM 0:MM 1:MM 2:MM 3:MM |
| EDT 23:MM 0:MM 1:MM 2:MM 3:MM 4:MM |
| |
| start 22:MM 23:MM 0:MM 1:MM 3:MM 4:MM |
| |
| end 23:MM 0:MM 1:MM 1:MM 2:MM 3:MM |
| \end{verbatim} |
| |
| When DST starts (the "start" line), the local wall clock leaps from 1:59 |
| to 3:00. A wall time of the form 2:MM doesn't really make sense on that |
| day, so \code{astimezone(Eastern)} won't deliver a result with |
| \code{hour==2} on the |
| day DST begins. In order for \method{astimezone()} to make this |
| guarantee, the \method{rzinfo.dst()} method must consider times |
| in the "missing hour" (2:MM for Eastern) to be in daylight time. |
| |
| When DST ends (the "end" line), there's a potentially worse problem: |
| there's an hour that can't be spelled unambiguously in local wall time: |
| the last hour of daylight time. In Eastern, that's times of |
| the form 5:MM UTC on the day daylight time ends. The local wall clock |
| leaps from 1:59 (daylight time) back to 1:00 (standard time) again. |
| Local times of the form 1:MM are ambiguous. \method{astimezone()} mimics |
| the local clock's behavior by mapping two adjacent UTC hours into the |
| same local hour then. In the Eastern example, UTC times of the form |
| 5:MM and 6:MM both map to 1:MM when converted to Eastern. In order for |
| \method{astimezone()} to make this guarantee, the \method{tzinfo.dst()} |
| method must consider times in the "repeated hour" to be in |
| standard time. This is easily arranged, as in the example, by expressing |
| DST switch times in the time zone's standard local time. |
| |
| Applications that can't bear such ambiguities should avoid using hybrid |
| \class{tzinfo} subclasses; there are no ambiguities when using UTC, or |
| any other fixed-offset \class{tzinfo} subclass (such as a class |
| representing only EST (fixed offset -5 hours), or only EDT (fixed offset |
| -4 hours)). |
| |
| |
| \subsection{\method{strftime()} Behavior} |
| |
| \class{date}, \class{datetime}, and \class{time} |
| objects all support a \code{strftime(\var{format})} |
| method, to create a string representing the time under the control of |
| an explicit format string. Broadly speaking, |
| \code{d.strftime(fmt)} |
| acts like the \refmodule{time} module's |
| \code{time.strftime(fmt, d.timetuple())} |
| although not all objects support a \method{timetuple()} method. |
| |
| For \class{time} objects, the format codes for |
| year, month, and day should not be used, as time objects have no such |
| values. If they're used anyway, \code{1900} is substituted for the |
| year, and \code{0} for the month and day. |
| |
| For \class{date} objects, the format codes for hours, minutes, and |
| seconds should not be used, as \class{date} objects have no such |
| values. If they're used anyway, \code{0} is substituted for them. |
| |
| For a naive object, the \code{\%z} and \code{\%Z} format codes are |
| replaced by empty strings. |
| |
| For an aware object: |
| |
| \begin{itemize} |
| \item[\code{\%z}] |
| \method{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 UTC offset hours, and MM is a 2-digit string giving the |
| number of UTC offset minutes. For example, if |
| \method{utcoffset()} returns \code{timedelta(hours=-3, minutes=-30)}, |
| \code{\%z} is replaced with the string \code{'-0330'}. |
| |
| \item[\code{\%Z}] |
| If \method{tzname()} returns \code{None}, \code{\%Z} is replaced |
| by an empty string. Otherwise \code{\%Z} is replaced by the returned |
| value, which must be a string. |
| \end{itemize} |
| |
| The full set of format codes supported varies across platforms, |
| because Python calls the platform C library's \function{strftime()} |
| function, and platform variations are common. The documentation for |
| Python's \refmodule{time} module lists the format codes that the C |
| standard (1989 version) requires, and those work on all platforms |
| with a standard C implementation. Note that the 1999 version of the |
| C standard added additional format codes. |
| |
| The exact range of years for which \method{strftime()} works also |
| varies across platforms. Regardless of platform, years before 1900 |
| cannot be used. |
| |
| |
| \begin{comment} |
| |
| \subsection{C API} |
| |
| Struct typedefs: |
| |
| PyDateTime_Date |
| PyDateTime_DateTime |
| PyDateTime_Time |
| PyDateTime_Delta |
| PyDateTime_TZInfo |
| |
| Type-check macros: |
| |
| PyDate_Check(op) |
| PyDate_CheckExact(op) |
| |
| PyDateTime_Check(op) |
| PyDateTime_CheckExact(op) |
| |
| PyTime_Check(op) |
| PyTime_CheckExact(op) |
| |
| PyDelta_Check(op) |
| PyDelta_CheckExact(op) |
| |
| PyTZInfo_Check(op) |
| PyTZInfo_CheckExact(op) |
| |
| Accessor macros: |
| |
| All objects are immutable, so accessors are read-only. All macros |
| return ints: |
| |
| For \class{date} and \class{datetime} instances: |
| PyDateTime_GET_YEAR(o) |
| PyDateTime_GET_MONTH(o) |
| PyDateTime_GET_DAY(o) |
| |
| For \class{datetime} instances: |
| PyDateTime_DATE_GET_HOUR(o) |
| PyDateTime_DATE_GET_MINUTE(o) |
| PyDateTime_DATE_GET_SECOND(o) |
| PyDateTime_DATE_GET_MICROSECOND(o) |
| |
| For \class{time} instances: |
| PyDateTime_TIME_GET_HOUR(o) |
| PyDateTime_TIME_GET_MINUTE(o) |
| PyDateTime_TIME_GET_SECOND(o) |
| PyDateTime_TIME_GET_MICROSECOND(o) |
| |
| \end{comment} |