% 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 datesand times in both simple and complex ways. While date and timearithmetic is supported, the focus of the implementation is onefficient 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 timezone, daylight saving time, or other kind of algorithmic or politicaltime adjustment. Whether a naive \class{datetime} object representsCoordinated Universal Time (UTC), local time, or time in some othertimezone is purely up to the program, just like it's up to the programwhether a particular number represents metres, miles, or mass. Naive\class{datetime} objects are easy to understand and to work with, atthe 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 ofthe abstract \class{tzinfo} class. These \class{tzinfo} objectscapture information about the offset from UTC time, the time zonename, and whether Daylight Saving Time is in effect. Note that noconcrete \class{tzinfo} classes are supplied by the \module{datetime}module. Supporting timezones at whatever level of detail is requiredis up to the application. The rules for time adjustment across theworld are more political than rational, and there is no standardsuitable 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 benaive 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\class{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 differencebetween two dates or times. \begin{classdesc}{timedelta}{\optional{days\optional{, seconds\optional{, microseconds\optional{, milliseconds\optional{, minutes\optional{, hours\optional{, weeks}}}}}}}} All arguments are optional and default to \code{0}. 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 asa \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}\noindentNotes: \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} objectssupport 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 consideredto be the smaller timedelta.In order to stop mixed-type comparisons from falling back to thedefault comparison by object address, when a \class{timedelta} object iscompared to an object of a different type, \exception{TypeError} israised unless the comparison is \code{==} or \code{!=}. The lattercases 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 idealizedcalendar, the current Gregorian calendar indefinitely extended in bothdirections. January 1 of year 1 is called day number 1, January 2 of year1 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 allcomputations. See the book for algorithms for converting betweenproleptic 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: \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 defaultscheme of comparing object addresses, date comparisonnormally raises \exception{TypeError} if the other comparandisn'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 ofdate objects a chance at implementing mixed-type comparison.If not, when a \class{date} object iscompared to an object of a different type, \exception{TypeError} israised unless the comparison is \code{==} or \code{!=}. The lattercases 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(2002, 12, 26)}.\end{methoddesc} \begin{methoddesc}{timetuple}{} Return a \class{time.struct_time} such as 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{time.struct_time((\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.Lines 1–500 of 1441. Load more
% 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 metres, 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 \class{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}{\optional{days\optional{, seconds\optional{, microseconds\optional{, milliseconds\optional{, minutes\optional{, hours\optional{, weeks}}}}}}}} All arguments are optional and default to \code{0}. 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: \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(2002, 12, 26)}. \end{methoddesc} \begin{methoddesc}{timetuple}{} Return a \class{time.struct_time} such as 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{time.struct_time((\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.