Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 1 | % XXX what order should the types be discussed in? |
Tim Peters | bad8ff0 | 2002-12-30 20:52:32 +0000 | [diff] [blame] | 2 | |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 3 | \section{\module{datetime} --- |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 4 | Basic date and time types} |
| 5 | |
| 6 | \declaremodule{builtin}{datetime} |
| 7 | \modulesynopsis{Basic date and time types.} |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 8 | \moduleauthor{Tim Peters}{tim@zope.com} |
| 9 | \sectionauthor{Tim Peters}{tim@zope.com} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 10 | \sectionauthor{A.M. Kuchling}{amk@amk.ca} |
Raymond Hettinger | 6005a34 | 2002-12-30 20:01:24 +0000 | [diff] [blame] | 11 | |
| 12 | \versionadded{2.3} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 13 | |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 14 | |
| 15 | The \module{datetime} module supplies classes for manipulating dates |
| 16 | and times in both simple and complex ways. While date and time |
| 17 | arithmetic is supported, the focus of the implementation is on |
Andrew M. Kuchling | 9b44571 | 2003-01-09 13:46:30 +0000 | [diff] [blame] | 18 | efficient member extraction for output formatting and manipulation. |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 19 | |
Fred Drake | a37e5cc | 2002-12-30 21:26:42 +0000 | [diff] [blame] | 20 | There are two kinds of date and time objects: ``naive'' and ``aware''. |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 21 | This distinction refers to whether the object has any notion of time |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 22 | zone, daylight saving time, or other kind of algorithmic or political |
| 23 | time adjustment. Whether a naive \class{datetime} object represents |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 24 | Coordinated Universal Time (UTC), local time, or time in some other |
| 25 | timezone is purely up to the program, just like it's up to the program |
Fred Drake | b184ae8 | 2005-01-19 03:39:17 +0000 | [diff] [blame] | 26 | whether a particular number represents metres, miles, or mass. Naive |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 27 | \class{datetime} objects are easy to understand and to work with, at |
| 28 | the cost of ignoring some aspects of reality. |
| 29 | |
Andrew M. Kuchling | 9b44571 | 2003-01-09 13:46:30 +0000 | [diff] [blame] | 30 | For applications requiring more, \class{datetime} and \class{time} |
| 31 | objects have an optional time zone information member, |
Tim Peters | 327098a | 2003-01-20 22:54:38 +0000 | [diff] [blame] | 32 | \member{tzinfo}, that can contain an instance of a subclass of |
Andrew M. Kuchling | 9b44571 | 2003-01-09 13:46:30 +0000 | [diff] [blame] | 33 | the abstract \class{tzinfo} class. These \class{tzinfo} objects |
| 34 | capture information about the offset from UTC time, the time zone |
| 35 | name, and whether Daylight Saving Time is in effect. Note that no |
| 36 | concrete \class{tzinfo} classes are supplied by the \module{datetime} |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 37 | module. Supporting timezones at whatever level of detail is required |
| 38 | is up to the application. The rules for time adjustment across the |
| 39 | world are more political than rational, and there is no standard |
Andrew M. Kuchling | 9b44571 | 2003-01-09 13:46:30 +0000 | [diff] [blame] | 40 | suitable for every application. |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 41 | |
| 42 | The \module{datetime} module exports the following constants: |
| 43 | |
| 44 | \begin{datadesc}{MINYEAR} |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 45 | The smallest year number allowed in a \class{date} or |
| 46 | \class{datetime} object. \constant{MINYEAR} |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 47 | is \code{1}. |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 48 | \end{datadesc} |
| 49 | |
| 50 | \begin{datadesc}{MAXYEAR} |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 51 | The largest year number allowed in a \class{date} or \class{datetime} |
| 52 | object. \constant{MAXYEAR} is \code{9999}. |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 53 | \end{datadesc} |
| 54 | |
Raymond Hettinger | 6005a34 | 2002-12-30 20:01:24 +0000 | [diff] [blame] | 55 | \begin{seealso} |
Raymond Hettinger | 6222958 | 2002-12-31 16:37:03 +0000 | [diff] [blame] | 56 | \seemodule{calendar}{General calendar related functions.} |
Raymond Hettinger | 6005a34 | 2002-12-30 20:01:24 +0000 | [diff] [blame] | 57 | \seemodule{time}{Time access and conversions.} |
| 58 | \end{seealso} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 59 | |
| 60 | \subsection{Available Types} |
| 61 | |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 62 | \begin{classdesc*}{date} |
Fred Drake | a37e5cc | 2002-12-30 21:26:42 +0000 | [diff] [blame] | 63 | An idealized naive date, assuming the current Gregorian calendar |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 64 | always was, and always will be, in effect. |
| 65 | Attributes: \member{year}, \member{month}, and \member{day}. |
| 66 | \end{classdesc*} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 67 | |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 68 | \begin{classdesc*}{time} |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 69 | An idealized time, independent of any particular day, assuming |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 70 | that every day has exactly 24*60*60 seconds (there is no notion |
| 71 | of "leap seconds" here). |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 72 | Attributes: \member{hour}, \member{minute}, \member{second}, |
| 73 | \member{microsecond}, and \member{tzinfo}. |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 74 | \end{classdesc*} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 75 | |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 76 | \begin{classdesc*}{datetime} |
Andrew M. Kuchling | 9b44571 | 2003-01-09 13:46:30 +0000 | [diff] [blame] | 77 | A combination of a date and a time. |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 78 | Attributes: \member{year}, \member{month}, \member{day}, |
| 79 | \member{hour}, \member{minute}, \member{second}, |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 80 | \member{microsecond}, and \member{tzinfo}. |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 81 | \end{classdesc*} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 82 | |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 83 | \begin{classdesc*}{timedelta} |
Andrew M. Kuchling | 9b44571 | 2003-01-09 13:46:30 +0000 | [diff] [blame] | 84 | A duration expressing the difference between two \class{date}, |
| 85 | \class{time}, or \class{datetime} instances to microsecond |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 86 | resolution. |
| 87 | \end{classdesc*} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 88 | |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 89 | \begin{classdesc*}{tzinfo} |
| 90 | An abstract base class for time zone information objects. These |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 91 | are used by the \class{datetime} and \class{time} classes to |
Andrew M. Kuchling | 9b44571 | 2003-01-09 13:46:30 +0000 | [diff] [blame] | 92 | provide a customizable notion of time adjustment (for example, to |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 93 | account for time zone and/or daylight saving time). |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 94 | \end{classdesc*} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 95 | |
| 96 | Objects of these types are immutable. |
| 97 | |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 98 | Objects of the \class{date} type are always naive. |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 99 | |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 100 | An object \var{d} of type \class{time} or \class{datetime} may be |
Fred Drake | a37e5cc | 2002-12-30 21:26:42 +0000 | [diff] [blame] | 101 | naive or aware. \var{d} is aware if \code{\var{d}.tzinfo} is not |
Andrew M. Kuchling | 9b44571 | 2003-01-09 13:46:30 +0000 | [diff] [blame] | 102 | \code{None} and \code{\var{d}.tzinfo.utcoffset(\var{d})} does not return |
Fred Drake | a37e5cc | 2002-12-30 21:26:42 +0000 | [diff] [blame] | 103 | \code{None}. If \code{\var{d}.tzinfo} is \code{None}, or if |
| 104 | \code{\var{d}.tzinfo} is not \code{None} but |
| 105 | \code{\var{d}.tzinfo.utcoffset(\var{d})} returns \code{None}, \var{d} |
| 106 | is naive. |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 107 | |
Fred Drake | a37e5cc | 2002-12-30 21:26:42 +0000 | [diff] [blame] | 108 | The distinction between naive and aware doesn't apply to |
Fred Drake | b0e8f5d | 2003-12-30 20:36:20 +0000 | [diff] [blame] | 109 | \class{timedelta} objects. |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 110 | |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 111 | Subclass relationships: |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 112 | |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 113 | \begin{verbatim} |
| 114 | object |
| 115 | timedelta |
| 116 | tzinfo |
| 117 | time |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 118 | date |
| 119 | datetime |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 120 | \end{verbatim} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 121 | |
Raymond Hettinger | 6005a34 | 2002-12-30 20:01:24 +0000 | [diff] [blame] | 122 | \subsection{\class{timedelta} Objects \label{datetime-timedelta}} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 123 | |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 124 | A \class{timedelta} object represents a duration, the difference |
| 125 | between two dates or times. |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 126 | |
Fred Drake | b0e8f5d | 2003-12-30 20:36:20 +0000 | [diff] [blame] | 127 | \begin{classdesc}{timedelta}{\optional{days\optional{, seconds\optional{, |
| 128 | microseconds\optional{, milliseconds\optional{, |
| 129 | minutes\optional{, hours\optional{, weeks}}}}}}}} |
| 130 | All arguments are optional and default to \code{0}. Arguments may |
| 131 | be ints, longs, or floats, and may be positive or negative. |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 132 | |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 133 | Only \var{days}, \var{seconds} and \var{microseconds} are stored |
| 134 | internally. Arguments are converted to those units: |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 135 | |
Andrew M. Kuchling | 9b44571 | 2003-01-09 13:46:30 +0000 | [diff] [blame] | 136 | \begin{itemize} |
| 137 | \item A millisecond is converted to 1000 microseconds. |
| 138 | \item A minute is converted to 60 seconds. |
| 139 | \item An hour is converted to 3600 seconds. |
| 140 | \item A week is converted to 7 days. |
| 141 | \end{itemize} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 142 | |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 143 | and days, seconds and microseconds are then normalized so that the |
| 144 | representation is unique, with |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 145 | |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 146 | \begin{itemize} |
| 147 | \item \code{0 <= \var{microseconds} < 1000000} |
| 148 | \item \code{0 <= \var{seconds} < 3600*24} (the number of seconds in one day) |
| 149 | \item \code{-999999999 <= \var{days} <= 999999999} |
| 150 | \end{itemize} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 151 | |
Andrew M. Kuchling | 9b44571 | 2003-01-09 13:46:30 +0000 | [diff] [blame] | 152 | If any argument is a float and there are fractional microseconds, |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 153 | the fractional microseconds left over from all arguments are combined |
| 154 | and their sum is rounded to the nearest microsecond. If no |
| 155 | argument is a float, the conversion and normalization processes |
| 156 | are exact (no information is lost). |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 157 | |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 158 | If the normalized value of days lies outside the indicated range, |
| 159 | \exception{OverflowError} is raised. |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 160 | |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 161 | Note that normalization of negative values may be surprising at first. |
| 162 | For example, |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 163 | |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 164 | \begin{verbatim} |
| 165 | >>> d = timedelta(microseconds=-1) |
| 166 | >>> (d.days, d.seconds, d.microseconds) |
| 167 | (-1, 86399, 999999) |
| 168 | \end{verbatim} |
Fred Drake | 0f8e543 | 2002-12-31 18:31:48 +0000 | [diff] [blame] | 169 | \end{classdesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 170 | |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 171 | Class attributes are: |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 172 | |
Fred Drake | 0f8e543 | 2002-12-31 18:31:48 +0000 | [diff] [blame] | 173 | \begin{memberdesc}{min} |
| 174 | The most negative \class{timedelta} object, |
| 175 | \code{timedelta(-999999999)}. |
| 176 | \end{memberdesc} |
| 177 | |
| 178 | \begin{memberdesc}{max} |
| 179 | The most positive \class{timedelta} object, |
| 180 | \code{timedelta(days=999999999, hours=23, minutes=59, seconds=59, |
| 181 | microseconds=999999)}. |
| 182 | \end{memberdesc} |
| 183 | |
| 184 | \begin{memberdesc}{resolution} |
| 185 | The smallest possible difference between non-equal |
| 186 | \class{timedelta} objects, \code{timedelta(microseconds=1)}. |
| 187 | \end{memberdesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 188 | |
Fred Drake | a37e5cc | 2002-12-30 21:26:42 +0000 | [diff] [blame] | 189 | Note that, because of normalization, \code{timedelta.max} \textgreater |
| 190 | \code{-timedelta.min}. \code{-timedelta.max} is not representable as |
| 191 | a \class{timedelta} object. |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 192 | |
| 193 | Instance attributes (read-only): |
| 194 | |
Raymond Hettinger | 6005a34 | 2002-12-30 20:01:24 +0000 | [diff] [blame] | 195 | \begin{tableii}{c|l}{code}{Attribute}{Value} |
| 196 | \lineii{days}{Between -999999999 and 999999999 inclusive} |
| 197 | \lineii{seconds}{Between 0 and 86399 inclusive} |
| 198 | \lineii{microseconds}{Between 0 and 999999 inclusive} |
| 199 | \end{tableii} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 200 | |
| 201 | Supported operations: |
| 202 | |
Andrew M. Kuchling | 9b44571 | 2003-01-09 13:46:30 +0000 | [diff] [blame] | 203 | % XXX this table is too wide! |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 204 | \begin{tableii}{c|l}{code}{Operation}{Result} |
| 205 | \lineii{\var{t1} = \var{t2} + \var{t3}} |
Tim Peters | 9532298 | 2002-12-31 16:01:47 +0000 | [diff] [blame] | 206 | {Sum of \var{t2} and \var{t3}. |
Fred Drake | 9bdeee4 | 2002-12-30 20:35:32 +0000 | [diff] [blame] | 207 | Afterwards \var{t1}-\var{t2} == \var{t3} and \var{t1}-\var{t3} |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 208 | == \var{t2} are true. |
| 209 | (1)} |
| 210 | \lineii{\var{t1} = \var{t2} - \var{t3}} |
| 211 | {Difference of \var{t2} and \var{t3}. |
Fred Drake | b0e8f5d | 2003-12-30 20:36:20 +0000 | [diff] [blame] | 212 | Afterwards \var{t1} == \var{t2} - \var{t3} and |
| 213 | \var{t2} == \var{t1} + \var{t3} are true. |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 214 | (1)} |
| 215 | \lineii{\var{t1} = \var{t2} * \var{i} or \var{t1} = \var{i} * \var{t2}} |
Fred Drake | 9bdeee4 | 2002-12-30 20:35:32 +0000 | [diff] [blame] | 216 | {Delta multiplied by an integer or long. |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 217 | Afterwards \var{t1} // i == \var{t2} is true, |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 218 | provided \code{i != 0}.} |
| 219 | \lineii{}{In general, \var{t1} * i == \var{t1} * (i-1) + \var{t1} is true. |
| 220 | (1)} |
| 221 | \lineii{\var{t1} = \var{t2} // \var{i}} |
| 222 | {The floor is computed and the remainder (if any) is thrown away. |
| 223 | (3)} |
| 224 | \lineii{+\var{t1}} |
| 225 | {Returns a \class{timedelta} object with the same value. |
| 226 | (2)} |
| 227 | \lineii{-\var{t1}} |
Raymond Hettinger | cbd6cd2 | 2002-12-31 16:30:49 +0000 | [diff] [blame] | 228 | {equivalent to \class{timedelta}(-\var{t1.days}, -\var{t1.seconds}, |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 229 | -\var{t1.microseconds}), and to \var{t1}* -1. |
| 230 | (1)(4)} |
| 231 | \lineii{abs(\var{t})} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 232 | {equivalent to +\var{t} when \code{t.days >= 0}, and to |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 233 | -\var{t} when \code{t.days < 0}. |
| 234 | (2)} |
| 235 | \end{tableii} |
Raymond Hettinger | 6005a34 | 2002-12-30 20:01:24 +0000 | [diff] [blame] | 236 | \noindent |
| 237 | Notes: |
| 238 | |
| 239 | \begin{description} |
| 240 | \item[(1)] |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 241 | This is exact, but may overflow. |
Raymond Hettinger | 6005a34 | 2002-12-30 20:01:24 +0000 | [diff] [blame] | 242 | |
| 243 | \item[(2)] |
Tim Peters | 397301e | 2003-01-02 21:28:08 +0000 | [diff] [blame] | 244 | This is exact, and cannot overflow. |
Raymond Hettinger | c5f5f87 | 2002-12-31 14:26:54 +0000 | [diff] [blame] | 245 | |
| 246 | \item[(3)] |
Tim Peters | 397301e | 2003-01-02 21:28:08 +0000 | [diff] [blame] | 247 | Division by 0 raises \exception{ZeroDivisionError}. |
| 248 | |
| 249 | \item[(4)] |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 250 | -\var{timedelta.max} is not representable as a \class{timedelta} object. |
Raymond Hettinger | 6005a34 | 2002-12-30 20:01:24 +0000 | [diff] [blame] | 251 | \end{description} |
| 252 | |
Raymond Hettinger | c5f5f87 | 2002-12-31 14:26:54 +0000 | [diff] [blame] | 253 | In addition to the operations listed above \class{timedelta} objects |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 254 | support certain additions and subtractions with \class{date} and |
| 255 | \class{datetime} objects (see below). |
Raymond Hettinger | 6005a34 | 2002-12-30 20:01:24 +0000 | [diff] [blame] | 256 | |
Raymond Hettinger | c5f5f87 | 2002-12-31 14:26:54 +0000 | [diff] [blame] | 257 | Comparisons of \class{timedelta} objects are supported with the |
| 258 | \class{timedelta} object representing the smaller duration considered |
| 259 | to be the smaller timedelta. |
Tim Peters | 07534a6 | 2003-02-07 22:50:28 +0000 | [diff] [blame] | 260 | In order to stop mixed-type comparisons from falling back to the |
| 261 | default comparison by object address, when a \class{timedelta} object is |
| 262 | compared to an object of a different type, \exception{TypeError} is |
| 263 | raised unless the comparison is \code{==} or \code{!=}. The latter |
| 264 | cases return \constant{False} or \constant{True}, respectively. |
Raymond Hettinger | 6005a34 | 2002-12-30 20:01:24 +0000 | [diff] [blame] | 265 | |
Andrew M. Kuchling | 9b44571 | 2003-01-09 13:46:30 +0000 | [diff] [blame] | 266 | \class{timedelta} objects are hashable (usable as dictionary keys), |
Raymond Hettinger | c5f5f87 | 2002-12-31 14:26:54 +0000 | [diff] [blame] | 267 | support efficient pickling, and in Boolean contexts, a \class{timedelta} |
| 268 | object is considered to be true if and only if it isn't equal to |
| 269 | \code{timedelta(0)}. |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 270 | |
| 271 | |
Raymond Hettinger | 6005a34 | 2002-12-30 20:01:24 +0000 | [diff] [blame] | 272 | \subsection{\class{date} Objects \label{datetime-date}} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 273 | |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 274 | A \class{date} object represents a date (year, month and day) in an idealized |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 275 | calendar, the current Gregorian calendar indefinitely extended in both |
| 276 | directions. January 1 of year 1 is called day number 1, January 2 of year |
| 277 | 1 is called day number 2, and so on. This matches the definition of the |
| 278 | "proleptic Gregorian" calendar in Dershowitz and Reingold's book |
Fred Drake | a37e5cc | 2002-12-30 21:26:42 +0000 | [diff] [blame] | 279 | \citetitle{Calendrical Calculations}, where it's the base calendar for all |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 280 | computations. See the book for algorithms for converting between |
| 281 | proleptic Gregorian ordinals and many other calendar systems. |
| 282 | |
Fred Drake | 0f8e543 | 2002-12-31 18:31:48 +0000 | [diff] [blame] | 283 | \begin{classdesc}{date}{year, month, day} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 284 | All arguments are required. Arguments may be ints or longs, in the |
| 285 | following ranges: |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 286 | |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 287 | \begin{itemize} |
| 288 | \item \code{MINYEAR <= \var{year} <= MAXYEAR} |
| 289 | \item \code{1 <= \var{month} <= 12} |
| 290 | \item \code{1 <= \var{day} <= number of days in the given month and year} |
| 291 | \end{itemize} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 292 | |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 293 | If an argument outside those ranges is given, \exception{ValueError} |
| 294 | is raised. |
Fred Drake | 0f8e543 | 2002-12-31 18:31:48 +0000 | [diff] [blame] | 295 | \end{classdesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 296 | |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 297 | Other constructors, all class methods: |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 298 | |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 299 | \begin{methoddesc}{today}{} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 300 | Return the current local date. This is equivalent to |
| 301 | \code{date.fromtimestamp(time.time())}. |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 302 | \end{methoddesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 303 | |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 304 | \begin{methoddesc}{fromtimestamp}{timestamp} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 305 | Return the local date corresponding to the POSIX timestamp, such |
| 306 | as is returned by \function{time.time()}. This may raise |
| 307 | \exception{ValueError}, if the timestamp is out of the range of |
| 308 | values supported by the platform C \cfunction{localtime()} |
| 309 | function. It's common for this to be restricted to years from 1970 |
Tim Peters | 75a6e3b | 2003-01-04 18:17:36 +0000 | [diff] [blame] | 310 | through 2038. Note that on non-POSIX systems that include leap |
| 311 | seconds in their notion of a timestamp, leap seconds are ignored by |
| 312 | \method{fromtimestamp()}. |
Andrew M. Kuchling | 0f0e6b9 | 2003-01-09 12:51:50 +0000 | [diff] [blame] | 313 | \end{methoddesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 314 | |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 315 | \begin{methoddesc}{fromordinal}{ordinal} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 316 | Return the date corresponding to the proleptic Gregorian ordinal, |
| 317 | where January 1 of year 1 has ordinal 1. \exception{ValueError} is |
| 318 | raised unless \code{1 <= \var{ordinal} <= date.max.toordinal()}. |
| 319 | For any date \var{d}, \code{date.fromordinal(\var{d}.toordinal()) == |
| 320 | \var{d}}. |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 321 | \end{methoddesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 322 | |
| 323 | Class attributes: |
| 324 | |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 325 | \begin{memberdesc}{min} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 326 | The earliest representable date, \code{date(MINYEAR, 1, 1)}. |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 327 | \end{memberdesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 328 | |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 329 | \begin{memberdesc}{max} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 330 | The latest representable date, \code{date(MAXYEAR, 12, 31)}. |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 331 | \end{memberdesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 332 | |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 333 | \begin{memberdesc}{resolution} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 334 | The smallest possible difference between non-equal date |
| 335 | objects, \code{timedelta(days=1)}. |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 336 | \end{memberdesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 337 | |
| 338 | Instance attributes (read-only): |
| 339 | |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 340 | \begin{memberdesc}{year} |
Andrew M. Kuchling | 9b44571 | 2003-01-09 13:46:30 +0000 | [diff] [blame] | 341 | Between \constant{MINYEAR} and \constant{MAXYEAR} inclusive. |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 342 | \end{memberdesc} |
| 343 | |
| 344 | \begin{memberdesc}{month} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 345 | Between 1 and 12 inclusive. |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 346 | \end{memberdesc} |
| 347 | |
| 348 | \begin{memberdesc}{day} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 349 | Between 1 and the number of days in the given month of the given |
| 350 | year. |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 351 | \end{memberdesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 352 | |
| 353 | Supported operations: |
| 354 | |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 355 | \begin{tableii}{c|l}{code}{Operation}{Result} |
| 356 | \lineii{\var{date2} = \var{date1} + \var{timedelta}} |
| 357 | {\var{date2} is \code{\var{timedelta}.days} days removed from |
| 358 | \var{date1}. (1)} |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 359 | |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 360 | |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 361 | \lineii{\var{date2} = \var{date1} - \var{timedelta}} |
| 362 | {Computes \var{date2} such that \code{\var{date2} + \var{timedelta} |
| 363 | == \var{date1}}. (2)} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 364 | |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 365 | \lineii{\var{timedelta} = \var{date1} - \var{date2}} |
| 366 | {(3)} |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 367 | |
Fred Drake | b0e8f5d | 2003-12-30 20:36:20 +0000 | [diff] [blame] | 368 | \lineii{\var{date1} < \var{date2}} |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 369 | {\var{date1} is considered less than \var{date2} when \var{date1} |
| 370 | precedes \var{date2} in time. (4)} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 371 | |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 372 | \end{tableii} |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 373 | |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 374 | Notes: |
| 375 | \begin{description} |
| 376 | |
| 377 | \item[(1)] |
| 378 | \var{date2} is moved forward in time if \code{\var{timedelta}.days |
| 379 | > 0}, or backward if \code{\var{timedelta}.days < 0}. Afterward |
| 380 | \code{\var{date2} - \var{date1} == \var{timedelta}.days}. |
| 381 | \code{\var{timedelta}.seconds} and |
| 382 | \code{\var{timedelta}.microseconds} are ignored. |
| 383 | \exception{OverflowError} is raised if \code{\var{date2}.year} |
| 384 | would be smaller than \constant{MINYEAR} or larger than |
| 385 | \constant{MAXYEAR}. |
| 386 | |
| 387 | \item[(2)] |
| 388 | This isn't quite equivalent to date1 + |
| 389 | (-timedelta), because -timedelta in isolation can overflow in cases |
| 390 | where date1 - timedelta does not. \code{\var{timedelta}.seconds} |
| 391 | and \code{\var{timedelta}.microseconds} are ignored. |
| 392 | |
| 393 | \item[(3)] |
| 394 | This is exact, and cannot overflow. timedelta.seconds and |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 395 | timedelta.microseconds are 0, and date2 + timedelta == date1 |
| 396 | after. |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 397 | |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 398 | \item[(4)] |
| 399 | In other words, \code{date1 < date2} |
| 400 | if and only if \code{\var{date1}.toordinal() < |
Tim Peters | fdc58f2 | 2004-11-15 03:50:16 +0000 | [diff] [blame] | 401 | \var{date2}.toordinal()}. |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 402 | In order to stop comparison from falling back to the default |
| 403 | scheme of comparing object addresses, date comparison |
| 404 | normally raises \exception{TypeError} if the other comparand |
| 405 | isn't also a \class{date} object. However, \code{NotImplemented} |
| 406 | is returned instead if the other comparand has a |
| 407 | \method{timetuple} attribute. This hook gives other kinds of |
| 408 | date objects a chance at implementing mixed-type comparison. |
Tim Peters | 07534a6 | 2003-02-07 22:50:28 +0000 | [diff] [blame] | 409 | If not, when a \class{date} object is |
| 410 | compared to an object of a different type, \exception{TypeError} is |
| 411 | raised unless the comparison is \code{==} or \code{!=}. The latter |
| 412 | cases return \constant{False} or \constant{True}, respectively. |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 413 | |
| 414 | \end{description} |
Tim Peters | 8d81a01 | 2003-01-24 22:36:34 +0000 | [diff] [blame] | 415 | |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 416 | |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 417 | Dates can be used as dictionary keys. In Boolean contexts, all |
| 418 | \class{date} objects are considered to be true. |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 419 | |
| 420 | Instance methods: |
| 421 | |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 422 | \begin{methoddesc}{replace}{year, month, day} |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 423 | Return a date with the same value, except for those members given |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 424 | new values by whichever keyword arguments are specified. For |
| 425 | example, if \code{d == date(2002, 12, 31)}, then |
Tim Peters | fdc58f2 | 2004-11-15 03:50:16 +0000 | [diff] [blame] | 426 | \code{d.replace(day=26) == date(2002, 12, 26)}. |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 427 | \end{methoddesc} |
Tim Peters | 12bf339 | 2002-12-24 05:41:27 +0000 | [diff] [blame] | 428 | |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 429 | \begin{methoddesc}{timetuple}{} |
Martin v. Löwis | ef36537 | 2003-09-04 18:29:53 +0000 | [diff] [blame] | 430 | Return a \class{time.struct_time} such as returned by |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 431 | \function{time.localtime()}. The hours, minutes and seconds are |
| 432 | 0, and the DST flag is -1. |
| 433 | \code{\var{d}.timetuple()} is equivalent to |
Martin v. Löwis | ef36537 | 2003-09-04 18:29:53 +0000 | [diff] [blame] | 434 | \code{time.struct_time((\var{d}.year, \var{d}.month, \var{d}.day, |
Tim Peters | fdc58f2 | 2004-11-15 03:50:16 +0000 | [diff] [blame] | 435 | 0, 0, 0, |
| 436 | \var{d}.weekday(), |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 437 | \var{d}.toordinal() - date(\var{d}.year, 1, 1).toordinal() + 1, |
Martin v. Löwis | ef36537 | 2003-09-04 18:29:53 +0000 | [diff] [blame] | 438 | -1))} |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 439 | \end{methoddesc} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 440 | |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 441 | \begin{methoddesc}{toordinal}{} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 442 | Return the proleptic Gregorian ordinal of the date, where January 1 |
| 443 | of year 1 has ordinal 1. For any \class{date} object \var{d}, |
| 444 | \code{date.fromordinal(\var{d}.toordinal()) == \var{d}}. |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 445 | \end{methoddesc} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 446 | |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 447 | \begin{methoddesc}{weekday}{} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 448 | Return the day of the week as an integer, where Monday is 0 and |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 449 | Sunday is 6. For example, \code{date(2002, 12, 4).weekday() == 2}, a |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 450 | Wednesday. |
| 451 | See also \method{isoweekday()}. |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 452 | \end{methoddesc} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 453 | |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 454 | \begin{methoddesc}{isoweekday}{} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 455 | Return the day of the week as an integer, where Monday is 1 and |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 456 | Sunday is 7. For example, \code{date(2002, 12, 4).isoweekday() == 3}, a |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 457 | Wednesday. |
| 458 | See also \method{weekday()}, \method{isocalendar()}. |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 459 | \end{methoddesc} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 460 | |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 461 | \begin{methoddesc}{isocalendar}{} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 462 | Return a 3-tuple, (ISO year, ISO week number, ISO weekday). |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 463 | |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 464 | The ISO calendar is a widely used variant of the Gregorian calendar. |
| 465 | See \url{http://www.phys.uu.nl/~vgent/calendar/isocalendar.htm} |
| 466 | for a good explanation. |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 467 | |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 468 | The ISO year consists of 52 or 53 full weeks, and where a week starts |
| 469 | on a Monday and ends on a Sunday. The first week of an ISO year is |
| 470 | the first (Gregorian) calendar week of a year containing a Thursday. |
| 471 | This is called week number 1, and the ISO year of that Thursday is |
| 472 | the same as its Gregorian year. |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 473 | |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 474 | For example, 2004 begins on a Thursday, so the first week of ISO |
| 475 | year 2004 begins on Monday, 29 Dec 2003 and ends on Sunday, 4 Jan |
| 476 | 2004, so that |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 477 | \code{date(2003, 12, 29).isocalendar() == (2004, 1, 1)} |
Tim Peters | fdc58f2 | 2004-11-15 03:50:16 +0000 | [diff] [blame] | 478 | and |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 479 | \code{date(2004, 1, 4).isocalendar() == (2004, 1, 7)}. |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 480 | \end{methoddesc} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 481 | |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 482 | \begin{methoddesc}{isoformat}{} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 483 | Return a string representing the date in ISO 8601 format, |
| 484 | 'YYYY-MM-DD'. For example, |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 485 | \code{date(2002, 12, 4).isoformat() == '2002-12-04'}. |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 486 | \end{methoddesc} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 487 | |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 488 | \begin{methoddesc}{__str__}{} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 489 | For a date \var{d}, \code{str(\var{d})} is equivalent to |
| 490 | \code{\var{d}.isoformat()}. |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 491 | \end{methoddesc} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 492 | |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 493 | \begin{methoddesc}{ctime}{} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 494 | Return a string representing the date, for example |
| 495 | date(2002, 12, 4).ctime() == 'Wed Dec 4 00:00:00 2002'. |
| 496 | \code{\var{d}.ctime()} is equivalent to |
| 497 | \code{time.ctime(time.mktime(\var{d}.timetuple()))} |
| 498 | on platforms where the native C \cfunction{ctime()} function |
| 499 | (which \function{time.ctime()} invokes, but which |
| 500 | \method{date.ctime()} does not invoke) conforms to the C standard. |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 501 | \end{methoddesc} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 502 | |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 503 | \begin{methoddesc}{strftime}{format} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 504 | Return a string representing the date, controlled by an explicit |
| 505 | format string. Format codes referring to hours, minutes or seconds |
| 506 | will see 0 values. |
| 507 | See the section on \method{strftime()} behavior. |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 508 | \end{methoddesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 509 | |
| 510 | |
Raymond Hettinger | 6005a34 | 2002-12-30 20:01:24 +0000 | [diff] [blame] | 511 | \subsection{\class{datetime} Objects \label{datetime-datetime}} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 512 | |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 513 | A \class{datetime} object is a single object containing all the |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 514 | information from a \class{date} object and a \class{time} object. Like a |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 515 | \class{date} object, \class{datetime} assumes the current Gregorian |
| 516 | calendar extended in both directions; like a time object, |
| 517 | \class{datetime} assumes there are exactly 3600*24 seconds in every |
| 518 | day. |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 519 | |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 520 | Constructor: |
| 521 | |
Fred Drake | b0e8f5d | 2003-12-30 20:36:20 +0000 | [diff] [blame] | 522 | \begin{classdesc}{datetime}{year, month, day\optional{, |
| 523 | hour\optional{, minute\optional{, |
| 524 | second\optional{, microsecond\optional{, |
| 525 | tzinfo}}}}}} |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 526 | The year, month and day arguments are required. \var{tzinfo} may |
| 527 | be \code{None}, or an instance of a \class{tzinfo} subclass. The |
| 528 | remaining arguments may be ints or longs, in the following ranges: |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 529 | |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 530 | \begin{itemize} |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 531 | \item \code{MINYEAR <= \var{year} <= MAXYEAR} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 532 | \item \code{1 <= \var{month} <= 12} |
| 533 | \item \code{1 <= \var{day} <= number of days in the given month and year} |
| 534 | \item \code{0 <= \var{hour} < 24} |
| 535 | \item \code{0 <= \var{minute} < 60} |
| 536 | \item \code{0 <= \var{second} < 60} |
| 537 | \item \code{0 <= \var{microsecond} < 1000000} |
| 538 | \end{itemize} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 539 | |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 540 | If an argument outside those ranges is given, |
| 541 | \exception{ValueError} is raised. |
Fred Drake | 0f8e543 | 2002-12-31 18:31:48 +0000 | [diff] [blame] | 542 | \end{classdesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 543 | |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 544 | Other constructors, all class methods: |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 545 | |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 546 | \begin{methoddesc}{today}{} |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 547 | Return the current local datetime, with \member{tzinfo} \code{None}. |
| 548 | This is equivalent to |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 549 | \code{datetime.fromtimestamp(time.time())}. |
| 550 | See also \method{now()}, \method{fromtimestamp()}. |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 551 | \end{methoddesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 552 | |
Fred Drake | b0e8f5d | 2003-12-30 20:36:20 +0000 | [diff] [blame] | 553 | \begin{methoddesc}{now}{\optional{tz}} |
Tim Peters | 10cadce | 2003-01-23 19:58:02 +0000 | [diff] [blame] | 554 | Return the current local date and time. If optional argument |
| 555 | \var{tz} is \code{None} or not specified, this is like |
| 556 | \method{today()}, but, if possible, supplies more precision than can |
| 557 | be gotten from going through a \function{time.time()} timestamp (for |
| 558 | example, this may be possible on platforms supplying the C |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 559 | \cfunction{gettimeofday()} function). |
Tim Peters | 10cadce | 2003-01-23 19:58:02 +0000 | [diff] [blame] | 560 | |
| 561 | Else \var{tz} must be an instance of a class \class{tzinfo} subclass, |
Tim Peters | 2a44a8d | 2003-01-23 20:53:10 +0000 | [diff] [blame] | 562 | and the current date and time are converted to \var{tz}'s time |
Tim Peters | 10cadce | 2003-01-23 19:58:02 +0000 | [diff] [blame] | 563 | zone. In this case the result is equivalent to |
Tim Peters | 2a44a8d | 2003-01-23 20:53:10 +0000 | [diff] [blame] | 564 | \code{\var{tz}.fromutc(datetime.utcnow().replace(tzinfo=\var{tz}))}. |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 565 | See also \method{today()}, \method{utcnow()}. |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 566 | \end{methoddesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 567 | |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 568 | \begin{methoddesc}{utcnow}{} |
Tim Peters | 10cadce | 2003-01-23 19:58:02 +0000 | [diff] [blame] | 569 | Return the current UTC date and time, with \member{tzinfo} \code{None}. |
Tim Peters | 2a44a8d | 2003-01-23 20:53:10 +0000 | [diff] [blame] | 570 | This is like \method{now()}, but returns the current UTC date and time, |
Tim Peters | 10cadce | 2003-01-23 19:58:02 +0000 | [diff] [blame] | 571 | as a naive \class{datetime} object. |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 572 | See also \method{now()}. |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 573 | \end{methoddesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 574 | |
Fred Drake | b0e8f5d | 2003-12-30 20:36:20 +0000 | [diff] [blame] | 575 | \begin{methoddesc}{fromtimestamp}{timestamp\optional{, tz}} |
Tim Peters | 2a44a8d | 2003-01-23 20:53:10 +0000 | [diff] [blame] | 576 | Return the local date and time corresponding to the \POSIX{} |
| 577 | timestamp, such as is returned by \function{time.time()}. |
| 578 | If optional argument \var{tz} is \code{None} or not specified, the |
| 579 | timestamp is converted to the platform's local date and time, and |
| 580 | the returned \class{datetime} object is naive. |
| 581 | |
| 582 | Else \var{tz} must be an instance of a class \class{tzinfo} subclass, |
| 583 | and the timestamp is converted to \var{tz}'s time zone. In this case |
| 584 | the result is equivalent to |
| 585 | \code{\var{tz}.fromutc(datetime.utcfromtimestamp(\var{timestamp}).replace(tzinfo=\var{tz}))}. |
| 586 | |
| 587 | \method{fromtimestamp()} may raise \exception{ValueError}, if the |
| 588 | timestamp is out of the range of values supported by the platform C |
Neal Norwitz | daae327 | 2003-01-25 21:08:30 +0000 | [diff] [blame] | 589 | \cfunction{localtime()} or \cfunction{gmtime()} functions. It's common |
Tim Peters | 2a44a8d | 2003-01-23 20:53:10 +0000 | [diff] [blame] | 590 | for this to be restricted to years in 1970 through 2038. |
Tim Peters | 75a6e3b | 2003-01-04 18:17:36 +0000 | [diff] [blame] | 591 | Note that on non-POSIX systems that include leap seconds in their |
| 592 | notion of a timestamp, leap seconds are ignored by |
| 593 | \method{fromtimestamp()}, and then it's possible to have two timestamps |
| 594 | differing by a second that yield identical \class{datetime} objects. |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 595 | See also \method{utcfromtimestamp()}. |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 596 | \end{methoddesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 597 | |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 598 | \begin{methoddesc}{utcfromtimestamp}{timestamp} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 599 | Return the UTC \class{datetime} corresponding to the \POSIX{} |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 600 | timestamp, with \member{tzinfo} \code{None}. |
| 601 | This may raise \exception{ValueError}, if the |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 602 | timestamp is out of the range of values supported by the platform |
| 603 | C \cfunction{gmtime()} function. It's common for this to be |
| 604 | restricted to years in 1970 through 2038. |
| 605 | See also \method{fromtimestamp()}. |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 606 | \end{methoddesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 607 | |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 608 | \begin{methoddesc}{fromordinal}{ordinal} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 609 | Return the \class{datetime} corresponding to the proleptic |
| 610 | Gregorian ordinal, where January 1 of year 1 has ordinal 1. |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 611 | \exception{ValueError} is raised unless \code{1 <= ordinal <= |
| 612 | datetime.max.toordinal()}. The hour, minute, second and |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 613 | microsecond of the result are all 0, |
| 614 | and \member{tzinfo} is \code{None}. |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 615 | \end{methoddesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 616 | |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 617 | \begin{methoddesc}{combine}{date, time} |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 618 | Return a new \class{datetime} object whose date members are |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 619 | equal to the given \class{date} object's, and whose time |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 620 | and \member{tzinfo} members are equal to the given \class{time} object's. |
| 621 | For any \class{datetime} object \var{d}, \code{\var{d} == |
| 622 | datetime.combine(\var{d}.date(), \var{d}.timetz())}. If date is a |
| 623 | \class{datetime} object, its time and \member{tzinfo} members are |
| 624 | ignored. |
| 625 | \end{methoddesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 626 | |
Skip Montanaro | 0af3ade | 2005-01-13 04:12:31 +0000 | [diff] [blame] | 627 | \begin{methoddesc}{strptime}{date_string, format} |
| 628 | Return a \class{datetime} corresponding to \var{date_string}, parsed |
| 629 | according to \var{format}. This is equivalent to |
| 630 | \code{datetime(*(time.strptime(date_string, |
| 631 | format)[0:6]))}. \exception{ValueError} is raised if the date_string and |
| 632 | format can't be parsed by \function{time.strptime()} or if it returns a |
| 633 | value which isn't a time tuple. |
Tim Peters | 9ba3684 | 2005-01-13 21:06:25 +0000 | [diff] [blame] | 634 | |
| 635 | \versionadded{2.5} |
Skip Montanaro | 0af3ade | 2005-01-13 04:12:31 +0000 | [diff] [blame] | 636 | \end{methoddesc} |
| 637 | |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 638 | Class attributes: |
| 639 | |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 640 | \begin{memberdesc}{min} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 641 | The earliest representable \class{datetime}, |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 642 | \code{datetime(MINYEAR, 1, 1, tzinfo=None)}. |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 643 | \end{memberdesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 644 | |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 645 | \begin{memberdesc}{max} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 646 | The latest representable \class{datetime}, |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 647 | \code{datetime(MAXYEAR, 12, 31, 23, 59, 59, 999999, tzinfo=None)}. |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 648 | \end{memberdesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 649 | |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 650 | \begin{memberdesc}{resolution} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 651 | The smallest possible difference between non-equal \class{datetime} |
| 652 | objects, \code{timedelta(microseconds=1)}. |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 653 | \end{memberdesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 654 | |
| 655 | Instance attributes (read-only): |
| 656 | |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 657 | \begin{memberdesc}{year} |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 658 | Between \constant{MINYEAR} and \constant{MAXYEAR} inclusive. |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 659 | \end{memberdesc} |
| 660 | |
| 661 | \begin{memberdesc}{month} |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 662 | Between 1 and 12 inclusive. |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 663 | \end{memberdesc} |
| 664 | |
| 665 | \begin{memberdesc}{day} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 666 | Between 1 and the number of days in the given month of the given |
| 667 | year. |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 668 | \end{memberdesc} |
| 669 | |
| 670 | \begin{memberdesc}{hour} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 671 | In \code{range(24)}. |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 672 | \end{memberdesc} |
| 673 | |
| 674 | \begin{memberdesc}{minute} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 675 | In \code{range(60)}. |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 676 | \end{memberdesc} |
| 677 | |
| 678 | \begin{memberdesc}{second} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 679 | In \code{range(60)}. |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 680 | \end{memberdesc} |
| 681 | |
| 682 | \begin{memberdesc}{microsecond} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 683 | In \code{range(1000000)}. |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 684 | \end{memberdesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 685 | |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 686 | \begin{memberdesc}{tzinfo} |
| 687 | The object passed as the \var{tzinfo} argument to the |
| 688 | \class{datetime} constructor, or \code{None} if none was passed. |
| 689 | \end{memberdesc} |
| 690 | |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 691 | Supported operations: |
| 692 | |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 693 | \begin{tableii}{c|l}{code}{Operation}{Result} |
| 694 | \lineii{\var{datetime2} = \var{datetime1} + \var{timedelta}}{(1)} |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 695 | |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 696 | \lineii{\var{datetime2} = \var{datetime1} - \var{timedelta}}{(2)} |
| 697 | |
| 698 | \lineii{\var{timedelta} = \var{datetime1} - \var{datetime2}}{(3)} |
| 699 | |
| 700 | \lineii{\var{datetime1} < \var{datetime2}} |
Tim Peters | fdc58f2 | 2004-11-15 03:50:16 +0000 | [diff] [blame] | 701 | {Compares \class{datetime} to \class{datetime}. |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 702 | (4)} |
| 703 | |
| 704 | \end{tableii} |
| 705 | |
| 706 | \begin{description} |
| 707 | |
| 708 | \item[(1)] |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 709 | |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 710 | datetime2 is a duration of timedelta removed from datetime1, moving |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 711 | forward in time if \code{\var{timedelta}.days} > 0, or backward if |
| 712 | \code{\var{timedelta}.days} < 0. The result has the same \member{tzinfo} member |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 713 | as the input datetime, and datetime2 - datetime1 == timedelta after. |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 714 | \exception{OverflowError} is raised if datetime2.year would be |
| 715 | smaller than \constant{MINYEAR} or larger than \constant{MAXYEAR}. |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 716 | Note that no time zone adjustments are done even if the input is an |
| 717 | aware object. |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 718 | |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 719 | \item[(2)] |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 720 | Computes the datetime2 such that datetime2 + timedelta == datetime1. |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 721 | As for addition, the result has the same \member{tzinfo} member |
| 722 | as the input datetime, and no time zone adjustments are done even |
| 723 | if the input is aware. |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 724 | This isn't quite equivalent to datetime1 + (-timedelta), because |
| 725 | -timedelta in isolation can overflow in cases where |
| 726 | datetime1 - timedelta does not. |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 727 | |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 728 | \item[(3)] |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 729 | Subtraction of a \class{datetime} from a |
| 730 | \class{datetime} is defined only if both |
| 731 | operands are naive, or if both are aware. If one is aware and the |
| 732 | other is naive, \exception{TypeError} is raised. |
| 733 | |
| 734 | If both are naive, or both are aware and have the same \member{tzinfo} |
| 735 | member, the \member{tzinfo} members are ignored, and the result is |
| 736 | a \class{timedelta} object \var{t} such that |
| 737 | \code{\var{datetime2} + \var{t} == \var{datetime1}}. No time zone |
| 738 | adjustments are done in this case. |
| 739 | |
| 740 | If both are aware and have different \member{tzinfo} members, |
| 741 | \code{a-b} acts as if \var{a} and \var{b} were first converted to |
| 742 | naive UTC datetimes first. The result is |
| 743 | \code{(\var{a}.replace(tzinfo=None) - \var{a}.utcoffset()) - |
| 744 | (\var{b}.replace(tzinfo=None) - \var{b}.utcoffset())} |
| 745 | except that the implementation never overflows. |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 746 | |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 747 | \item[(4)] |
| 748 | |
| 749 | \var{datetime1} is considered less than \var{datetime2} |
Tim Peters | fdc58f2 | 2004-11-15 03:50:16 +0000 | [diff] [blame] | 750 | when \var{datetime1} precedes \var{datetime2} in time. |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 751 | |
| 752 | If one comparand is naive and |
| 753 | the other is aware, \exception{TypeError} is raised. If both |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 754 | comparands are aware, and have the same \member{tzinfo} member, |
| 755 | the common \member{tzinfo} member is ignored and the base datetimes |
| 756 | are compared. If both comparands are aware and have different |
| 757 | \member{tzinfo} members, the comparands are first adjusted by |
| 758 | subtracting their UTC offsets (obtained from \code{self.utcoffset()}). |
Tim Peters | 8d81a01 | 2003-01-24 22:36:34 +0000 | [diff] [blame] | 759 | \note{In order to stop comparison from falling back to the default |
| 760 | scheme of comparing object addresses, datetime comparison |
| 761 | normally raises \exception{TypeError} if the other comparand |
| 762 | isn't also a \class{datetime} object. However, |
| 763 | \code{NotImplemented} is returned instead if the other comparand |
| 764 | has a \method{timetuple} attribute. This hook gives other |
| 765 | kinds of date objects a chance at implementing mixed-type |
Tim Peters | 07534a6 | 2003-02-07 22:50:28 +0000 | [diff] [blame] | 766 | comparison. If not, when a \class{datetime} object is |
| 767 | compared to an object of a different type, \exception{TypeError} |
| 768 | is raised unless the comparison is \code{==} or \code{!=}. The |
| 769 | latter cases return \constant{False} or \constant{True}, |
| 770 | respectively.} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 771 | |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 772 | \end{description} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 773 | |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 774 | \class{datetime} objects can be used as dictionary keys. In Boolean |
| 775 | contexts, all \class{datetime} objects are considered to be true. |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 776 | |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 777 | |
| 778 | Instance methods: |
| 779 | |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 780 | \begin{methoddesc}{date}{} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 781 | Return \class{date} object with same year, month and day. |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 782 | \end{methoddesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 783 | |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 784 | \begin{methoddesc}{time}{} |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 785 | Return \class{time} object with same hour, minute, second and microsecond. |
| 786 | \member{tzinfo} is \code{None}. See also method \method{timetz()}. |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 787 | \end{methoddesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 788 | |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 789 | \begin{methoddesc}{timetz}{} |
| 790 | Return \class{time} object with same hour, minute, second, microsecond, |
| 791 | and tzinfo members. See also method \method{time()}. |
| 792 | \end{methoddesc} |
| 793 | |
Fred Drake | b0e8f5d | 2003-12-30 20:36:20 +0000 | [diff] [blame] | 794 | \begin{methoddesc}{replace}{\optional{year\optional{, month\optional{, |
| 795 | day\optional{, hour\optional{, minute\optional{, |
| 796 | second\optional{, microsecond\optional{, |
| 797 | tzinfo}}}}}}}}} |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 798 | Return a datetime with the same members, except for those members given |
| 799 | new values by whichever keyword arguments are specified. Note that |
| 800 | \code{tzinfo=None} can be specified to create a naive datetime from |
| 801 | an aware datetime with no conversion of date and time members. |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 802 | \end{methoddesc} |
Tim Peters | 12bf339 | 2002-12-24 05:41:27 +0000 | [diff] [blame] | 803 | |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 804 | \begin{methoddesc}{astimezone}{tz} |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 805 | Return a \class{datetime} object with new \member{tzinfo} member |
Tim Peters | f196a0a | 2003-01-22 04:45:50 +0000 | [diff] [blame] | 806 | \var{tz}, adjusting the date and time members so the result is the |
| 807 | same UTC time as \var{self}, but in \var{tz}'s local time. |
| 808 | |
| 809 | \var{tz} must be an instance of a \class{tzinfo} subclass, and its |
| 810 | \method{utcoffset()} and \method{dst()} methods must not return |
| 811 | \code{None}. \var{self} must be aware (\code{\var{self}.tzinfo} must |
| 812 | not be \code{None}, and \code{\var{self}.utcoffset()} must not return |
| 813 | \code{None}). |
| 814 | |
Andrew M. Kuchling | 570e358 | 2003-02-05 21:15:38 +0000 | [diff] [blame] | 815 | If \code{\var{self}.tzinfo} is \var{tz}, |
Tim Peters | f196a0a | 2003-01-22 04:45:50 +0000 | [diff] [blame] | 816 | \code{\var{self}.astimezone(\var{tz})} is equal to \var{self}: no |
| 817 | adjustment of date or time members is performed. |
| 818 | Else the result is local time in time zone \var{tz}, representing the |
| 819 | same UTC time as \var{self}: after \code{\var{astz} = |
| 820 | \var{dt}.astimezone(\var{tz})}, |
| 821 | \code{\var{astz} - \var{astz}.utcoffset()} will usually have the same |
| 822 | date and time members as \code{\var{dt} - \var{dt}.utcoffset()}. |
| 823 | The discussion of class \class{tzinfo} explains the cases at Daylight |
| 824 | Saving Time transition boundaries where this cannot be achieved (an issue |
| 825 | only if \var{tz} models both standard and daylight time). |
| 826 | |
| 827 | If you merely want to attach a time zone object \var{tz} to a |
| 828 | datetime \var{dt} without adjustment of date and time members, |
| 829 | use \code{\var{dt}.replace(tzinfo=\var{tz})}. If |
| 830 | you merely want to remove the time zone object from an aware datetime |
| 831 | \var{dt} without conversion of date and time members, use |
| 832 | \code{\var{dt}.replace(tzinfo=None)}. |
| 833 | |
| 834 | Note that the default \method{tzinfo.fromutc()} method can be overridden |
Raymond Hettinger | 1c90a67 | 2003-09-06 05:36:13 +0000 | [diff] [blame] | 835 | in a \class{tzinfo} subclass to affect the result returned by |
Tim Peters | f196a0a | 2003-01-22 04:45:50 +0000 | [diff] [blame] | 836 | \method{astimezone()}. Ignoring error cases, \method{astimezone()} |
| 837 | acts like: |
| 838 | |
| 839 | \begin{verbatim} |
| 840 | def astimezone(self, tz): |
| 841 | if self.tzinfo is tz: |
| 842 | return self |
| 843 | # Convert self to UTC, and attach the new time zone object. |
| 844 | utc = (self - self.utcoffset()).replace(tzinfo=tz) |
| 845 | # Convert from UTC to tz's local time. |
| 846 | return tz.fromutc(utc) |
| 847 | \end{verbatim} |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 848 | \end{methoddesc} |
| 849 | |
| 850 | \begin{methoddesc}{utcoffset}{} |
| 851 | If \member{tzinfo} is \code{None}, returns \code{None}, else |
Tim Peters | f196a0a | 2003-01-22 04:45:50 +0000 | [diff] [blame] | 852 | returns \code{\var{self}.tzinfo.utcoffset(\var{self})}, and |
| 853 | raises an exception if the latter doesn't return \code{None}, or |
| 854 | a \class{timedelta} object representing a whole number of minutes |
| 855 | with magnitude less than one day. |
| 856 | \end{methoddesc} |
| 857 | |
| 858 | \begin{methoddesc}{dst}{} |
| 859 | If \member{tzinfo} is \code{None}, returns \code{None}, else |
| 860 | returns \code{\var{self}.tzinfo.dst(\var{self})}, and |
| 861 | raises an exception if the latter doesn't return \code{None}, or |
| 862 | a \class{timedelta} object representing a whole number of minutes |
| 863 | with magnitude less than one day. |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 864 | \end{methoddesc} |
| 865 | |
| 866 | \begin{methoddesc}{tzname}{} |
| 867 | If \member{tzinfo} is \code{None}, returns \code{None}, else |
Tim Peters | f196a0a | 2003-01-22 04:45:50 +0000 | [diff] [blame] | 868 | returns \code{\var{self}.tzinfo.tzname(\var{self})}, |
| 869 | raises an exception if the latter doesn't return \code{None} or |
| 870 | a string object, |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 871 | \end{methoddesc} |
Tim Peters | 80475bb | 2002-12-25 07:40:55 +0000 | [diff] [blame] | 872 | |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 873 | \begin{methoddesc}{timetuple}{} |
Martin v. Löwis | ef36537 | 2003-09-04 18:29:53 +0000 | [diff] [blame] | 874 | Return a \class{time.struct_time} such as returned by |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 875 | \function{time.localtime()}. |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 876 | \code{\var{d}.timetuple()} is equivalent to |
Martin v. Löwis | ef36537 | 2003-09-04 18:29:53 +0000 | [diff] [blame] | 877 | \code{time.struct_time((\var{d}.year, \var{d}.month, \var{d}.day, |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 878 | \var{d}.hour, \var{d}.minute, \var{d}.second, |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 879 | \var{d}.weekday(), |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 880 | \var{d}.toordinal() - date(\var{d}.year, 1, 1).toordinal() + 1, |
Martin v. Löwis | ef36537 | 2003-09-04 18:29:53 +0000 | [diff] [blame] | 881 | dst))} |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 882 | The \member{tm_isdst} flag of the result is set according to |
| 883 | the \method{dst()} method: \member{tzinfo} is \code{None} or |
| 884 | \method{dst()} returns \code{None}, |
| 885 | \member{tm_isdst} is set to \code{-1}; else if \method{dst()} returns |
| 886 | a non-zero value, \member{tm_isdst} is set to \code{1}; |
| 887 | else \code{tm_isdst} is set to \code{0}. |
| 888 | \end{methoddesc} |
| 889 | |
| 890 | \begin{methoddesc}{utctimetuple}{} |
| 891 | If \class{datetime} instance \var{d} is naive, this is the same as |
| 892 | \code{\var{d}.timetuple()} except that \member{tm_isdst} is forced to 0 |
| 893 | regardless of what \code{d.dst()} returns. DST is never in effect |
| 894 | for a UTC time. |
| 895 | |
| 896 | If \var{d} is aware, \var{d} is normalized to UTC time, by subtracting |
Martin v. Löwis | ef36537 | 2003-09-04 18:29:53 +0000 | [diff] [blame] | 897 | \code{\var{d}.utcoffset()}, and a \class{time.struct_time} for the |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 898 | normalized time is returned. \member{tm_isdst} is forced to 0. |
| 899 | Note that the result's \member{tm_year} member may be |
| 900 | \constant{MINYEAR}-1 or \constant{MAXYEAR}+1, if \var{d}.year was |
| 901 | \code{MINYEAR} or \code{MAXYEAR} and UTC adjustment spills over a |
| 902 | year boundary. |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 903 | \end{methoddesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 904 | |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 905 | \begin{methoddesc}{toordinal}{} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 906 | Return the proleptic Gregorian ordinal of the date. The same as |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 907 | \code{self.date().toordinal()}. |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 908 | \end{methoddesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 909 | |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 910 | \begin{methoddesc}{weekday}{} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 911 | Return the day of the week as an integer, where Monday is 0 and |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 912 | Sunday is 6. The same as \code{self.date().weekday()}. |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 913 | See also \method{isoweekday()}. |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 914 | \end{methoddesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 915 | |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 916 | \begin{methoddesc}{isoweekday}{} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 917 | Return the day of the week as an integer, where Monday is 1 and |
Raymond Hettinger | eca984f | 2003-05-10 04:21:08 +0000 | [diff] [blame] | 918 | Sunday is 7. The same as \code{self.date().isoweekday()}. |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 919 | See also \method{weekday()}, \method{isocalendar()}. |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 920 | \end{methoddesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 921 | |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 922 | \begin{methoddesc}{isocalendar}{} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 923 | Return a 3-tuple, (ISO year, ISO week number, ISO weekday). The |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 924 | same as \code{self.date().isocalendar()}. |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 925 | \end{methoddesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 926 | |
Fred Drake | b0e8f5d | 2003-12-30 20:36:20 +0000 | [diff] [blame] | 927 | \begin{methoddesc}{isoformat}{\optional{sep}} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 928 | Return a string representing the date and time in ISO 8601 format, |
| 929 | YYYY-MM-DDTHH:MM:SS.mmmmmm |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 930 | or, if \member{microsecond} is 0, |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 931 | YYYY-MM-DDTHH:MM:SS |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 932 | |
| 933 | If \method{utcoffset()} does not return \code{None}, a 6-character |
| 934 | string is appended, giving the UTC offset in (signed) hours and |
| 935 | minutes: |
| 936 | YYYY-MM-DDTHH:MM:SS.mmmmmm+HH:MM |
| 937 | or, if \member{microsecond} is 0 |
| 938 | YYYY-MM-DDTHH:MM:SS+HH:MM |
| 939 | |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 940 | The optional argument \var{sep} (default \code{'T'}) is a |
| 941 | one-character separator, placed between the date and time portions |
| 942 | of the result. For example, |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 943 | |
| 944 | \begin{verbatim} |
| 945 | >>> from datetime import tzinfo, timedelta, datetime |
| 946 | >>> class TZ(tzinfo): |
| 947 | ... def utcoffset(self, dt): return timedelta(minutes=-399) |
| 948 | ... |
| 949 | >>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ') |
| 950 | '2002-12-25 00:00:00-06:39' |
| 951 | \end{verbatim} |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 952 | \end{methoddesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 953 | |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 954 | \begin{methoddesc}{__str__}{} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 955 | For a \class{datetime} instance \var{d}, \code{str(\var{d})} is |
| 956 | equivalent to \code{\var{d}.isoformat(' ')}. |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 957 | \end{methoddesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 958 | |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 959 | \begin{methoddesc}{ctime}{} |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 960 | Return a string representing the date and time, for example |
| 961 | \code{datetime(2002, 12, 4, 20, 30, 40).ctime() == |
| 962 | 'Wed Dec 4 20:30:40 2002'}. |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 963 | \code{d.ctime()} is equivalent to |
| 964 | \code{time.ctime(time.mktime(d.timetuple()))} on platforms where |
| 965 | the native C \cfunction{ctime()} function (which |
| 966 | \function{time.ctime()} invokes, but which |
| 967 | \method{datetime.ctime()} does not invoke) conforms to the C |
| 968 | standard. |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 969 | \end{methoddesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 970 | |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 971 | \begin{methoddesc}{strftime}{format} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 972 | Return a string representing the date and time, controlled by an |
| 973 | explicit format string. See the section on \method{strftime()} |
| 974 | behavior. |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 975 | \end{methoddesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 976 | |
| 977 | |
Raymond Hettinger | 6005a34 | 2002-12-30 20:01:24 +0000 | [diff] [blame] | 978 | \subsection{\class{time} Objects \label{datetime-time}} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 979 | |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 980 | A time object represents a (local) time of day, independent of any |
| 981 | particular day, and subject to adjustment via a \class{tzinfo} object. |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 982 | |
Fred Drake | b0e8f5d | 2003-12-30 20:36:20 +0000 | [diff] [blame] | 983 | \begin{classdesc}{time}{hour\optional{, minute\optional{, second\optional{, |
| 984 | microsecond\optional{, tzinfo}}}}} |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 985 | All arguments are optional. \var{tzinfo} may be \code{None}, or |
| 986 | an instance of a \class{tzinfo} subclass. The remaining arguments |
| 987 | may be ints or longs, in the following ranges: |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 988 | |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 989 | \begin{itemize} |
| 990 | \item \code{0 <= \var{hour} < 24} |
| 991 | \item \code{0 <= \var{minute} < 60} |
| 992 | \item \code{0 <= \var{second} < 60} |
| 993 | \item \code{0 <= \var{microsecond} < 1000000}. |
| 994 | \end{itemize} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 995 | |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 996 | If an argument outside those ranges is given, |
Fred Drake | b0e8f5d | 2003-12-30 20:36:20 +0000 | [diff] [blame] | 997 | \exception{ValueError} is raised. All default to \code{0} except |
| 998 | \var{tzinfo}, which defaults to \constant{None}. |
Fred Drake | 0f8e543 | 2002-12-31 18:31:48 +0000 | [diff] [blame] | 999 | \end{classdesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 1000 | |
| 1001 | Class attributes: |
| 1002 | |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 1003 | \begin{memberdesc}{min} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 1004 | The earliest representable \class{time}, \code{time(0, 0, 0, 0)}. |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 1005 | \end{memberdesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 1006 | |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 1007 | \begin{memberdesc}{max} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 1008 | The latest representable \class{time}, \code{time(23, 59, 59, 999999)}. |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 1009 | \end{memberdesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 1010 | |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 1011 | \begin{memberdesc}{resolution} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 1012 | The smallest possible difference between non-equal \class{time} |
| 1013 | objects, \code{timedelta(microseconds=1)}, although note that |
| 1014 | arithmetic on \class{time} objects is not supported. |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 1015 | \end{memberdesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 1016 | |
| 1017 | Instance attributes (read-only): |
| 1018 | |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 1019 | \begin{memberdesc}{hour} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 1020 | In \code{range(24)}. |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 1021 | \end{memberdesc} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 1022 | |
Tim Peters | bad8ff0 | 2002-12-30 20:52:32 +0000 | [diff] [blame] | 1023 | \begin{memberdesc}{minute} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 1024 | In \code{range(60)}. |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 1025 | \end{memberdesc} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 1026 | |
Tim Peters | bad8ff0 | 2002-12-30 20:52:32 +0000 | [diff] [blame] | 1027 | \begin{memberdesc}{second} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 1028 | In \code{range(60)}. |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 1029 | \end{memberdesc} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 1030 | |
Tim Peters | bad8ff0 | 2002-12-30 20:52:32 +0000 | [diff] [blame] | 1031 | \begin{memberdesc}{microsecond} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 1032 | In \code{range(1000000)}. |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 1033 | \end{memberdesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 1034 | |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 1035 | \begin{memberdesc}{tzinfo} |
| 1036 | The object passed as the tzinfo argument to the \class{time} |
| 1037 | constructor, or \code{None} if none was passed. |
| 1038 | \end{memberdesc} |
| 1039 | |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 1040 | Supported operations: |
| 1041 | |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 1042 | \begin{itemize} |
| 1043 | \item |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 1044 | comparison of \class{time} to \class{time}, |
| 1045 | where \var{a} is considered less than \var{b} when \var{a} precedes |
| 1046 | \var{b} in time. If one comparand is naive and the other is aware, |
| 1047 | \exception{TypeError} is raised. If both comparands are aware, and |
| 1048 | have the same \member{tzinfo} member, the common \member{tzinfo} |
| 1049 | member is ignored and the base times are compared. If both |
| 1050 | comparands are aware and have different \member{tzinfo} members, |
| 1051 | the comparands are first adjusted by subtracting their UTC offsets |
| 1052 | (obtained from \code{self.utcoffset()}). |
Tim Peters | 07534a6 | 2003-02-07 22:50:28 +0000 | [diff] [blame] | 1053 | In order to stop mixed-type comparisons from falling back to the |
| 1054 | default comparison by object address, when a \class{time} object is |
| 1055 | compared to an object of a different type, \exception{TypeError} is |
| 1056 | raised unless the comparison is \code{==} or \code{!=}. The latter |
| 1057 | cases return \constant{False} or \constant{True}, respectively. |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 1058 | |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 1059 | \item |
| 1060 | hash, use as dict key |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 1061 | |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 1062 | \item |
| 1063 | efficient pickling |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 1064 | |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 1065 | \item |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 1066 | in Boolean contexts, a \class{time} object is considered to be |
| 1067 | true if and only if, after converting it to minutes and |
| 1068 | subtracting \method{utcoffset()} (or \code{0} if that's |
| 1069 | \code{None}), the result is non-zero. |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 1070 | \end{itemize} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 1071 | |
| 1072 | Instance methods: |
| 1073 | |
Fred Drake | b0e8f5d | 2003-12-30 20:36:20 +0000 | [diff] [blame] | 1074 | \begin{methoddesc}{replace}{\optional{hour\optional{, minute\optional{, |
| 1075 | second\optional{, microsecond\optional{, |
| 1076 | tzinfo}}}}}} |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 1077 | Return a \class{time} with the same value, except for those members given |
| 1078 | new values by whichever keyword arguments are specified. Note that |
| 1079 | \code{tzinfo=None} can be specified to create a naive \class{time} from |
| 1080 | an aware \class{time}, without conversion of the time members. |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 1081 | \end{methoddesc} |
Tim Peters | 12bf339 | 2002-12-24 05:41:27 +0000 | [diff] [blame] | 1082 | |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 1083 | \begin{methoddesc}{isoformat}{} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 1084 | Return a string representing the time in ISO 8601 format, |
| 1085 | HH:MM:SS.mmmmmm |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 1086 | or, if self.microsecond is 0, |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 1087 | HH:MM:SS |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 1088 | If \method{utcoffset()} does not return \code{None}, a 6-character |
| 1089 | string is appended, giving the UTC offset in (signed) hours and |
| 1090 | minutes: |
| 1091 | HH:MM:SS.mmmmmm+HH:MM |
| 1092 | or, if self.microsecond is 0, |
| 1093 | HH:MM:SS+HH:MM |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 1094 | \end{methoddesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 1095 | |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 1096 | \begin{methoddesc}{__str__}{} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 1097 | For a time \var{t}, \code{str(\var{t})} is equivalent to |
| 1098 | \code{\var{t}.isoformat()}. |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 1099 | \end{methoddesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 1100 | |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 1101 | \begin{methoddesc}{strftime}{format} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 1102 | Return a string representing the time, controlled by an explicit |
| 1103 | format string. See the section on \method{strftime()} behavior. |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 1104 | \end{methoddesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 1105 | |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 1106 | \begin{methoddesc}{utcoffset}{} |
| 1107 | If \member{tzinfo} is \code{None}, returns \code{None}, else |
Tim Peters | f196a0a | 2003-01-22 04:45:50 +0000 | [diff] [blame] | 1108 | returns \code{\var{self}.tzinfo.utcoffset(None)}, and |
| 1109 | raises an exception if the latter doesn't return \code{None} or |
| 1110 | a \class{timedelta} object representing a whole number of minutes |
| 1111 | with magnitude less than one day. |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 1112 | \end{methoddesc} |
| 1113 | |
| 1114 | \begin{methoddesc}{dst}{} |
| 1115 | If \member{tzinfo} is \code{None}, returns \code{None}, else |
Tim Peters | f196a0a | 2003-01-22 04:45:50 +0000 | [diff] [blame] | 1116 | returns \code{\var{self}.tzinfo.dst(None)}, and |
| 1117 | raises an exception if the latter doesn't return \code{None}, or |
| 1118 | a \class{timedelta} object representing a whole number of minutes |
| 1119 | with magnitude less than one day. |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 1120 | \end{methoddesc} |
| 1121 | |
| 1122 | \begin{methoddesc}{tzname}{} |
| 1123 | If \member{tzinfo} is \code{None}, returns \code{None}, else |
Tim Peters | f196a0a | 2003-01-22 04:45:50 +0000 | [diff] [blame] | 1124 | returns \code{\var{self}.tzinfo.tzname(None)}, or |
| 1125 | raises an exception if the latter doesn't return \code{None} or |
| 1126 | a string object. |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 1127 | \end{methoddesc} |
| 1128 | |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 1129 | |
Raymond Hettinger | 6005a34 | 2002-12-30 20:01:24 +0000 | [diff] [blame] | 1130 | \subsection{\class{tzinfo} Objects \label{datetime-tzinfo}} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 1131 | |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 1132 | \class{tzinfo} is an abstract base clase, meaning that this class |
| 1133 | should not be instantiated directly. You need to derive a concrete |
| 1134 | subclass, and (at least) supply implementations of the standard |
| 1135 | \class{tzinfo} methods needed by the \class{datetime} methods you |
Tim Peters | bad8ff0 | 2002-12-30 20:52:32 +0000 | [diff] [blame] | 1136 | use. The \module{datetime} module does not supply any concrete |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 1137 | subclasses of \class{tzinfo}. |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 1138 | |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 1139 | An instance of (a concrete subclass of) \class{tzinfo} can be passed |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 1140 | to the constructors for \class{datetime} and \class{time} objects. |
| 1141 | The latter objects view their members as being in local time, and the |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 1142 | \class{tzinfo} object supports methods revealing offset of local time |
| 1143 | from UTC, the name of the time zone, and DST offset, all relative to a |
| 1144 | date or time object passed to them. |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 1145 | |
Tim Peters | bad8ff0 | 2002-12-30 20:52:32 +0000 | [diff] [blame] | 1146 | Special requirement for pickling: A \class{tzinfo} subclass must have an |
Tim Peters | 2483b61 | 2002-12-24 16:30:58 +0000 | [diff] [blame] | 1147 | \method{__init__} method that can be called with no arguments, else it |
| 1148 | can be pickled but possibly not unpickled again. This is a technical |
| 1149 | requirement that may be relaxed in the future. |
| 1150 | |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 1151 | A concrete subclass of \class{tzinfo} may need to implement the |
| 1152 | following methods. Exactly which methods are needed depends on the |
Tim Peters | bad8ff0 | 2002-12-30 20:52:32 +0000 | [diff] [blame] | 1153 | uses made of aware \module{datetime} objects. If in doubt, simply |
| 1154 | implement all of them. |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 1155 | |
Tim Peters | bad8ff0 | 2002-12-30 20:52:32 +0000 | [diff] [blame] | 1156 | \begin{methoddesc}{utcoffset}{self, dt} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 1157 | Return offset of local time from UTC, in minutes east of UTC. If |
| 1158 | local time is west of UTC, this should be negative. Note that this |
| 1159 | is intended to be the total offset from UTC; for example, if a |
| 1160 | \class{tzinfo} object represents both time zone and DST adjustments, |
| 1161 | \method{utcoffset()} should return their sum. If the UTC offset |
| 1162 | isn't known, return \code{None}. Else the value returned must be |
Tim Peters | 397301e | 2003-01-02 21:28:08 +0000 | [diff] [blame] | 1163 | a \class{timedelta} object specifying a whole number of minutes in the |
| 1164 | range -1439 to 1439 inclusive (1440 = 24*60; the magnitude of the offset |
| 1165 | must be less than one day). Most implementations of |
| 1166 | \method{utcoffset()} will probably look like one of these two: |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 1167 | |
Tim Peters | bad8ff0 | 2002-12-30 20:52:32 +0000 | [diff] [blame] | 1168 | \begin{verbatim} |
Tim Peters | f361515 | 2003-01-01 21:51:37 +0000 | [diff] [blame] | 1169 | return CONSTANT # fixed-offset class |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 1170 | return CONSTANT + self.dst(dt) # daylight-aware class |
Guido van Rossum | 8e7ec7c | 2002-12-31 04:39:05 +0000 | [diff] [blame] | 1171 | \end{verbatim} |
Tim Peters | 710fb15 | 2003-01-02 19:35:54 +0000 | [diff] [blame] | 1172 | |
| 1173 | If \method{utcoffset()} does not return \code{None}, |
| 1174 | \method{dst()} should not return \code{None} either. |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 1175 | |
Tim Peters | 327098a | 2003-01-20 22:54:38 +0000 | [diff] [blame] | 1176 | The default implementation of \method{utcoffset()} raises |
| 1177 | \exception{NotImplementedError}. |
| 1178 | \end{methoddesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 1179 | |
Tim Peters | bad8ff0 | 2002-12-30 20:52:32 +0000 | [diff] [blame] | 1180 | \begin{methoddesc}{dst}{self, dt} |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 1181 | Return the daylight saving time (DST) adjustment, in minutes east of |
Tim Peters | b01c39b | 2003-01-21 16:44:27 +0000 | [diff] [blame] | 1182 | UTC, or \code{None} if DST information isn't known. Return |
| 1183 | \code{timedelta(0)} if DST is not in effect. |
Tim Peters | 397301e | 2003-01-02 21:28:08 +0000 | [diff] [blame] | 1184 | If DST is in effect, return the offset as a |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 1185 | \class{timedelta} object (see \method{utcoffset()} for details). |
| 1186 | Note that DST offset, if applicable, has |
| 1187 | already been added to the UTC offset returned by |
| 1188 | \method{utcoffset()}, so there's no need to consult \method{dst()} |
Tim Peters | 327098a | 2003-01-20 22:54:38 +0000 | [diff] [blame] | 1189 | unless you're interested in obtaining DST info separately. For |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 1190 | example, \method{datetime.timetuple()} calls its \member{tzinfo} |
Fred Drake | 436eadd | 2002-12-31 18:13:11 +0000 | [diff] [blame] | 1191 | member's \method{dst()} method to determine how the |
Tim Peters | f361515 | 2003-01-01 21:51:37 +0000 | [diff] [blame] | 1192 | \member{tm_isdst} flag should be set, and |
Tim Peters | f196a0a | 2003-01-22 04:45:50 +0000 | [diff] [blame] | 1193 | \method{tzinfo.fromutc()} calls \method{dst()} to account for |
Tim Peters | f361515 | 2003-01-01 21:51:37 +0000 | [diff] [blame] | 1194 | DST changes when crossing time zones. |
| 1195 | |
| 1196 | An instance \var{tz} of a \class{tzinfo} subclass that models both |
| 1197 | standard and daylight times must be consistent in this sense: |
| 1198 | |
Tim Peters | f196a0a | 2003-01-22 04:45:50 +0000 | [diff] [blame] | 1199 | \code{\var{tz}.utcoffset(\var{dt}) - \var{tz}.dst(\var{dt})} |
Tim Peters | f361515 | 2003-01-01 21:51:37 +0000 | [diff] [blame] | 1200 | |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 1201 | must return the same result for every \class{datetime} \var{dt} |
Fred Drake | b0e8f5d | 2003-12-30 20:36:20 +0000 | [diff] [blame] | 1202 | with \code{\var{dt}.tzinfo == \var{tz}} For sane \class{tzinfo} |
Tim Peters | f196a0a | 2003-01-22 04:45:50 +0000 | [diff] [blame] | 1203 | subclasses, this expression yields the time zone's "standard offset", |
| 1204 | which should not depend on the date or the time, but only on geographic |
| 1205 | location. The implementation of \method{datetime.astimezone()} relies |
| 1206 | on this, but cannot detect violations; it's the programmer's |
| 1207 | responsibility to ensure it. If a \class{tzinfo} subclass cannot |
| 1208 | guarantee this, it may be able to override the default implementation |
| 1209 | of \method{tzinfo.fromutc()} to work correctly with \method{astimezone()} |
| 1210 | regardless. |
| 1211 | |
| 1212 | Most implementations of \method{dst()} will probably look like one |
| 1213 | of these two: |
| 1214 | |
| 1215 | \begin{verbatim} |
Fred Drake | b0e8f5d | 2003-12-30 20:36:20 +0000 | [diff] [blame] | 1216 | def dst(self): |
| 1217 | # a fixed-offset class: doesn't account for DST |
| 1218 | return timedelta(0) |
| 1219 | \end{verbatim} |
Tim Peters | f196a0a | 2003-01-22 04:45:50 +0000 | [diff] [blame] | 1220 | |
| 1221 | or |
| 1222 | |
Fred Drake | b0e8f5d | 2003-12-30 20:36:20 +0000 | [diff] [blame] | 1223 | \begin{verbatim} |
| 1224 | def dst(self): |
| 1225 | # Code to set dston and dstoff to the time zone's DST |
| 1226 | # transition times based on the input dt.year, and expressed |
| 1227 | # in standard local time. Then |
Tim Peters | f196a0a | 2003-01-22 04:45:50 +0000 | [diff] [blame] | 1228 | |
Fred Drake | b0e8f5d | 2003-12-30 20:36:20 +0000 | [diff] [blame] | 1229 | if dston <= dt.replace(tzinfo=None) < dstoff: |
| 1230 | return timedelta(hours=1) |
| 1231 | else: |
| 1232 | return timedelta(0) |
Tim Peters | f196a0a | 2003-01-22 04:45:50 +0000 | [diff] [blame] | 1233 | \end{verbatim} |
Tim Peters | f361515 | 2003-01-01 21:51:37 +0000 | [diff] [blame] | 1234 | |
Tim Peters | 327098a | 2003-01-20 22:54:38 +0000 | [diff] [blame] | 1235 | The default implementation of \method{dst()} raises |
| 1236 | \exception{NotImplementedError}. |
| 1237 | \end{methoddesc} |
| 1238 | |
Tim Peters | 710fb15 | 2003-01-02 19:35:54 +0000 | [diff] [blame] | 1239 | \begin{methoddesc}{tzname}{self, dt} |
Tim Peters | f196a0a | 2003-01-22 04:45:50 +0000 | [diff] [blame] | 1240 | Return the time zone name corresponding to the \class{datetime} |
| 1241 | object \var{dt}, as a string. |
| 1242 | Nothing about string names is defined by the |
| 1243 | \module{datetime} module, and there's no requirement that it mean |
| 1244 | anything in particular. For example, "GMT", "UTC", "-500", "-5:00", |
| 1245 | "EDT", "US/Eastern", "America/New York" are all valid replies. Return |
Tim Peters | 710fb15 | 2003-01-02 19:35:54 +0000 | [diff] [blame] | 1246 | \code{None} if a string name isn't known. Note that this is a method |
Tim Peters | f196a0a | 2003-01-22 04:45:50 +0000 | [diff] [blame] | 1247 | rather than a fixed string primarily because some \class{tzinfo} |
| 1248 | subclasses will wish to return different names depending on the specific |
| 1249 | value of \var{dt} passed, especially if the \class{tzinfo} class is |
Tim Peters | 710fb15 | 2003-01-02 19:35:54 +0000 | [diff] [blame] | 1250 | accounting for daylight time. |
Tim Peters | 710fb15 | 2003-01-02 19:35:54 +0000 | [diff] [blame] | 1251 | |
Tim Peters | 327098a | 2003-01-20 22:54:38 +0000 | [diff] [blame] | 1252 | The default implementation of \method{tzname()} raises |
| 1253 | \exception{NotImplementedError}. |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 1254 | \end{methoddesc} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 1255 | |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 1256 | These methods are called by a \class{datetime} or \class{time} object, |
| 1257 | in response to their methods of the same names. A \class{datetime} |
| 1258 | object passes itself as the argument, and a \class{time} object passes |
Tim Peters | bad8ff0 | 2002-12-30 20:52:32 +0000 | [diff] [blame] | 1259 | \code{None} as the argument. A \class{tzinfo} subclass's methods should |
| 1260 | therefore be prepared to accept a \var{dt} argument of \code{None}, or of |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 1261 | class \class{datetime}. |
Tim Peters | bad8ff0 | 2002-12-30 20:52:32 +0000 | [diff] [blame] | 1262 | |
| 1263 | When \code{None} is passed, it's up to the class designer to decide the |
| 1264 | best response. For example, returning \code{None} is appropriate if the |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 1265 | class wishes to say that time objects don't participate in the |
Tim Peters | f196a0a | 2003-01-22 04:45:50 +0000 | [diff] [blame] | 1266 | \class{tzinfo} protocols. It may be more useful for \code{utcoffset(None)} |
Tim Peters | 327098a | 2003-01-20 22:54:38 +0000 | [diff] [blame] | 1267 | to return the standard UTC offset, as there is no other convention for |
| 1268 | discovering the standard offset. |
Tim Peters | bad8ff0 | 2002-12-30 20:52:32 +0000 | [diff] [blame] | 1269 | |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 1270 | When a \class{datetime} object is passed in response to a |
| 1271 | \class{datetime} method, \code{dt.tzinfo} is the same object as |
Tim Peters | bad8ff0 | 2002-12-30 20:52:32 +0000 | [diff] [blame] | 1272 | \var{self}. \class{tzinfo} methods can rely on this, unless |
| 1273 | user code calls \class{tzinfo} methods directly. The intent is that |
| 1274 | the \class{tzinfo} methods interpret \var{dt} as being in local time, |
Tim Peters | 327098a | 2003-01-20 22:54:38 +0000 | [diff] [blame] | 1275 | and not need worry about objects in other timezones. |
Tim Peters | bad8ff0 | 2002-12-30 20:52:32 +0000 | [diff] [blame] | 1276 | |
Tim Peters | f196a0a | 2003-01-22 04:45:50 +0000 | [diff] [blame] | 1277 | There is one more \class{tzinfo} method that a subclass may wish to |
| 1278 | override: |
| 1279 | |
| 1280 | \begin{methoddesc}{fromutc}{self, dt} |
| 1281 | This is called from the default \class{datetime.astimezone()} |
| 1282 | implementation. When called from that, \code{\var{dt}.tzinfo} is |
| 1283 | \var{self}, and \var{dt}'s date and time members are to be viewed as |
| 1284 | expressing a UTC time. The purpose of \method{fromutc()} is to |
| 1285 | adjust the date and time members, returning an equivalent datetime in |
| 1286 | \var{self}'s local time. |
| 1287 | |
| 1288 | Most \class{tzinfo} subclasses should be able to inherit the default |
| 1289 | \method{fromutc()} implementation without problems. It's strong enough |
| 1290 | to handle fixed-offset time zones, and time zones accounting for both |
| 1291 | standard and daylight time, and the latter even if the DST transition |
| 1292 | times differ in different years. An example of a time zone the default |
| 1293 | \method{fromutc()} implementation may not handle correctly in all cases |
| 1294 | is one where the standard offset (from UTC) depends on the specific date |
| 1295 | and time passed, which can happen for political reasons. |
| 1296 | The default implementations of \method{astimezone()} and |
| 1297 | \method{fromutc()} may not produce the result you want if the result is |
| 1298 | one of the hours straddling the moment the standard offset changes. |
| 1299 | |
| 1300 | Skipping code for error cases, the default \method{fromutc()} |
| 1301 | implementation acts like: |
| 1302 | |
| 1303 | \begin{verbatim} |
| 1304 | def fromutc(self, dt): |
| 1305 | # raise ValueError error if dt.tzinfo is not self |
| 1306 | dtoff = dt.utcoffset() |
| 1307 | dtdst = dt.dst() |
| 1308 | # raise ValueError if dtoff is None or dtdst is None |
| 1309 | delta = dtoff - dtdst # this is self's standard offset |
| 1310 | if delta: |
| 1311 | dt += delta # convert to standard local time |
| 1312 | dtdst = dt.dst() |
| 1313 | # raise ValueError if dtdst is None |
| 1314 | if dtdst: |
| 1315 | return dt + dtdst |
| 1316 | else: |
| 1317 | return dt |
| 1318 | \end{verbatim} |
| 1319 | \end{methoddesc} |
| 1320 | |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 1321 | Example \class{tzinfo} classes: |
| 1322 | |
Fred Drake | bbdb250 | 2002-12-23 18:58:06 +0000 | [diff] [blame] | 1323 | \verbatiminput{tzinfo-examples.py} |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 1324 | |
Tim Peters | 327098a | 2003-01-20 22:54:38 +0000 | [diff] [blame] | 1325 | Note that there are unavoidable subtleties twice per year in a |
| 1326 | \class{tzinfo} |
Tim Peters | adf6420 | 2003-01-04 06:03:15 +0000 | [diff] [blame] | 1327 | subclass accounting for both standard and daylight time, at the DST |
| 1328 | transition points. For concreteness, consider US Eastern (UTC -0500), |
| 1329 | where EDT begins the minute after 1:59 (EST) on the first Sunday in |
| 1330 | April, and ends the minute after 1:59 (EDT) on the last Sunday in October: |
| 1331 | |
| 1332 | \begin{verbatim} |
| 1333 | UTC 3:MM 4:MM 5:MM 6:MM 7:MM 8:MM |
| 1334 | EST 22:MM 23:MM 0:MM 1:MM 2:MM 3:MM |
| 1335 | EDT 23:MM 0:MM 1:MM 2:MM 3:MM 4:MM |
| 1336 | |
| 1337 | start 22:MM 23:MM 0:MM 1:MM 3:MM 4:MM |
| 1338 | |
| 1339 | end 23:MM 0:MM 1:MM 1:MM 2:MM 3:MM |
| 1340 | \end{verbatim} |
| 1341 | |
| 1342 | When DST starts (the "start" line), the local wall clock leaps from 1:59 |
| 1343 | to 3:00. A wall time of the form 2:MM doesn't really make sense on that |
Tim Peters | 75a6e3b | 2003-01-04 18:17:36 +0000 | [diff] [blame] | 1344 | day, so \code{astimezone(Eastern)} won't deliver a result with |
Fred Drake | b0e8f5d | 2003-12-30 20:36:20 +0000 | [diff] [blame] | 1345 | \code{hour == 2} on the |
Tim Peters | 327098a | 2003-01-20 22:54:38 +0000 | [diff] [blame] | 1346 | day DST begins. In order for \method{astimezone()} to make this |
Tim Peters | f196a0a | 2003-01-22 04:45:50 +0000 | [diff] [blame] | 1347 | guarantee, the \method{rzinfo.dst()} method must consider times |
Tim Peters | 327098a | 2003-01-20 22:54:38 +0000 | [diff] [blame] | 1348 | in the "missing hour" (2:MM for Eastern) to be in daylight time. |
Tim Peters | adf6420 | 2003-01-04 06:03:15 +0000 | [diff] [blame] | 1349 | |
| 1350 | When DST ends (the "end" line), there's a potentially worse problem: |
Tim Peters | 327098a | 2003-01-20 22:54:38 +0000 | [diff] [blame] | 1351 | there's an hour that can't be spelled unambiguously in local wall time: |
| 1352 | the last hour of daylight time. In Eastern, that's times of |
| 1353 | the form 5:MM UTC on the day daylight time ends. The local wall clock |
Tim Peters | adf6420 | 2003-01-04 06:03:15 +0000 | [diff] [blame] | 1354 | leaps from 1:59 (daylight time) back to 1:00 (standard time) again. |
Tim Peters | 327098a | 2003-01-20 22:54:38 +0000 | [diff] [blame] | 1355 | Local times of the form 1:MM are ambiguous. \method{astimezone()} mimics |
| 1356 | the local clock's behavior by mapping two adjacent UTC hours into the |
| 1357 | same local hour then. In the Eastern example, UTC times of the form |
| 1358 | 5:MM and 6:MM both map to 1:MM when converted to Eastern. In order for |
Tim Peters | f196a0a | 2003-01-22 04:45:50 +0000 | [diff] [blame] | 1359 | \method{astimezone()} to make this guarantee, the \method{tzinfo.dst()} |
| 1360 | method must consider times in the "repeated hour" to be in |
Tim Peters | 327098a | 2003-01-20 22:54:38 +0000 | [diff] [blame] | 1361 | standard time. This is easily arranged, as in the example, by expressing |
| 1362 | DST switch times in the time zone's standard local time. |
Tim Peters | adf6420 | 2003-01-04 06:03:15 +0000 | [diff] [blame] | 1363 | |
Tim Peters | 327098a | 2003-01-20 22:54:38 +0000 | [diff] [blame] | 1364 | Applications that can't bear such ambiguities should avoid using hybrid |
| 1365 | \class{tzinfo} subclasses; there are no ambiguities when using UTC, or |
| 1366 | any other fixed-offset \class{tzinfo} subclass (such as a class |
| 1367 | representing only EST (fixed offset -5 hours), or only EDT (fixed offset |
| 1368 | -4 hours)). |
Tim Peters | adf6420 | 2003-01-04 06:03:15 +0000 | [diff] [blame] | 1369 | |
Andrew M. Kuchling | ca2623a | 2002-12-18 14:59:11 +0000 | [diff] [blame] | 1370 | |
Tim Peters | 29fb9c7 | 2002-12-23 22:21:52 +0000 | [diff] [blame] | 1371 | \subsection{\method{strftime()} Behavior} |
| 1372 | |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 1373 | \class{date}, \class{datetime}, and \class{time} |
| 1374 | objects all support a \code{strftime(\var{format})} |
Tim Peters | 29fb9c7 | 2002-12-23 22:21:52 +0000 | [diff] [blame] | 1375 | method, to create a string representing the time under the control of |
| 1376 | an explicit format string. Broadly speaking, |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 1377 | \code{d.strftime(fmt)} |
Tim Peters | 29fb9c7 | 2002-12-23 22:21:52 +0000 | [diff] [blame] | 1378 | acts like the \refmodule{time} module's |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 1379 | \code{time.strftime(fmt, d.timetuple())} |
Tim Peters | 29fb9c7 | 2002-12-23 22:21:52 +0000 | [diff] [blame] | 1380 | although not all objects support a \method{timetuple()} method. |
| 1381 | |
Tim Peters | 0037202 | 2003-01-09 04:10:05 +0000 | [diff] [blame] | 1382 | For \class{time} objects, the format codes for |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 1383 | year, month, and day should not be used, as time objects have no such |
| 1384 | values. If they're used anyway, \code{1900} is substituted for the |
| 1385 | year, and \code{0} for the month and day. |
Tim Peters | 29fb9c7 | 2002-12-23 22:21:52 +0000 | [diff] [blame] | 1386 | |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 1387 | For \class{date} objects, the format codes for hours, minutes, and |
| 1388 | seconds should not be used, as \class{date} objects have no such |
| 1389 | values. If they're used anyway, \code{0} is substituted for them. |
Tim Peters | 29fb9c7 | 2002-12-23 22:21:52 +0000 | [diff] [blame] | 1390 | |
Fred Drake | a37e5cc | 2002-12-30 21:26:42 +0000 | [diff] [blame] | 1391 | For a naive object, the \code{\%z} and \code{\%Z} format codes are |
Tim Peters | 29fb9c7 | 2002-12-23 22:21:52 +0000 | [diff] [blame] | 1392 | replaced by empty strings. |
| 1393 | |
| 1394 | For an aware object: |
| 1395 | |
| 1396 | \begin{itemize} |
| 1397 | \item[\code{\%z}] |
| 1398 | \method{utcoffset()} is transformed into a 5-character string of |
| 1399 | the form +HHMM or -HHMM, where HH is a 2-digit string giving the |
| 1400 | number of UTC offset hours, and MM is a 2-digit string giving the |
| 1401 | number of UTC offset minutes. For example, if |
Andrew M. Kuchling | c97868e | 2002-12-30 03:06:45 +0000 | [diff] [blame] | 1402 | \method{utcoffset()} returns \code{timedelta(hours=-3, minutes=-30)}, |
Tim Peters | 1cff9fc | 2002-12-24 16:25:29 +0000 | [diff] [blame] | 1403 | \code{\%z} is replaced with the string \code{'-0330'}. |
Tim Peters | 29fb9c7 | 2002-12-23 22:21:52 +0000 | [diff] [blame] | 1404 | |
| 1405 | \item[\code{\%Z}] |
| 1406 | If \method{tzname()} returns \code{None}, \code{\%Z} is replaced |
Andrew M. Kuchling | fa91858 | 2002-12-30 14:20:16 +0000 | [diff] [blame] | 1407 | by an empty string. Otherwise \code{\%Z} is replaced by the returned |
Tim Peters | 29fb9c7 | 2002-12-23 22:21:52 +0000 | [diff] [blame] | 1408 | value, which must be a string. |
| 1409 | \end{itemize} |
| 1410 | |
| 1411 | The full set of format codes supported varies across platforms, |
| 1412 | because Python calls the platform C library's \function{strftime()} |
| 1413 | function, and platform variations are common. The documentation for |
| 1414 | Python's \refmodule{time} module lists the format codes that the C |
| 1415 | standard (1989 version) requires, and those work on all platforms |
| 1416 | with a standard C implementation. Note that the 1999 version of the |
| 1417 | C standard added additional format codes. |
| 1418 | |
| 1419 | The exact range of years for which \method{strftime()} works also |
| 1420 | varies across platforms. Regardless of platform, years before 1900 |
| 1421 | cannot be used. |
Skip Montanaro | ef1b50d | 2005-12-06 21:00:47 +0000 | [diff] [blame] | 1422 | |
| 1423 | \subsection{Examples} |
| 1424 | |
| 1425 | \subsubsection{Creating Datetime Objects from Formatted Strings} |
| 1426 | |
| 1427 | The \class{datetime} class does not directly support parsing formatted time |
| 1428 | strings. You can use \function{time.strptime} to do the parsing and create |
| 1429 | a \class{datetime} object from the tuple it returns: |
| 1430 | |
| 1431 | \begin{verbatim} |
| 1432 | >>> s = "2005-12-06T12:13:14" |
| 1433 | >>> from datetime import datetime |
| 1434 | >>> from time import strptime |
| 1435 | >>> datetime(*strptime(s, "%Y-%m-%dT%H:%M:%S")[0:6]) |
| 1436 | datetime.datetime(2005, 12, 6, 12, 13, 14) |
| 1437 | \end{verbatim} |
| 1438 | |