rest25/library/time.rst => rest262/library/time.rst
f1
2:mod:`time` --- Time access and conversions
3===========================================
4
5.. module:: time
6   :synopsis: Time access and conversions.
7
8
n9-This module provides various time-related functions.  It is always available,
n9+This module provides various time-related functions. For related
10+functionality, see also the :mod:`datetime` and :mod:`calendar` modules.
11+ 
12+Although this module is always available,
10-but not all functions are available on all platforms.  Most of the functions
13+not all functions are available on all platforms.  Most of the functions
11defined in this module call platform C library functions with the same name.  It
12may sometimes be helpful to consult the platform documentation, because the
13semantics of these functions varies among platforms.
14
15An explanation of some terminology and conventions is in order.
16
17  .. index:: single: epoch
18
59* DST is Daylight Saving Time, an adjustment of the timezone by (usually) one
60  hour during part of the year.  DST rules are magic (determined by local law) and
61  can change from year to year.  The C library has a table containing the local
62  rules (often it is read from a system file for flexibility) and is the only
63  source of True Wisdom in this respect.
64
65* The precision of the various real-time functions may be less than suggested by
66  the units in which their value or argument is expressed. E.g. on most Unix
n67-  systems, the clock "ticks" only 50 or 100 times a second, and on the Mac, times
n70+  systems, the clock "ticks" only 50 or 100 times a second.
68-  are only accurate to whole seconds.
69
70* On the other hand, the precision of :func:`time` and :func:`sleep` is better
71  than their Unix equivalents: times are expressed as floating point numbers,
72  :func:`time` returns the most accurate time available (using Unix
73  :cfunc:`gettimeofday` where available), and :func:`sleep` will accept a time
74  with a nonzero fraction (Unix :cfunc:`select` is used to implement this, where
75  available).
76
77* The time value as returned by :func:`gmtime`, :func:`localtime`, and
78  :func:`strptime`, and accepted by :func:`asctime`, :func:`mktime` and
n79-  :func:`strftime`, is a sequence of 9 integers.  The return values of
n81+  :func:`strftime`, may be considered as a sequence of 9 integers.  The return
80-  :func:`gmtime`, :func:`localtime`, and :func:`strptime` also offer attribute
82+  values of :func:`gmtime`, :func:`localtime`, and :func:`strptime` also offer
81-  names for individual fields.
83+  attribute names for individual fields.
82
n83-  +-------+------------------+------------------------------+
n85+  +-------+-------------------+---------------------------------+
84-  | Index | Attribute        | Values                       |
86+  | Index | Attribute         | Values                          |
85-  +=======+==================+==============================+
87+  +=======+===================+=================================+
86-  | 0     | :attr:`tm_year`  | (for example, 1993)          |
88+  | 0     | :attr:`tm_year`   | (for example, 1993)             |
87-  +-------+------------------+------------------------------+
89+  +-------+-------------------+---------------------------------+
88-  | 1     | :attr:`tm_mon`   | range [1,12]                 |
90+  | 1     | :attr:`tm_mon`    | range [1,12]                    |
89-  +-------+------------------+------------------------------+
91+  +-------+-------------------+---------------------------------+
90-  | 2     | :attr:`tm_mday`  | range [1,31]                 |
92+  | 2     | :attr:`tm_mday`   | range [1,31]                    |
91-  +-------+------------------+------------------------------+
93+  +-------+-------------------+---------------------------------+
92-  | 3     | :attr:`tm_hour`  | range [0,23]                 |
94+  | 3     | :attr:`tm_hour`   | range [0,23]                    |
93-  +-------+------------------+------------------------------+
95+  +-------+-------------------+---------------------------------+
94-  | 4     | :attr:`tm_min`   | range [0,59]                 |
96+  | 4     | :attr:`tm_min`    | range [0,59]                    |
95-  +-------+------------------+------------------------------+
97+  +-------+-------------------+---------------------------------+
96-  | 5     | :attr:`tm_sec`   | range [0,61]; see **(1)** in |
98+  | 5     | :attr:`tm_sec`    | range [0,61]; see **(1)** in    |
97-  |       |                  | :func:`strftime` description |
99+  |       |                   | :func:`strftime` description    |
98-  +-------+------------------+------------------------------+
100+  +-------+-------------------+---------------------------------+
99-  | 6     | :attr:`tm_wday`  | range [0,6], Monday is 0     |
101+  | 6     | :attr:`tm_wday`   | range [0,6], Monday is 0        |
100-  +-------+------------------+------------------------------+
102+  +-------+-------------------+---------------------------------+
101-  | 7     | :attr:`tm_yday`  | range [1,366]                |
103+  | 7     | :attr:`tm_yday`   | range [1,366]                   |
102-  +-------+------------------+------------------------------+
104+  +-------+-------------------+---------------------------------+
103-  | 8     | :attr:`tm_isdst` | 0, 1 or -1; see below        |
105+  | 8     | :attr:`tm_isdst`  | 0, 1 or -1; see below           |
104-  +-------+------------------+------------------------------+
106+  +-------+-------------------+---------------------------------+
105
106  Note that unlike the C structure, the month value is a range of 1-12, not 0-11.
107  A year value will be handled as described under "Year 2000 (Y2K) issues" above.
108  A ``-1`` argument as the daylight savings flag, passed to :func:`mktime` will
109  usually result in the correct daylight savings state to be filled in.
110
111  When a tuple with an incorrect length is passed to a function expecting a
112  :class:`struct_time`, or having elements of the wrong type, a :exc:`TypeError`
113  is raised.
114
115  .. versionchanged:: 2.2
116     The time value sequence was changed from a tuple to a :class:`struct_time`, with
117     the addition of attribute names for the fields.
118
n121+* Use the following functions to convert between time representations:
122+ 
123+  +-------------------------+-------------------------+-------------------------+
124+  | From                    | To                      | Use                     |
125+  +=========================+=========================+=========================+
126+  | seconds since the epoch | :class:`struct_time` in | :func:`gmtime`          |
127+  |                         | UTC                     |                         |
128+  +-------------------------+-------------------------+-------------------------+
129+  | seconds since the epoch | :class:`struct_time` in | :func:`localtime`       |
130+  |                         | local time              |                         |
131+  +-------------------------+-------------------------+-------------------------+
132+  | :class:`struct_time` in | seconds since the epoch | :func:`calendar.timegm` |
133+  | UTC                     |                         |                         |
134+  +-------------------------+-------------------------+-------------------------+
135+  | :class:`struct_time` in | seconds since the epoch | :func:`mktime`          |
136+  | local time              |                         |                         |
137+  +-------------------------+-------------------------+-------------------------+
138+ 
139+ 
119The module defines the following functions and data items:
n120- 
121
122.. data:: accept2dyear
123
124   Boolean value indicating whether two-digit year values will be accepted.  This
125   is true by default, but will be set to false if the environment variable
126   :envvar:`PYTHONY2K` has been set to a non-empty string.  It may also be modified
127   at run time.
128
365   immediately follow the initial ``'%'`` of a directive in the following order;
366   this is also not portable. The field width is normally 2 except for ``%j`` where
367   it is 3.
368
369
370.. function:: strptime(string[, format])
371
372   Parse a string representing a time according to a format.  The return  value is
n373-   a :class:`struct_time` as returned by :func:`gmtime` or :func:`localtime`.  The
n393+   a :class:`struct_time` as returned by :func:`gmtime` or :func:`localtime`.
394+ 
374-   *format* parameter uses the same directives as those used by :func:`strftime`;
395+   The *format* parameter uses the same directives as those used by
375-   it defaults to ``"%a %b %d %H:%M:%S %Y"`` which matches the formatting returned
396+   :func:`strftime`; it defaults to ``"%a %b %d %H:%M:%S %Y"`` which matches the
376-   by :func:`ctime`.  If *string* cannot be parsed according to *format*,
397+   formatting returned by :func:`ctime`. If *string* cannot be parsed according to
377-   :exc:`ValueError` is raised.  If the string to be parsed has excess data after
398+   *format*, or if it has excess data after parsing, :exc:`ValueError` is raised.
378-   parsing, :exc:`ValueError` is raised.  The default values used to fill in any
399+   The default values used to fill in any missing data when more accurate values
379-   missing data when more accurate values cannot be inferred are ``(1900, 1, 1, 0,
400+   cannot be inferred are ``(1900, 1, 1, 0, 0, 0, 0, 1, -1)``.
380-   0, 0, 0, 1, -1)`` .
401+ 
402+   For example:
403+ 
404+      >>> import time
405+      >>> time.strptime("30 Nov 00", "%d %b %y")   # doctest: +NORMALIZE_WHITESPACE
406+      time.struct_time(tm_year=2000, tm_mon=11, tm_mday=30, tm_hour=0, tm_min=0,
407+                       tm_sec=0, tm_wday=3, tm_yday=335, tm_isdst=-1)
381
382   Support for the ``%Z`` directive is based on the values contained in ``tzname``
383   and whether ``daylight`` is true.  Because of this, it is platform-specific
384   except for recognizing UTC and GMT which are always known (and are considered to
385   be non-daylight savings timezones).
n413+ 
414+   Only the directives specified in the documentation are supported.  Because
415+   ``strftime()`` is implemented per platform it can sometimes offer more
416+   directives than those listed.  But ``strptime()`` is independent of any platform
417+   and thus does not necessarily support all directives available that are not
418+   documented as supported.
386
387
388.. data:: struct_time
389
390   The type of the time value sequence returned by :func:`gmtime`,
391   :func:`localtime`, and :func:`strptime`.
392
393   .. versionadded:: 2.2
428   .. note::
429
430      Although in many cases, changing the :envvar:`TZ` environment variable may
431      affect the output of functions like :func:`localtime` without calling
432      :func:`tzset`, this behavior should not be relied on.
433
434      The :envvar:`TZ` environment variable should contain no whitespace.
435
n436-   The standard format of the :envvar:`TZ` environment variable is: (whitespace
n469+   The standard format of the :envvar:`TZ` environment variable is (whitespace
437-   added for clarity)
470+   added for clarity)::
438
n439-   std offset [dst [offset
n472+      std offset [dst [offset [,start[/time], end[/time]]]]
440-      [,start[/time], end[/time]]]]
441
n442-   Where:
n474+   Where the components are:
443
n444-   std and dst
n476+   ``std`` and ``dst``
445      Three or more alphanumerics giving the timezone abbreviations. These will be
446      propagated into time.tzname
447
n448-   offset
n480+   ``offset``
449-      The offset has the form: ± hh[:mm[:ss]]. This indicates the value added the
481+      The offset has the form: ``± hh[:mm[:ss]]``. This indicates the value
450-      local time to arrive at UTC.  If preceded by a '-', the timezone is east of the
482+      added the local time to arrive at UTC.  If preceded by a '-', the timezone
451-      Prime  Meridian; otherwise, it is west. If no offset follows dst, summer time is
483+      is east of the Prime Meridian; otherwise, it is west. If no offset follows
452-      assumed to be one hour ahead of standard time.
484+      dst, summer time is assumed to be one hour ahead of standard time.
453
n454-   start[/time
n486+   ``start[/time], end[/time]``
455-      ,end[/time]] Indicates when to change to and back from DST. The format of the
487+      Indicates when to change to and back from DST. The format of the
456      start and end dates are one of the following:
457
n458-      J*n*
n490+      :samp:`J{n}`
459-         The Julian day *n* (1 <= *n* <= 365). Leap days are not  counted, so in all
491+         The Julian day *n* (1 <= *n* <= 365). Leap days are not counted, so in
460-         years February 28 is day 59 and March 1 is day 60.
492+         all years February 28 is day 59 and March 1 is day 60.
461
n462-      *n*
n494+      :samp:`{n}`
463-         The zero-based Julian day (0 <= *n* <= 365). Leap days are counted, and it is
495+         The zero-based Julian day (0 <= *n* <= 365). Leap days are counted, and
464-         possible to refer to February 29.
496+         it is possible to refer to February 29.
465
n466-      M*m*.*n*.*d*
n498+      :samp:`M{m}.{n}.{d}`
467-         The *d*'th day (0 <= *d* <= 6) or week *n*  of month *m* of the year (1 <= *n*
499+         The *d*'th day (0 <= *d* <= 6) or week *n* of month *m* of the year (1
468-         <= 5,  1 <= *m* <= 12, where week 5 means "the last *d* day in month *m*" which
500+         <= *n* <= 5, 1 <= *m* <= 12, where week 5 means "the last *d* day in
469-         may occur in either the fourth or  the fifth week). Week 1 is the first week in
501+         month *m*" which may occur in either the fourth or the fifth
470-         which the  *d*'th day occurs. Day zero is Sunday.
502+         week). Week 1 is the first week in which the *d*'th day occurs. Day
503+         zero is Sunday.
471
t472-      time has the same format as offset except that no leading sign ('-' or '+') is
t505+      ``time`` has the same format as ``offset`` except that no leading sign
473-      allowed. The default, if time is not given, is 02:00:00.
506+      ('-' or '+') is allowed. The default, if time is not given, is 02:00:00.
474
475   ::
476
477      >>> os.environ['TZ'] = 'EST+05EDT,M4.1.0,M10.5.0'
478      >>> time.tzset()
479      >>> time.strftime('%X %x %Z')
480      '02:07:36 05/08/03 EDT'
481      >>> os.environ['TZ'] = 'AEST-10AEDT-11,M10.5.0,M3.5.0'
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op