source: python/trunk/Doc/library/time.rst

Last change on this file was 391, checked in by dmik, 11 years ago

python: Merge vendor 2.7.6 to trunk.
  • Property svn:eol-style set to native
File size: 24.9 KB
RevLine 
[2]1
2:mod:`time` --- Time access and conversions
3===========================================
4
5.. module:: time
6 :synopsis: Time access and conversions.
7
8
9This module provides various time-related functions. For related
10functionality, see also the :mod:`datetime` and :mod:`calendar` modules.
11
12Although this module is always available,
13not all functions are available on all platforms. Most of the functions
14defined in this module call platform C library functions with the same name. It
15may sometimes be helpful to consult the platform documentation, because the
16semantics of these functions varies among platforms.
17
18An explanation of some terminology and conventions is in order.
19
[391]20.. index:: single: epoch
[2]21
22* The :dfn:`epoch` is the point where the time starts. On January 1st of that
23 year, at 0 hours, the "time since the epoch" is zero. For Unix, the epoch is
24 1970. To find out what the epoch is, look at ``gmtime(0)``.
25
[391]26.. index:: single: Year 2038
[2]27
28* The functions in this module do not handle dates and times before the epoch or
29 far in the future. The cut-off point in the future is determined by the C
30 library; for Unix, it is typically in 2038.
31
[391]32.. index::
33 single: Year 2000
34 single: Y2K
[2]35
[391]36.. _time-y2kissues:
37
[2]38* **Year 2000 (Y2K) issues**: Python depends on the platform's C library, which
39 generally doesn't have year 2000 issues, since all dates and times are
40 represented internally as seconds since the epoch. Functions accepting a
41 :class:`struct_time` (see below) generally require a 4-digit year. For backward
42 compatibility, 2-digit years are supported if the module variable
43 ``accept2dyear`` is a non-zero integer; this variable is initialized to ``1``
44 unless the environment variable :envvar:`PYTHONY2K` is set to a non-empty
45 string, in which case it is initialized to ``0``. Thus, you can set
46 :envvar:`PYTHONY2K` to a non-empty string in the environment to require 4-digit
47 years for all year input. When 2-digit years are accepted, they are converted
48 according to the POSIX or X/Open standard: values 69-99 are mapped to 1969-1999,
49 and values 0--68 are mapped to 2000--2068. Values 100--1899 are always illegal.
50 Note that this is new as of Python 1.5.2(a2); earlier versions, up to Python
51 1.5.1 and 1.5.2a1, would add 1900 to year values below 1900.
52
[391]53.. index::
54 single: UTC
55 single: Coordinated Universal Time
56 single: Greenwich Mean Time
[2]57
58* UTC is Coordinated Universal Time (formerly known as Greenwich Mean Time, or
59 GMT). The acronym UTC is not a mistake but a compromise between English and
60 French.
61
[391]62.. index:: single: Daylight Saving Time
[2]63
64* DST is Daylight Saving Time, an adjustment of the timezone by (usually) one
65 hour during part of the year. DST rules are magic (determined by local law) and
66 can change from year to year. The C library has a table containing the local
67 rules (often it is read from a system file for flexibility) and is the only
68 source of True Wisdom in this respect.
69
70* The precision of the various real-time functions may be less than suggested by
71 the units in which their value or argument is expressed. E.g. on most Unix
72 systems, the clock "ticks" only 50 or 100 times a second.
73
[391]74* On the other hand, the precision of :func:`.time` and :func:`sleep` is better
[2]75 than their Unix equivalents: times are expressed as floating point numbers,
[391]76 :func:`.time` returns the most accurate time available (using Unix
77 :c:func:`gettimeofday` where available), and :func:`sleep` will accept a time
78 with a nonzero fraction (Unix :c:func:`select` is used to implement this, where
[2]79 available).
80
81* The time value as returned by :func:`gmtime`, :func:`localtime`, and
82 :func:`strptime`, and accepted by :func:`asctime`, :func:`mktime` and
83 :func:`strftime`, may be considered as a sequence of 9 integers. The return
84 values of :func:`gmtime`, :func:`localtime`, and :func:`strptime` also offer
85 attribute names for individual fields.
86
[391]87 See :class:`struct_time` for a description of these objects.
[2]88
89 .. versionchanged:: 2.2
90 The time value sequence was changed from a tuple to a :class:`struct_time`, with
91 the addition of attribute names for the fields.
92
93* Use the following functions to convert between time representations:
94
95 +-------------------------+-------------------------+-------------------------+
96 | From | To | Use |
97 +=========================+=========================+=========================+
98 | seconds since the epoch | :class:`struct_time` in | :func:`gmtime` |
99 | | UTC | |
100 +-------------------------+-------------------------+-------------------------+
101 | seconds since the epoch | :class:`struct_time` in | :func:`localtime` |
102 | | local time | |
103 +-------------------------+-------------------------+-------------------------+
104 | :class:`struct_time` in | seconds since the epoch | :func:`calendar.timegm` |
105 | UTC | | |
106 +-------------------------+-------------------------+-------------------------+
107 | :class:`struct_time` in | seconds since the epoch | :func:`mktime` |
108 | local time | | |
109 +-------------------------+-------------------------+-------------------------+
110
111
112The module defines the following functions and data items:
113
114.. data:: accept2dyear
115
116 Boolean value indicating whether two-digit year values will be accepted. This
117 is true by default, but will be set to false if the environment variable
118 :envvar:`PYTHONY2K` has been set to a non-empty string. It may also be modified
119 at run time.
120
121
122.. data:: altzone
123
124 The offset of the local DST timezone, in seconds west of UTC, if one is defined.
125 This is negative if the local DST timezone is east of UTC (as in Western Europe,
126 including the UK). Only use this if ``daylight`` is nonzero.
127
128
129.. function:: asctime([t])
130
131 Convert a tuple or :class:`struct_time` representing a time as returned by
132 :func:`gmtime` or :func:`localtime` to a 24-character string of the following
133 form: ``'Sun Jun 20 23:21:05 1993'``. If *t* is not provided, the current time
134 as returned by :func:`localtime` is used. Locale information is not used by
135 :func:`asctime`.
136
137 .. note::
138
139 Unlike the C function of the same name, there is no trailing newline.
140
141 .. versionchanged:: 2.1
142 Allowed *t* to be omitted.
143
144
145.. function:: clock()
146
147 .. index::
148 single: CPU time
149 single: processor time
150 single: benchmarking
151
152 On Unix, return the current processor time as a floating point number expressed
153 in seconds. The precision, and in fact the very definition of the meaning of
154 "processor time", depends on that of the C function of the same name, but in any
155 case, this is the function to use for benchmarking Python or timing algorithms.
156
157 On Windows, this function returns wall-clock seconds elapsed since the first
158 call to this function, as a floating point number, based on the Win32 function
[391]159 :c:func:`QueryPerformanceCounter`. The resolution is typically better than one
[2]160 microsecond.
161
162
163.. function:: ctime([secs])
164
165 Convert a time expressed in seconds since the epoch to a string representing
166 local time. If *secs* is not provided or :const:`None`, the current time as
[391]167 returned by :func:`.time` is used. ``ctime(secs)`` is equivalent to
[2]168 ``asctime(localtime(secs))``. Locale information is not used by :func:`ctime`.
169
170 .. versionchanged:: 2.1
171 Allowed *secs* to be omitted.
172
173 .. versionchanged:: 2.4
174 If *secs* is :const:`None`, the current time is used.
175
176
177.. data:: daylight
178
179 Nonzero if a DST timezone is defined.
180
181
182.. function:: gmtime([secs])
183
184 Convert a time expressed in seconds since the epoch to a :class:`struct_time` in
185 UTC in which the dst flag is always zero. If *secs* is not provided or
[391]186 :const:`None`, the current time as returned by :func:`.time` is used. Fractions
[2]187 of a second are ignored. See above for a description of the
188 :class:`struct_time` object. See :func:`calendar.timegm` for the inverse of this
189 function.
190
191 .. versionchanged:: 2.1
192 Allowed *secs* to be omitted.
193
194 .. versionchanged:: 2.4
195 If *secs* is :const:`None`, the current time is used.
196
197
198.. function:: localtime([secs])
199
200 Like :func:`gmtime` but converts to local time. If *secs* is not provided or
[391]201 :const:`None`, the current time as returned by :func:`.time` is used. The dst
[2]202 flag is set to ``1`` when DST applies to the given time.
203
204 .. versionchanged:: 2.1
205 Allowed *secs* to be omitted.
206
207 .. versionchanged:: 2.4
208 If *secs* is :const:`None`, the current time is used.
209
210
211.. function:: mktime(t)
212
213 This is the inverse function of :func:`localtime`. Its argument is the
214 :class:`struct_time` or full 9-tuple (since the dst flag is needed; use ``-1``
215 as the dst flag if it is unknown) which expresses the time in *local* time, not
[391]216 UTC. It returns a floating point number, for compatibility with :func:`.time`.
[2]217 If the input value cannot be represented as a valid time, either
218 :exc:`OverflowError` or :exc:`ValueError` will be raised (which depends on
219 whether the invalid value is caught by Python or the underlying C libraries).
220 The earliest date for which it can generate a time is platform-dependent.
221
222
223.. function:: sleep(secs)
224
225 Suspend execution for the given number of seconds. The argument may be a
226 floating point number to indicate a more precise sleep time. The actual
227 suspension time may be less than that requested because any caught signal will
228 terminate the :func:`sleep` following execution of that signal's catching
229 routine. Also, the suspension time may be longer than requested by an arbitrary
230 amount because of the scheduling of other activity in the system.
231
232
233.. function:: strftime(format[, t])
234
235 Convert a tuple or :class:`struct_time` representing a time as returned by
236 :func:`gmtime` or :func:`localtime` to a string as specified by the *format*
237 argument. If *t* is not provided, the current time as returned by
238 :func:`localtime` is used. *format* must be a string. :exc:`ValueError` is
239 raised if any field in *t* is outside of the allowed range.
240
241 .. versionchanged:: 2.1
242 Allowed *t* to be omitted.
243
244 .. versionchanged:: 2.4
245 :exc:`ValueError` raised if a field in *t* is out of range.
246
247 .. versionchanged:: 2.5
248 0 is now a legal argument for any position in the time tuple; if it is normally
249 illegal the value is forced to a correct one..
250
251 The following directives can be embedded in the *format* string. They are shown
252 without the optional field width and precision specification, and are replaced
253 by the indicated characters in the :func:`strftime` result:
254
255 +-----------+--------------------------------+-------+
256 | Directive | Meaning | Notes |
257 +===========+================================+=======+
258 | ``%a`` | Locale's abbreviated weekday | |
259 | | name. | |
260 +-----------+--------------------------------+-------+
261 | ``%A`` | Locale's full weekday name. | |
262 +-----------+--------------------------------+-------+
263 | ``%b`` | Locale's abbreviated month | |
264 | | name. | |
265 +-----------+--------------------------------+-------+
266 | ``%B`` | Locale's full month name. | |
267 +-----------+--------------------------------+-------+
268 | ``%c`` | Locale's appropriate date and | |
269 | | time representation. | |
270 +-----------+--------------------------------+-------+
271 | ``%d`` | Day of the month as a decimal | |
272 | | number [01,31]. | |
273 +-----------+--------------------------------+-------+
274 | ``%H`` | Hour (24-hour clock) as a | |
275 | | decimal number [00,23]. | |
276 +-----------+--------------------------------+-------+
277 | ``%I`` | Hour (12-hour clock) as a | |
278 | | decimal number [01,12]. | |
279 +-----------+--------------------------------+-------+
280 | ``%j`` | Day of the year as a decimal | |
281 | | number [001,366]. | |
282 +-----------+--------------------------------+-------+
283 | ``%m`` | Month as a decimal number | |
284 | | [01,12]. | |
285 +-----------+--------------------------------+-------+
286 | ``%M`` | Minute as a decimal number | |
287 | | [00,59]. | |
288 +-----------+--------------------------------+-------+
289 | ``%p`` | Locale's equivalent of either | \(1) |
290 | | AM or PM. | |
291 +-----------+--------------------------------+-------+
292 | ``%S`` | Second as a decimal number | \(2) |
293 | | [00,61]. | |
294 +-----------+--------------------------------+-------+
295 | ``%U`` | Week number of the year | \(3) |
296 | | (Sunday as the first day of | |
297 | | the week) as a decimal number | |
298 | | [00,53]. All days in a new | |
299 | | year preceding the first | |
300 | | Sunday are considered to be in | |
301 | | week 0. | |
302 +-----------+--------------------------------+-------+
303 | ``%w`` | Weekday as a decimal number | |
304 | | [0(Sunday),6]. | |
305 +-----------+--------------------------------+-------+
306 | ``%W`` | Week number of the year | \(3) |
307 | | (Monday as the first day of | |
308 | | the week) as a decimal number | |
309 | | [00,53]. All days in a new | |
310 | | year preceding the first | |
311 | | Monday are considered to be in | |
312 | | week 0. | |
313 +-----------+--------------------------------+-------+
314 | ``%x`` | Locale's appropriate date | |
315 | | representation. | |
316 +-----------+--------------------------------+-------+
317 | ``%X`` | Locale's appropriate time | |
318 | | representation. | |
319 +-----------+--------------------------------+-------+
320 | ``%y`` | Year without century as a | |
321 | | decimal number [00,99]. | |
322 +-----------+--------------------------------+-------+
323 | ``%Y`` | Year with century as a decimal | |
324 | | number. | |
325 +-----------+--------------------------------+-------+
326 | ``%Z`` | Time zone name (no characters | |
327 | | if no time zone exists). | |
328 +-----------+--------------------------------+-------+
329 | ``%%`` | A literal ``'%'`` character. | |
330 +-----------+--------------------------------+-------+
331
332 Notes:
333
334 (1)
335 When used with the :func:`strptime` function, the ``%p`` directive only affects
336 the output hour field if the ``%I`` directive is used to parse the hour.
337
338 (2)
339 The range really is ``0`` to ``61``; this accounts for leap seconds and the
340 (very rare) double leap seconds.
341
342 (3)
343 When used with the :func:`strptime` function, ``%U`` and ``%W`` are only used in
344 calculations when the day of the week and the year are specified.
345
346 Here is an example, a format for dates compatible with that specified in the
347 :rfc:`2822` Internet email standard. [#]_ ::
348
349 >>> from time import gmtime, strftime
350 >>> strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime())
351 'Thu, 28 Jun 2001 14:17:15 +0000'
352
[391]353 Additional directives may be supported on certain platforms, but only the
354 ones listed here have a meaning standardized by ANSI C. To see the full set
355 of format codes supported on your platform, consult the :manpage:`strftime(3)`
356 documentation.
[2]357
358 On some platforms, an optional field width and precision specification can
359 immediately follow the initial ``'%'`` of a directive in the following order;
360 this is also not portable. The field width is normally 2 except for ``%j`` where
361 it is 3.
362
363
364.. function:: strptime(string[, format])
365
366 Parse a string representing a time according to a format. The return value is
367 a :class:`struct_time` as returned by :func:`gmtime` or :func:`localtime`.
368
369 The *format* parameter uses the same directives as those used by
370 :func:`strftime`; it defaults to ``"%a %b %d %H:%M:%S %Y"`` which matches the
371 formatting returned by :func:`ctime`. If *string* cannot be parsed according to
372 *format*, or if it has excess data after parsing, :exc:`ValueError` is raised.
373 The default values used to fill in any missing data when more accurate values
374 cannot be inferred are ``(1900, 1, 1, 0, 0, 0, 0, 1, -1)``.
375
376 For example:
377
378 >>> import time
379 >>> time.strptime("30 Nov 00", "%d %b %y") # doctest: +NORMALIZE_WHITESPACE
380 time.struct_time(tm_year=2000, tm_mon=11, tm_mday=30, tm_hour=0, tm_min=0,
381 tm_sec=0, tm_wday=3, tm_yday=335, tm_isdst=-1)
382
383 Support for the ``%Z`` directive is based on the values contained in ``tzname``
384 and whether ``daylight`` is true. Because of this, it is platform-specific
385 except for recognizing UTC and GMT which are always known (and are considered to
386 be non-daylight savings timezones).
387
388 Only the directives specified in the documentation are supported. Because
389 ``strftime()`` is implemented per platform it can sometimes offer more
390 directives than those listed. But ``strptime()`` is independent of any platform
391 and thus does not necessarily support all directives available that are not
392 documented as supported.
393
394
[391]395.. class:: struct_time
[2]396
397 The type of the time value sequence returned by :func:`gmtime`,
[391]398 :func:`localtime`, and :func:`strptime`. It is an object with a :term:`named
399 tuple` interface: values can be accessed by index and by attribute name. The
400 following values are present:
[2]401
[391]402 +-------+-------------------+---------------------------------+
403 | Index | Attribute | Values |
404 +=======+===================+=================================+
405 | 0 | :attr:`tm_year` | (for example, 1993) |
406 +-------+-------------------+---------------------------------+
407 | 1 | :attr:`tm_mon` | range [1, 12] |
408 +-------+-------------------+---------------------------------+
409 | 2 | :attr:`tm_mday` | range [1, 31] |
410 +-------+-------------------+---------------------------------+
411 | 3 | :attr:`tm_hour` | range [0, 23] |
412 +-------+-------------------+---------------------------------+
413 | 4 | :attr:`tm_min` | range [0, 59] |
414 +-------+-------------------+---------------------------------+
415 | 5 | :attr:`tm_sec` | range [0, 61]; see **(2)** in |
416 | | | :func:`strftime` description |
417 +-------+-------------------+---------------------------------+
418 | 6 | :attr:`tm_wday` | range [0, 6], Monday is 0 |
419 +-------+-------------------+---------------------------------+
420 | 7 | :attr:`tm_yday` | range [1, 366] |
421 +-------+-------------------+---------------------------------+
422 | 8 | :attr:`tm_isdst` | 0, 1 or -1; see below |
423 +-------+-------------------+---------------------------------+
424
[2]425 .. versionadded:: 2.2
426
[391]427 Note that unlike the C structure, the month value is a range of [1, 12], not
428 [0, 11]. A year value will be handled as described under :ref:`Year 2000
429 (Y2K) issues <time-y2kissues>` above. A ``-1`` argument as the daylight
430 savings flag, passed to :func:`mktime` will usually result in the correct
431 daylight savings state to be filled in.
[2]432
[391]433 When a tuple with an incorrect length is passed to a function expecting a
434 :class:`struct_time`, or having elements of the wrong type, a
435 :exc:`TypeError` is raised.
436
437
[2]438.. function:: time()
439
[391]440 Return the time in seconds since the epoch as a floating point number.
441 Note that even though the time is always returned as a floating point
[2]442 number, not all systems provide time with a better precision than 1 second.
443 While this function normally returns non-decreasing values, it can return a
444 lower value than a previous call if the system clock has been set back between
445 the two calls.
446
447
448.. data:: timezone
449
450 The offset of the local (non-DST) timezone, in seconds west of UTC (negative in
451 most of Western Europe, positive in the US, zero in the UK).
452
453
454.. data:: tzname
455
456 A tuple of two strings: the first is the name of the local non-DST timezone, the
457 second is the name of the local DST timezone. If no DST timezone is defined,
458 the second string should not be used.
459
460
461.. function:: tzset()
462
463 Resets the time conversion rules used by the library routines. The environment
464 variable :envvar:`TZ` specifies how this is done.
465
466 .. versionadded:: 2.3
467
468 Availability: Unix.
469
470 .. note::
471
472 Although in many cases, changing the :envvar:`TZ` environment variable may
473 affect the output of functions like :func:`localtime` without calling
474 :func:`tzset`, this behavior should not be relied on.
475
476 The :envvar:`TZ` environment variable should contain no whitespace.
477
478 The standard format of the :envvar:`TZ` environment variable is (whitespace
479 added for clarity)::
480
481 std offset [dst [offset [,start[/time], end[/time]]]]
482
483 Where the components are:
484
485 ``std`` and ``dst``
486 Three or more alphanumerics giving the timezone abbreviations. These will be
487 propagated into time.tzname
488
489 ``offset``
490 The offset has the form: ``± hh[:mm[:ss]]``. This indicates the value
491 added the local time to arrive at UTC. If preceded by a '-', the timezone
492 is east of the Prime Meridian; otherwise, it is west. If no offset follows
493 dst, summer time is assumed to be one hour ahead of standard time.
494
495 ``start[/time], end[/time]``
496 Indicates when to change to and back from DST. The format of the
497 start and end dates are one of the following:
498
499 :samp:`J{n}`
500 The Julian day *n* (1 <= *n* <= 365). Leap days are not counted, so in
501 all years February 28 is day 59 and March 1 is day 60.
502
503 :samp:`{n}`
504 The zero-based Julian day (0 <= *n* <= 365). Leap days are counted, and
505 it is possible to refer to February 29.
506
507 :samp:`M{m}.{n}.{d}`
508 The *d*'th day (0 <= *d* <= 6) or week *n* of month *m* of the year (1
509 <= *n* <= 5, 1 <= *m* <= 12, where week 5 means "the last *d* day in
510 month *m*" which may occur in either the fourth or the fifth
511 week). Week 1 is the first week in which the *d*'th day occurs. Day
512 zero is Sunday.
513
514 ``time`` has the same format as ``offset`` except that no leading sign
515 ('-' or '+') is allowed. The default, if time is not given, is 02:00:00.
516
517 ::
518
519 >>> os.environ['TZ'] = 'EST+05EDT,M4.1.0,M10.5.0'
520 >>> time.tzset()
521 >>> time.strftime('%X %x %Z')
522 '02:07:36 05/08/03 EDT'
523 >>> os.environ['TZ'] = 'AEST-10AEDT-11,M10.5.0,M3.5.0'
524 >>> time.tzset()
525 >>> time.strftime('%X %x %Z')
526 '16:08:12 05/08/03 AEST'
527
528 On many Unix systems (including \*BSD, Linux, Solaris, and Darwin), it is more
529 convenient to use the system's zoneinfo (:manpage:`tzfile(5)`) database to
530 specify the timezone rules. To do this, set the :envvar:`TZ` environment
531 variable to the path of the required timezone datafile, relative to the root of
532 the systems 'zoneinfo' timezone database, usually located at
533 :file:`/usr/share/zoneinfo`. For example, ``'US/Eastern'``,
534 ``'Australia/Melbourne'``, ``'Egypt'`` or ``'Europe/Amsterdam'``. ::
535
536 >>> os.environ['TZ'] = 'US/Eastern'
537 >>> time.tzset()
538 >>> time.tzname
539 ('EST', 'EDT')
540 >>> os.environ['TZ'] = 'Egypt'
541 >>> time.tzset()
542 >>> time.tzname
543 ('EET', 'EEST')
544
545
546.. seealso::
547
548 Module :mod:`datetime`
549 More object-oriented interface to dates and times.
550
551 Module :mod:`locale`
[391]552 Internationalization services. The locale setting affects the interpretation
553 of many format specifiers in :func:`strftime` and :func:`strptime`.
[2]554
555 Module :mod:`calendar`
[391]556 General calendar-related functions. :func:`~calendar.timegm` is the
557 inverse of :func:`gmtime` from this module.
[2]558
559.. rubric:: Footnotes
560
561.. [#] The use of ``%Z`` is now deprecated, but the ``%z`` escape that expands to the
562 preferred hour/minute offset is not supported by all ANSI C libraries. Also, a
563 strict reading of the original 1982 :rfc:`822` standard calls for a two-digit
564 year (%y rather than %Y), but practice moved to 4-digit years long before the
[391]565 year 2000. After that, :rfc:`822` became obsolete and the 4-digit year has
566 been first recommended by :rfc:`1123` and then mandated by :rfc:`2822`.
[2]567
Note: See TracBrowser for help on using the repository browser.