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