Commit | Line | Data |
---|---|---|
920dae64 AT |
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> |