| 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 | <html> |
| 3 | <head> |
| 4 | <link rel="STYLESHEET" href="lib.css" type='text/css' /> |
| 5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> |
| 6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> |
| 7 | <link rel="first" href="lib.html" title='Python Library Reference' /> |
| 8 | <link rel='contents' href='contents.html' title="Contents" /> |
| 9 | <link rel='index' href='genindex.html' title='Index' /> |
| 10 | <link rel='last' href='about.html' title='About this document...' /> |
| 11 | <link rel='help' href='about.html' title='About this document...' /> |
| 12 | <link rel="next" href="datetime-time.html" /> |
| 13 | <link rel="prev" href="datetime-date.html" /> |
| 14 | <link rel="parent" href="module-datetime.html" /> |
| 15 | <link rel="next" href="datetime-time.html" /> |
| 16 | <meta name='aesop' content='information' /> |
| 17 | <title>6.10.4 datetime Objects </title> |
| 18 | </head> |
| 19 | <body> |
| 20 | <DIV CLASS="navigation"> |
| 21 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> |
| 22 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 23 | <tr> |
| 24 | <td class='online-navigation'><a rel="prev" title="6.10.3 date Objects" |
| 25 | href="datetime-date.html"><img src='../icons/previous.png' |
| 26 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 27 | <td class='online-navigation'><a rel="parent" title="6.10 datetime " |
| 28 | href="module-datetime.html"><img src='../icons/up.png' |
| 29 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 30 | <td class='online-navigation'><a rel="next" title="6.10.5 time Objects" |
| 31 | href="datetime-time.html"><img src='../icons/next.png' |
| 32 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 33 | <td align="center" width="100%">Python Library Reference</td> |
| 34 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 35 | href="contents.html"><img src='../icons/contents.png' |
| 36 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 37 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' |
| 38 | border='0' height='32' alt='Module Index' width='32' /></a></td> |
| 39 | <td class='online-navigation'><a rel="index" title="Index" |
| 40 | href="genindex.html"><img src='../icons/index.png' |
| 41 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 42 | </tr></table> |
| 43 | <div class='online-navigation'> |
| 44 | <b class="navlabel">Previous:</b> |
| 45 | <a class="sectref" rel="prev" href="datetime-date.html">6.10.3 date Objects</A> |
| 46 | <b class="navlabel">Up:</b> |
| 47 | <a class="sectref" rel="parent" href="module-datetime.html">6.10 datetime </A> |
| 48 | <b class="navlabel">Next:</b> |
| 49 | <a class="sectref" rel="next" href="datetime-time.html">6.10.5 time Objects</A> |
| 50 | </div> |
| 51 | <hr /></div> |
| 52 | </DIV> |
| 53 | <!--End of Navigation Panel--> |
| 54 | |
| 55 | <H2><A NAME="SECTION0081040000000000000000"></A><A NAME="datetime-datetime"></A> |
| 56 | <BR> |
| 57 | 6.10.4 <tt class="class">datetime</tt> Objects |
| 58 | </H2> |
| 59 | |
| 60 | <P> |
| 61 | A <tt class="class">datetime</tt> object is a single object containing all the |
| 62 | information from a <tt class="class">date</tt> object and a <tt class="class">time</tt> object. Like a |
| 63 | <tt class="class">date</tt> object, <tt class="class">datetime</tt> assumes the current Gregorian |
| 64 | calendar extended in both directions; like a time object, |
| 65 | <tt class="class">datetime</tt> assumes there are exactly 3600*24 seconds in every |
| 66 | day. |
| 67 | |
| 68 | <P> |
| 69 | Constructor: |
| 70 | |
| 71 | <P> |
| 72 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 73 | <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-1887' xml:id='l2h-1887' class="class">datetime</tt></b>(</nobr></td> |
| 74 | <td><var>year, month, day</var><big>[</big><var>, |
| 75 | hour</var><big>[</big><var>, minute</var><big>[</big><var>, |
| 76 | second</var><big>[</big><var>, microsecond</var><big>[</big><var>, |
| 77 | tzinfo</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> |
| 78 | <dd> |
| 79 | The year, month and day arguments are required. <var>tzinfo</var> may |
| 80 | be <code>None</code>, or an instance of a <tt class="class">tzinfo</tt> subclass. The |
| 81 | remaining arguments may be ints or longs, in the following ranges: |
| 82 | |
| 83 | <P> |
| 84 | |
| 85 | <UL> |
| 86 | <LI><code>MINYEAR <= <var>year</var> <= MAXYEAR</code> |
| 87 | </LI> |
| 88 | <LI><code>1 <= <var>month</var> <= 12</code> |
| 89 | </LI> |
| 90 | <LI><code>1 <= <var>day</var> <= number of days in the given month and year</code> |
| 91 | </LI> |
| 92 | <LI><code>0 <= <var>hour</var> < 24</code> |
| 93 | </LI> |
| 94 | <LI><code>0 <= <var>minute</var> < 60</code> |
| 95 | </LI> |
| 96 | <LI><code>0 <= <var>second</var> < 60</code> |
| 97 | </LI> |
| 98 | <LI><code>0 <= <var>microsecond</var> < 1000000</code> |
| 99 | |
| 100 | </LI> |
| 101 | </UL> |
| 102 | |
| 103 | <P> |
| 104 | If an argument outside those ranges is given, |
| 105 | <tt class="exception">ValueError</tt> is raised. |
| 106 | </dl> |
| 107 | |
| 108 | <P> |
| 109 | Other constructors, all class methods: |
| 110 | |
| 111 | <P> |
| 112 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 113 | <td><nobr><b><tt id='l2h-1888' xml:id='l2h-1888' class="method">today</tt></b>(</nobr></td> |
| 114 | <td><var></var>)</td></tr></table></dt> |
| 115 | <dd> |
| 116 | Return the current local datetime, with <tt class="member">tzinfo</tt> <code>None</code>. |
| 117 | This is equivalent to |
| 118 | <code>datetime.fromtimestamp(time.time())</code>. |
| 119 | See also <tt class="method">now()</tt>, <tt class="method">fromtimestamp()</tt>. |
| 120 | </dl> |
| 121 | |
| 122 | <P> |
| 123 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 124 | <td><nobr><b><tt id='l2h-1889' xml:id='l2h-1889' class="method">now</tt></b>(</nobr></td> |
| 125 | <td><var></var><big>[</big><var>tz</var><big>]</big><var></var>)</td></tr></table></dt> |
| 126 | <dd> |
| 127 | Return the current local date and time. If optional argument |
| 128 | <var>tz</var> is <code>None</code> or not specified, this is like |
| 129 | <tt class="method">today()</tt>, but, if possible, supplies more precision than can |
| 130 | be gotten from going through a <tt class="function">time.time()</tt> timestamp (for |
| 131 | example, this may be possible on platforms supplying the C |
| 132 | <tt class="cfunction">gettimeofday()</tt> function). |
| 133 | |
| 134 | <P> |
| 135 | Else <var>tz</var> must be an instance of a class <tt class="class">tzinfo</tt> subclass, |
| 136 | and the current date and time are converted to <var>tz</var>'s time |
| 137 | zone. In this case the result is equivalent to |
| 138 | <code><var>tz</var>.fromutc(datetime.utcnow().replace(tzinfo=<var>tz</var>))</code>. |
| 139 | See also <tt class="method">today()</tt>, <tt class="method">utcnow()</tt>. |
| 140 | </dl> |
| 141 | |
| 142 | <P> |
| 143 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 144 | <td><nobr><b><tt id='l2h-1890' xml:id='l2h-1890' class="method">utcnow</tt></b>(</nobr></td> |
| 145 | <td><var></var>)</td></tr></table></dt> |
| 146 | <dd> |
| 147 | Return the current UTC date and time, with <tt class="member">tzinfo</tt> <code>None</code>. |
| 148 | This is like <tt class="method">now()</tt>, but returns the current UTC date and time, |
| 149 | as a naive <tt class="class">datetime</tt> object. |
| 150 | See also <tt class="method">now()</tt>. |
| 151 | </dl> |
| 152 | |
| 153 | <P> |
| 154 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 155 | <td><nobr><b><tt id='l2h-1891' xml:id='l2h-1891' class="method">fromtimestamp</tt></b>(</nobr></td> |
| 156 | <td><var>timestamp</var><big>[</big><var>, tz</var><big>]</big><var></var>)</td></tr></table></dt> |
| 157 | <dd> |
| 158 | Return the local date and time corresponding to the POSIX |
| 159 | timestamp, such as is returned by <tt class="function">time.time()</tt>. |
| 160 | If optional argument <var>tz</var> is <code>None</code> or not specified, the |
| 161 | timestamp is converted to the platform's local date and time, and |
| 162 | the returned <tt class="class">datetime</tt> object is naive. |
| 163 | |
| 164 | <P> |
| 165 | Else <var>tz</var> must be an instance of a class <tt class="class">tzinfo</tt> subclass, |
| 166 | and the timestamp is converted to <var>tz</var>'s time zone. In this case |
| 167 | the result is equivalent to |
| 168 | <code><var>tz</var>.fromutc(datetime.utcfromtimestamp(<var>timestamp</var>).replace(tzinfo=<var>tz</var>))</code>. |
| 169 | |
| 170 | <P> |
| 171 | <tt class="method">fromtimestamp()</tt> may raise <tt class="exception">ValueError</tt>, if the |
| 172 | timestamp is out of the range of values supported by the platform C |
| 173 | <tt class="cfunction">localtime()</tt> or <tt class="cfunction">gmtime()</tt> functions. It's common |
| 174 | for this to be restricted to years in 1970 through 2038. |
| 175 | Note that on non-POSIX systems that include leap seconds in their |
| 176 | notion of a timestamp, leap seconds are ignored by |
| 177 | <tt class="method">fromtimestamp()</tt>, and then it's possible to have two timestamps |
| 178 | differing by a second that yield identical <tt class="class">datetime</tt> objects. |
| 179 | See also <tt class="method">utcfromtimestamp()</tt>. |
| 180 | </dl> |
| 181 | |
| 182 | <P> |
| 183 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 184 | <td><nobr><b><tt id='l2h-1892' xml:id='l2h-1892' class="method">utcfromtimestamp</tt></b>(</nobr></td> |
| 185 | <td><var>timestamp</var>)</td></tr></table></dt> |
| 186 | <dd> |
| 187 | Return the UTC <tt class="class">datetime</tt> corresponding to the POSIX |
| 188 | timestamp, with <tt class="member">tzinfo</tt> <code>None</code>. |
| 189 | This may raise <tt class="exception">ValueError</tt>, if the |
| 190 | timestamp is out of the range of values supported by the platform |
| 191 | C <tt class="cfunction">gmtime()</tt> function. It's common for this to be |
| 192 | restricted to years in 1970 through 2038. |
| 193 | See also <tt class="method">fromtimestamp()</tt>. |
| 194 | </dl> |
| 195 | |
| 196 | <P> |
| 197 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 198 | <td><nobr><b><tt id='l2h-1893' xml:id='l2h-1893' class="method">fromordinal</tt></b>(</nobr></td> |
| 199 | <td><var>ordinal</var>)</td></tr></table></dt> |
| 200 | <dd> |
| 201 | Return the <tt class="class">datetime</tt> corresponding to the proleptic |
| 202 | Gregorian ordinal, where January 1 of year 1 has ordinal 1. |
| 203 | <tt class="exception">ValueError</tt> is raised unless <code>1 <= ordinal <= |
| 204 | datetime.max.toordinal()</code>. The hour, minute, second and |
| 205 | microsecond of the result are all 0, |
| 206 | and <tt class="member">tzinfo</tt> is <code>None</code>. |
| 207 | </dl> |
| 208 | |
| 209 | <P> |
| 210 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 211 | <td><nobr><b><tt id='l2h-1894' xml:id='l2h-1894' class="method">combine</tt></b>(</nobr></td> |
| 212 | <td><var>date, time</var>)</td></tr></table></dt> |
| 213 | <dd> |
| 214 | Return a new <tt class="class">datetime</tt> object whose date members are |
| 215 | equal to the given <tt class="class">date</tt> object's, and whose time |
| 216 | and <tt class="member">tzinfo</tt> members are equal to the given <tt class="class">time</tt> object's. |
| 217 | For any <tt class="class">datetime</tt> object <var>d</var>, <code><var>d</var> == |
| 218 | datetime.combine(<var>d</var>.date(), <var>d</var>.timetz())</code>. If date is a |
| 219 | <tt class="class">datetime</tt> object, its time and <tt class="member">tzinfo</tt> members are |
| 220 | ignored. |
| 221 | </dl> |
| 222 | |
| 223 | <P> |
| 224 | Class attributes: |
| 225 | |
| 226 | <P> |
| 227 | <dl><dt><b><tt id='l2h-1895' xml:id='l2h-1895' class="member">min</tt></b></dt> |
| 228 | <dd> |
| 229 | The earliest representable <tt class="class">datetime</tt>, |
| 230 | <code>datetime(MINYEAR, 1, 1, tzinfo=None)</code>. |
| 231 | </dl> |
| 232 | |
| 233 | <P> |
| 234 | <dl><dt><b><tt id='l2h-1896' xml:id='l2h-1896' class="member">max</tt></b></dt> |
| 235 | <dd> |
| 236 | The latest representable <tt class="class">datetime</tt>, |
| 237 | <code>datetime(MAXYEAR, 12, 31, 23, 59, 59, 999999, tzinfo=None)</code>. |
| 238 | </dl> |
| 239 | |
| 240 | <P> |
| 241 | <dl><dt><b><tt id='l2h-1897' xml:id='l2h-1897' class="member">resolution</tt></b></dt> |
| 242 | <dd> |
| 243 | The smallest possible difference between non-equal <tt class="class">datetime</tt> |
| 244 | objects, <code>timedelta(microseconds=1)</code>. |
| 245 | </dl> |
| 246 | |
| 247 | <P> |
| 248 | Instance attributes (read-only): |
| 249 | |
| 250 | <P> |
| 251 | <dl><dt><b><tt id='l2h-1898' xml:id='l2h-1898' class="member">year</tt></b></dt> |
| 252 | <dd> |
| 253 | Between <tt class="constant">MINYEAR</tt> and <tt class="constant">MAXYEAR</tt> inclusive. |
| 254 | </dl> |
| 255 | |
| 256 | <P> |
| 257 | <dl><dt><b><tt id='l2h-1899' xml:id='l2h-1899' class="member">month</tt></b></dt> |
| 258 | <dd> |
| 259 | Between 1 and 12 inclusive. |
| 260 | </dl> |
| 261 | |
| 262 | <P> |
| 263 | <dl><dt><b><tt id='l2h-1900' xml:id='l2h-1900' class="member">day</tt></b></dt> |
| 264 | <dd> |
| 265 | Between 1 and the number of days in the given month of the given |
| 266 | year. |
| 267 | </dl> |
| 268 | |
| 269 | <P> |
| 270 | <dl><dt><b><tt id='l2h-1901' xml:id='l2h-1901' class="member">hour</tt></b></dt> |
| 271 | <dd> |
| 272 | In <code>range(24)</code>. |
| 273 | </dl> |
| 274 | |
| 275 | <P> |
| 276 | <dl><dt><b><tt id='l2h-1902' xml:id='l2h-1902' class="member">minute</tt></b></dt> |
| 277 | <dd> |
| 278 | In <code>range(60)</code>. |
| 279 | </dl> |
| 280 | |
| 281 | <P> |
| 282 | <dl><dt><b><tt id='l2h-1903' xml:id='l2h-1903' class="member">second</tt></b></dt> |
| 283 | <dd> |
| 284 | In <code>range(60)</code>. |
| 285 | </dl> |
| 286 | |
| 287 | <P> |
| 288 | <dl><dt><b><tt id='l2h-1904' xml:id='l2h-1904' class="member">microsecond</tt></b></dt> |
| 289 | <dd> |
| 290 | In <code>range(1000000)</code>. |
| 291 | </dl> |
| 292 | |
| 293 | <P> |
| 294 | <dl><dt><b><tt id='l2h-1905' xml:id='l2h-1905' class="member">tzinfo</tt></b></dt> |
| 295 | <dd> |
| 296 | The object passed as the <var>tzinfo</var> argument to the |
| 297 | <tt class="class">datetime</tt> constructor, or <code>None</code> if none was passed. |
| 298 | </dl> |
| 299 | |
| 300 | <P> |
| 301 | Supported operations: |
| 302 | |
| 303 | <P> |
| 304 | <div class="center"><table class="realtable"> |
| 305 | <thead> |
| 306 | <tr> |
| 307 | <th class="center">Operation</th> |
| 308 | <th class="left" >Result</th> |
| 309 | </tr> |
| 310 | </thead> |
| 311 | <tbody> |
| 312 | <tr><td class="center" valign="baseline"><code><var>datetime2</var> = <var>datetime1</var> + <var>timedelta</var></code></td> |
| 313 | <td class="left" >(1)</td></tr><P> |
| 314 | |
| 315 | <tr><td class="center" valign="baseline"><code><var>datetime2</var> = <var>datetime1</var> - <var>timedelta</var></code></td> |
| 316 | <td class="left" >(2)</td></tr><P> |
| 317 | |
| 318 | <tr><td class="center" valign="baseline"><code><var>timedelta</var> = <var>datetime1</var> - <var>datetime2</var></code></td> |
| 319 | <td class="left" >(3)</td></tr><P> |
| 320 | |
| 321 | <tr><td class="center" valign="baseline"><code><var>datetime1</var> < <var>datetime2</var></code></td> |
| 322 | <td class="left" >Compares <tt class="class">datetime</tt> to <tt class="class">datetime</tt>. |
| 323 | (4)</td></tr><P> |
| 324 | |
| 325 | </tbody> |
| 326 | </table></div> |
| 327 | |
| 328 | <P> |
| 329 | <DL> |
| 330 | <DT><STRONG>(1)</STRONG></DT> |
| 331 | <DD><P> |
| 332 | datetime2 is a duration of timedelta removed from datetime1, moving |
| 333 | forward in time if <code><var>timedelta</var>.days</code> > 0, or backward if |
| 334 | <code><var>timedelta</var>.days</code> < 0. The result has the same <tt class="member">tzinfo</tt> member |
| 335 | as the input datetime, and datetime2 - datetime1 == timedelta after. |
| 336 | <tt class="exception">OverflowError</tt> is raised if datetime2.year would be |
| 337 | smaller than <tt class="constant">MINYEAR</tt> or larger than <tt class="constant">MAXYEAR</tt>. |
| 338 | Note that no time zone adjustments are done even if the input is an |
| 339 | aware object. |
| 340 | |
| 341 | <P> |
| 342 | </DD> |
| 343 | <DT><STRONG>(2)</STRONG></DT> |
| 344 | <DD>Computes the datetime2 such that datetime2 + timedelta == datetime1. |
| 345 | As for addition, the result has the same <tt class="member">tzinfo</tt> member |
| 346 | as the input datetime, and no time zone adjustments are done even |
| 347 | if the input is aware. |
| 348 | This isn't quite equivalent to datetime1 + (-timedelta), because |
| 349 | -timedelta in isolation can overflow in cases where |
| 350 | datetime1 - timedelta does not. |
| 351 | |
| 352 | <P> |
| 353 | </DD> |
| 354 | <DT><STRONG>(3)</STRONG></DT> |
| 355 | <DD>Subtraction of a <tt class="class">datetime</tt> from a |
| 356 | <tt class="class">datetime</tt> is defined only if both |
| 357 | operands are naive, or if both are aware. If one is aware and the |
| 358 | other is naive, <tt class="exception">TypeError</tt> is raised. |
| 359 | |
| 360 | <P> |
| 361 | If both are naive, or both are aware and have the same <tt class="member">tzinfo</tt> |
| 362 | member, the <tt class="member">tzinfo</tt> members are ignored, and the result is |
| 363 | a <tt class="class">timedelta</tt> object <var>t</var> such that |
| 364 | <code><var>datetime2</var> + <var>t</var> == <var>datetime1</var></code>. No time zone |
| 365 | adjustments are done in this case. |
| 366 | |
| 367 | <P> |
| 368 | If both are aware and have different <tt class="member">tzinfo</tt> members, |
| 369 | <code>a-b</code> acts as if <var>a</var> and <var>b</var> were first converted to |
| 370 | naive UTC datetimes first. The result is |
| 371 | <code>(<var>a</var>.replace(tzinfo=None) - <var>a</var>.utcoffset()) - |
| 372 | (<var>b</var>.replace(tzinfo=None) - <var>b</var>.utcoffset())</code> |
| 373 | except that the implementation never overflows. |
| 374 | |
| 375 | <P> |
| 376 | </DD> |
| 377 | <DT><STRONG>(4)</STRONG></DT> |
| 378 | <DD><P> |
| 379 | <var>datetime1</var> is considered less than <var>datetime2</var> |
| 380 | when <var>datetime1</var> precedes <var>datetime2</var> in time. |
| 381 | |
| 382 | <P> |
| 383 | If one comparand is naive and |
| 384 | the other is aware, <tt class="exception">TypeError</tt> is raised. If both |
| 385 | comparands are aware, and have the same <tt class="member">tzinfo</tt> member, |
| 386 | the common <tt class="member">tzinfo</tt> member is ignored and the base datetimes |
| 387 | are compared. If both comparands are aware and have different |
| 388 | <tt class="member">tzinfo</tt> members, the comparands are first adjusted by |
| 389 | subtracting their UTC offsets (obtained from <code>self.utcoffset()</code>). |
| 390 | <span class="note"><b class="label">Note:</b> |
| 391 | In order to stop comparison from falling back to the default |
| 392 | scheme of comparing object addresses, datetime comparison |
| 393 | normally raises <tt class="exception">TypeError</tt> if the other comparand |
| 394 | isn't also a <tt class="class">datetime</tt> object. However, |
| 395 | <code>NotImplemented</code> is returned instead if the other comparand |
| 396 | has a <tt class="method">timetuple</tt> attribute. This hook gives other |
| 397 | kinds of date objects a chance at implementing mixed-type |
| 398 | comparison. If not, when a <tt class="class">datetime</tt> object is |
| 399 | compared to an object of a different type, <tt class="exception">TypeError</tt> |
| 400 | is raised unless the comparison is <code>==</code> or <code>!=</code>. The |
| 401 | latter cases return <tt class="constant">False</tt> or <tt class="constant">True</tt>, |
| 402 | respectively.</span> |
| 403 | |
| 404 | <P> |
| 405 | </DD> |
| 406 | </DL> |
| 407 | |
| 408 | <P> |
| 409 | <tt class="class">datetime</tt> objects can be used as dictionary keys. In Boolean |
| 410 | contexts, all <tt class="class">datetime</tt> objects are considered to be true. |
| 411 | |
| 412 | <P> |
| 413 | Instance methods: |
| 414 | |
| 415 | <P> |
| 416 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 417 | <td><nobr><b><tt id='l2h-1906' xml:id='l2h-1906' class="method">date</tt></b>(</nobr></td> |
| 418 | <td><var></var>)</td></tr></table></dt> |
| 419 | <dd> |
| 420 | Return <tt class="class">date</tt> object with same year, month and day. |
| 421 | </dl> |
| 422 | |
| 423 | <P> |
| 424 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 425 | <td><nobr><b><tt id='l2h-1907' xml:id='l2h-1907' class="method">time</tt></b>(</nobr></td> |
| 426 | <td><var></var>)</td></tr></table></dt> |
| 427 | <dd> |
| 428 | Return <tt class="class">time</tt> object with same hour, minute, second and microsecond. |
| 429 | <tt class="member">tzinfo</tt> is <code>None</code>. See also method <tt class="method">timetz()</tt>. |
| 430 | </dl> |
| 431 | |
| 432 | <P> |
| 433 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 434 | <td><nobr><b><tt id='l2h-1908' xml:id='l2h-1908' class="method">timetz</tt></b>(</nobr></td> |
| 435 | <td><var></var>)</td></tr></table></dt> |
| 436 | <dd> |
| 437 | Return <tt class="class">time</tt> object with same hour, minute, second, microsecond, |
| 438 | and tzinfo members. See also method <tt class="method">time()</tt>. |
| 439 | </dl> |
| 440 | |
| 441 | <P> |
| 442 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 443 | <td><nobr><b><tt id='l2h-1909' xml:id='l2h-1909' class="method">replace</tt></b>(</nobr></td> |
| 444 | <td><var></var><big>[</big><var>year</var><big>[</big><var>, month</var><big>[</big><var>, |
| 445 | day</var><big>[</big><var>, hour</var><big>[</big><var>, minute</var><big>[</big><var>, |
| 446 | second</var><big>[</big><var>, microsecond</var><big>[</big><var>, |
| 447 | tzinfo</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> |
| 448 | <dd> |
| 449 | Return a datetime with the same members, except for those members given |
| 450 | new values by whichever keyword arguments are specified. Note that |
| 451 | <code>tzinfo=None</code> can be specified to create a naive datetime from |
| 452 | an aware datetime with no conversion of date and time members. |
| 453 | </dl> |
| 454 | |
| 455 | <P> |
| 456 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 457 | <td><nobr><b><tt id='l2h-1910' xml:id='l2h-1910' class="method">astimezone</tt></b>(</nobr></td> |
| 458 | <td><var>tz</var>)</td></tr></table></dt> |
| 459 | <dd> |
| 460 | Return a <tt class="class">datetime</tt> object with new <tt class="member">tzinfo</tt> member |
| 461 | <var>tz</var>, adjusting the date and time members so the result is the |
| 462 | same UTC time as <var>self</var>, but in <var>tz</var>'s local time. |
| 463 | |
| 464 | <P> |
| 465 | <var>tz</var> must be an instance of a <tt class="class">tzinfo</tt> subclass, and its |
| 466 | <tt class="method">utcoffset()</tt> and <tt class="method">dst()</tt> methods must not return |
| 467 | <code>None</code>. <var>self</var> must be aware (<code><var>self</var>.tzinfo</code> must |
| 468 | not be <code>None</code>, and <code><var>self</var>.utcoffset()</code> must not return |
| 469 | <code>None</code>). |
| 470 | |
| 471 | <P> |
| 472 | If <code><var>self</var>.tzinfo</code> is <var>tz</var>, |
| 473 | <code><var>self</var>.astimezone(<var>tz</var>)</code> is equal to <var>self</var>: no |
| 474 | adjustment of date or time members is performed. |
| 475 | Else the result is local time in time zone <var>tz</var>, representing the |
| 476 | same UTC time as <var>self</var>: after <code><var>astz</var> = |
| 477 | <var>dt</var>.astimezone(<var>tz</var>)</code>, |
| 478 | <code><var>astz</var> - <var>astz</var>.utcoffset()</code> will usually have the same |
| 479 | date and time members as <code><var>dt</var> - <var>dt</var>.utcoffset()</code>. |
| 480 | The discussion of class <tt class="class">tzinfo</tt> explains the cases at Daylight |
| 481 | Saving Time transition boundaries where this cannot be achieved (an issue |
| 482 | only if <var>tz</var> models both standard and daylight time). |
| 483 | |
| 484 | <P> |
| 485 | If you merely want to attach a time zone object <var>tz</var> to a |
| 486 | datetime <var>dt</var> without adjustment of date and time members, |
| 487 | use <code><var>dt</var>.replace(tzinfo=<var>tz</var>)</code>. If |
| 488 | you merely want to remove the time zone object from an aware datetime |
| 489 | <var>dt</var> without conversion of date and time members, use |
| 490 | <code><var>dt</var>.replace(tzinfo=None)</code>. |
| 491 | |
| 492 | <P> |
| 493 | Note that the default <tt class="method">tzinfo.fromutc()</tt> method can be overridden |
| 494 | in a <tt class="class">tzinfo</tt> subclass to affect the result returned by |
| 495 | <tt class="method">astimezone()</tt>. Ignoring error cases, <tt class="method">astimezone()</tt> |
| 496 | acts like: |
| 497 | |
| 498 | <P> |
| 499 | <div class="verbatim"><pre> |
| 500 | def astimezone(self, tz): |
| 501 | if self.tzinfo is tz: |
| 502 | return self |
| 503 | # Convert self to UTC, and attach the new time zone object. |
| 504 | utc = (self - self.utcoffset()).replace(tzinfo=tz) |
| 505 | # Convert from UTC to tz's local time. |
| 506 | return tz.fromutc(utc) |
| 507 | </pre></div> |
| 508 | </dl> |
| 509 | |
| 510 | <P> |
| 511 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 512 | <td><nobr><b><tt id='l2h-1911' xml:id='l2h-1911' class="method">utcoffset</tt></b>(</nobr></td> |
| 513 | <td><var></var>)</td></tr></table></dt> |
| 514 | <dd> |
| 515 | If <tt class="member">tzinfo</tt> is <code>None</code>, returns <code>None</code>, else |
| 516 | returns <code><var>self</var>.tzinfo.utcoffset(<var>self</var>)</code>, and |
| 517 | raises an exception if the latter doesn't return <code>None</code>, or |
| 518 | a <tt class="class">timedelta</tt> object representing a whole number of minutes |
| 519 | with magnitude less than one day. |
| 520 | </dl> |
| 521 | |
| 522 | <P> |
| 523 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 524 | <td><nobr><b><tt id='l2h-1912' xml:id='l2h-1912' class="method">dst</tt></b>(</nobr></td> |
| 525 | <td><var></var>)</td></tr></table></dt> |
| 526 | <dd> |
| 527 | If <tt class="member">tzinfo</tt> is <code>None</code>, returns <code>None</code>, else |
| 528 | returns <code><var>self</var>.tzinfo.dst(<var>self</var>)</code>, and |
| 529 | raises an exception if the latter doesn't return <code>None</code>, or |
| 530 | a <tt class="class">timedelta</tt> object representing a whole number of minutes |
| 531 | with magnitude less than one day. |
| 532 | </dl> |
| 533 | |
| 534 | <P> |
| 535 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 536 | <td><nobr><b><tt id='l2h-1913' xml:id='l2h-1913' class="method">tzname</tt></b>(</nobr></td> |
| 537 | <td><var></var>)</td></tr></table></dt> |
| 538 | <dd> |
| 539 | If <tt class="member">tzinfo</tt> is <code>None</code>, returns <code>None</code>, else |
| 540 | returns <code><var>self</var>.tzinfo.tzname(<var>self</var>)</code>, |
| 541 | raises an exception if the latter doesn't return <code>None</code> or |
| 542 | a string object, |
| 543 | </dl> |
| 544 | |
| 545 | <P> |
| 546 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 547 | <td><nobr><b><tt id='l2h-1914' xml:id='l2h-1914' class="method">timetuple</tt></b>(</nobr></td> |
| 548 | <td><var></var>)</td></tr></table></dt> |
| 549 | <dd> |
| 550 | Return a <tt class="class">time.struct_time</tt> such as returned by |
| 551 | <tt class="function">time.localtime()</tt>. |
| 552 | <code><var>d</var>.timetuple()</code> is equivalent to |
| 553 | <code>time.struct_time((<var>d</var>.year, <var>d</var>.month, <var>d</var>.day, |
| 554 | <var>d</var>.hour, <var>d</var>.minute, <var>d</var>.second, |
| 555 | <var>d</var>.weekday(), |
| 556 | <var>d</var>.toordinal() - date(<var>d</var>.year, 1, 1).toordinal() + 1, |
| 557 | dst))</code> |
| 558 | The <tt class="member">tm_isdst</tt> flag of the result is set according to |
| 559 | the <tt class="method">dst()</tt> method: <tt class="member">tzinfo</tt> is <code>None</code> or |
| 560 | <tt class="method">dst()</tt> returns <code>None</code>, |
| 561 | <tt class="member">tm_isdst</tt> is set to <code>-1</code>; else if <tt class="method">dst()</tt> returns |
| 562 | a non-zero value, <tt class="member">tm_isdst</tt> is set to <code>1</code>; |
| 563 | else <code>tm_isdst</code> is set to <code>0</code>. |
| 564 | </dl> |
| 565 | |
| 566 | <P> |
| 567 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 568 | <td><nobr><b><tt id='l2h-1915' xml:id='l2h-1915' class="method">utctimetuple</tt></b>(</nobr></td> |
| 569 | <td><var></var>)</td></tr></table></dt> |
| 570 | <dd> |
| 571 | If <tt class="class">datetime</tt> instance <var>d</var> is naive, this is the same as |
| 572 | <code><var>d</var>.timetuple()</code> except that <tt class="member">tm_isdst</tt> is forced to 0 |
| 573 | regardless of what <code>d.dst()</code> returns. DST is never in effect |
| 574 | for a UTC time. |
| 575 | |
| 576 | <P> |
| 577 | If <var>d</var> is aware, <var>d</var> is normalized to UTC time, by subtracting |
| 578 | <code><var>d</var>.utcoffset()</code>, and a <tt class="class">time.struct_time</tt> for the |
| 579 | normalized time is returned. <tt class="member">tm_isdst</tt> is forced to 0. |
| 580 | Note that the result's <tt class="member">tm_year</tt> member may be |
| 581 | <tt class="constant">MINYEAR</tt>-1 or <tt class="constant">MAXYEAR</tt>+1, if <var>d</var>.year was |
| 582 | <code>MINYEAR</code> or <code>MAXYEAR</code> and UTC adjustment spills over a |
| 583 | year boundary. |
| 584 | </dl> |
| 585 | |
| 586 | <P> |
| 587 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 588 | <td><nobr><b><tt id='l2h-1916' xml:id='l2h-1916' class="method">toordinal</tt></b>(</nobr></td> |
| 589 | <td><var></var>)</td></tr></table></dt> |
| 590 | <dd> |
| 591 | Return the proleptic Gregorian ordinal of the date. The same as |
| 592 | <code>self.date().toordinal()</code>. |
| 593 | </dl> |
| 594 | |
| 595 | <P> |
| 596 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 597 | <td><nobr><b><tt id='l2h-1917' xml:id='l2h-1917' class="method">weekday</tt></b>(</nobr></td> |
| 598 | <td><var></var>)</td></tr></table></dt> |
| 599 | <dd> |
| 600 | Return the day of the week as an integer, where Monday is 0 and |
| 601 | Sunday is 6. The same as <code>self.date().weekday()</code>. |
| 602 | See also <tt class="method">isoweekday()</tt>. |
| 603 | </dl> |
| 604 | |
| 605 | <P> |
| 606 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 607 | <td><nobr><b><tt id='l2h-1918' xml:id='l2h-1918' class="method">isoweekday</tt></b>(</nobr></td> |
| 608 | <td><var></var>)</td></tr></table></dt> |
| 609 | <dd> |
| 610 | Return the day of the week as an integer, where Monday is 1 and |
| 611 | Sunday is 7. The same as <code>self.date().isoweekday()</code>. |
| 612 | See also <tt class="method">weekday()</tt>, <tt class="method">isocalendar()</tt>. |
| 613 | </dl> |
| 614 | |
| 615 | <P> |
| 616 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 617 | <td><nobr><b><tt id='l2h-1919' xml:id='l2h-1919' class="method">isocalendar</tt></b>(</nobr></td> |
| 618 | <td><var></var>)</td></tr></table></dt> |
| 619 | <dd> |
| 620 | Return a 3-tuple, (ISO year, ISO week number, ISO weekday). The |
| 621 | same as <code>self.date().isocalendar()</code>. |
| 622 | </dl> |
| 623 | |
| 624 | <P> |
| 625 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 626 | <td><nobr><b><tt id='l2h-1920' xml:id='l2h-1920' class="method">isoformat</tt></b>(</nobr></td> |
| 627 | <td><var></var><big>[</big><var>sep</var><big>]</big><var></var>)</td></tr></table></dt> |
| 628 | <dd> |
| 629 | Return a string representing the date and time in ISO 8601 format, |
| 630 | YYYY-MM-DDTHH:MM:SS.mmmmmm |
| 631 | or, if <tt class="member">microsecond</tt> is 0, |
| 632 | YYYY-MM-DDTHH:MM:SS |
| 633 | |
| 634 | <P> |
| 635 | If <tt class="method">utcoffset()</tt> does not return <code>None</code>, a 6-character |
| 636 | string is appended, giving the UTC offset in (signed) hours and |
| 637 | minutes: |
| 638 | YYYY-MM-DDTHH:MM:SS.mmmmmm+HH:MM |
| 639 | or, if <tt class="member">microsecond</tt> is 0 |
| 640 | YYYY-MM-DDTHH:MM:SS+HH:MM |
| 641 | |
| 642 | <P> |
| 643 | The optional argument <var>sep</var> (default <code>'T'</code>) is a |
| 644 | one-character separator, placed between the date and time portions |
| 645 | of the result. For example, |
| 646 | |
| 647 | <P> |
| 648 | <div class="verbatim"><pre> |
| 649 | >>> from datetime import tzinfo, timedelta, datetime |
| 650 | >>> class TZ(tzinfo): |
| 651 | ... def utcoffset(self, dt): return timedelta(minutes=-399) |
| 652 | ... |
| 653 | >>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ') |
| 654 | '2002-12-25 00:00:00-06:39' |
| 655 | </pre></div> |
| 656 | </dl> |
| 657 | |
| 658 | <P> |
| 659 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 660 | <td><nobr><b><tt id='l2h-1921' xml:id='l2h-1921' class="method">__str__</tt></b>(</nobr></td> |
| 661 | <td><var></var>)</td></tr></table></dt> |
| 662 | <dd> |
| 663 | For a <tt class="class">datetime</tt> instance <var>d</var>, <code>str(<var>d</var>)</code> is |
| 664 | equivalent to <code><var>d</var>.isoformat(' ')</code>. |
| 665 | </dl> |
| 666 | |
| 667 | <P> |
| 668 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 669 | <td><nobr><b><tt id='l2h-1922' xml:id='l2h-1922' class="method">ctime</tt></b>(</nobr></td> |
| 670 | <td><var></var>)</td></tr></table></dt> |
| 671 | <dd> |
| 672 | Return a string representing the date and time, for example |
| 673 | <code>datetime(2002, 12, 4, 20, 30, 40).ctime() == |
| 674 | 'Wed Dec 4 20:30:40 2002'</code>. |
| 675 | <code>d.ctime()</code> is equivalent to |
| 676 | <code>time.ctime(time.mktime(d.timetuple()))</code> on platforms where |
| 677 | the native C <tt class="cfunction">ctime()</tt> function (which |
| 678 | <tt class="function">time.ctime()</tt> invokes, but which |
| 679 | <tt class="method">datetime.ctime()</tt> does not invoke) conforms to the C |
| 680 | standard. |
| 681 | </dl> |
| 682 | |
| 683 | <P> |
| 684 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 685 | <td><nobr><b><tt id='l2h-1923' xml:id='l2h-1923' class="method">strftime</tt></b>(</nobr></td> |
| 686 | <td><var>format</var>)</td></tr></table></dt> |
| 687 | <dd> |
| 688 | Return a string representing the date and time, controlled by an |
| 689 | explicit format string. See the section on <tt class="method">strftime()</tt> |
| 690 | behavior. |
| 691 | </dl> |
| 692 | |
| 693 | <P> |
| 694 | |
| 695 | <DIV CLASS="navigation"> |
| 696 | <div class='online-navigation'> |
| 697 | <p></p><hr /> |
| 698 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 699 | <tr> |
| 700 | <td class='online-navigation'><a rel="prev" title="6.10.3 date Objects" |
| 701 | href="datetime-date.html"><img src='../icons/previous.png' |
| 702 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 703 | <td class='online-navigation'><a rel="parent" title="6.10 datetime " |
| 704 | href="module-datetime.html"><img src='../icons/up.png' |
| 705 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 706 | <td class='online-navigation'><a rel="next" title="6.10.5 time Objects" |
| 707 | href="datetime-time.html"><img src='../icons/next.png' |
| 708 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 709 | <td align="center" width="100%">Python Library Reference</td> |
| 710 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 711 | href="contents.html"><img src='../icons/contents.png' |
| 712 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 713 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' |
| 714 | border='0' height='32' alt='Module Index' width='32' /></a></td> |
| 715 | <td class='online-navigation'><a rel="index" title="Index" |
| 716 | href="genindex.html"><img src='../icons/index.png' |
| 717 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 718 | </tr></table> |
| 719 | <div class='online-navigation'> |
| 720 | <b class="navlabel">Previous:</b> |
| 721 | <a class="sectref" rel="prev" href="datetime-date.html">6.10.3 date Objects</A> |
| 722 | <b class="navlabel">Up:</b> |
| 723 | <a class="sectref" rel="parent" href="module-datetime.html">6.10 datetime </A> |
| 724 | <b class="navlabel">Next:</b> |
| 725 | <a class="sectref" rel="next" href="datetime-time.html">6.10.5 time Objects</A> |
| 726 | </div> |
| 727 | </div> |
| 728 | <hr /> |
| 729 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> |
| 730 | </DIV> |
| 731 | <!--End of Navigation Panel--> |
| 732 | <ADDRESS> |
| 733 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. |
| 734 | </ADDRESS> |
| 735 | </BODY> |
| 736 | </HTML> |