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 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 7 | -------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 8 | |
| 9 | 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, |
| 13 | not all functions are available on all platforms. Most of the functions |
| 14 | defined in this module call platform C library functions with the same name. It |
| 15 | may sometimes be helpful to consult the platform documentation, because the |
| 16 | semantics of these functions varies among platforms. |
| 17 | |
| 18 | An explanation of some terminology and conventions is in order. |
| 19 | |
Eric Appelt | 23557d5 | 2017-02-16 05:00:45 -0500 | [diff] [blame] | 20 | .. _epoch: |
| 21 | |
Georg Brandl | b67878a | 2010-10-15 17:01:15 +0000 | [diff] [blame] | 22 | .. index:: single: epoch |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 23 | |
Eric Appelt | 23557d5 | 2017-02-16 05:00:45 -0500 | [diff] [blame] | 24 | * The :dfn:`epoch` is the point where the time starts, and is platform |
| 25 | dependent. For Unix, the epoch is January 1, 1970, 00:00:00 (UTC). |
| 26 | To find out what the epoch is on a given platform, look at |
| 27 | ``time.gmtime(0)``. |
| 28 | |
| 29 | .. _leap seconds: https://en.wikipedia.org/wiki/Leap_second |
| 30 | |
| 31 | .. index:: seconds since the epoch |
| 32 | |
| 33 | * The term :dfn:`seconds since the epoch` refers to the total number |
| 34 | of elapsed seconds since the epoch, typically excluding |
| 35 | `leap seconds`_. Leap seconds are excluded from this total on all |
| 36 | POSIX-compliant platforms. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 37 | |
Georg Brandl | b67878a | 2010-10-15 17:01:15 +0000 | [diff] [blame] | 38 | .. index:: single: Year 2038 |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 39 | |
Alexander Belopolsky | c64708a | 2011-01-07 19:59:19 +0000 | [diff] [blame] | 40 | * 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] | 41 | 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] | 42 | library; for 32-bit systems, it is typically in 2038. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 43 | |
Georg Brandl | b67878a | 2010-10-15 17:01:15 +0000 | [diff] [blame] | 44 | .. index:: |
| 45 | single: Year 2000 |
| 46 | single: Y2K |
| 47 | |
| 48 | .. _time-y2kissues: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 49 | |
Alexander Belopolsky | c64708a | 2011-01-07 19:59:19 +0000 | [diff] [blame] | 50 | * **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] | 51 | 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] | 52 | represented internally as seconds since the epoch. Function :func:`strptime` |
| 53 | can parse 2-digit years when given ``%y`` format code. When 2-digit years are |
| 54 | parsed, they are converted according to the POSIX and ISO C standards: values |
| 55 | 69--99 are mapped to 1969--1999, and values 0--68 are mapped to 2000--2068. |
| 56 | |
Georg Brandl | b67878a | 2010-10-15 17:01:15 +0000 | [diff] [blame] | 57 | .. index:: |
| 58 | single: UTC |
| 59 | single: Coordinated Universal Time |
| 60 | single: Greenwich Mean Time |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 61 | |
| 62 | * UTC is Coordinated Universal Time (formerly known as Greenwich Mean Time, or |
| 63 | GMT). The acronym UTC is not a mistake but a compromise between English and |
| 64 | French. |
| 65 | |
Georg Brandl | b67878a | 2010-10-15 17:01:15 +0000 | [diff] [blame] | 66 | .. index:: single: Daylight Saving Time |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 67 | |
| 68 | * DST is Daylight Saving Time, an adjustment of the timezone by (usually) one |
| 69 | hour during part of the year. DST rules are magic (determined by local law) and |
| 70 | can change from year to year. The C library has a table containing the local |
| 71 | rules (often it is read from a system file for flexibility) and is the only |
| 72 | source of True Wisdom in this respect. |
| 73 | |
| 74 | * The precision of the various real-time functions may be less than suggested by |
| 75 | 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] | 76 | systems, the clock "ticks" only 50 or 100 times a second. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 77 | |
Petri Lehtinen | 1033b31 | 2012-05-18 21:19:17 +0300 | [diff] [blame] | 78 | * On the other hand, the precision of :func:`.time` and :func:`sleep` is better |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 79 | than their Unix equivalents: times are expressed as floating point numbers, |
Petri Lehtinen | 1033b31 | 2012-05-18 21:19:17 +0300 | [diff] [blame] | 80 | :func:`.time` returns the most accurate time available (using Unix |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 81 | :c:func:`gettimeofday` where available), and :func:`sleep` will accept a time |
| 82 | 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] | 83 | available). |
| 84 | |
| 85 | * The time value as returned by :func:`gmtime`, :func:`localtime`, and |
| 86 | :func:`strptime`, and accepted by :func:`asctime`, :func:`mktime` and |
| 87 | :func:`strftime`, is a sequence of 9 integers. The return values of |
| 88 | :func:`gmtime`, :func:`localtime`, and :func:`strptime` also offer attribute |
| 89 | names for individual fields. |
| 90 | |
Georg Brandl | b67878a | 2010-10-15 17:01:15 +0000 | [diff] [blame] | 91 | See :class:`struct_time` for a description of these objects. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 92 | |
Alexander Belopolsky | c142bba | 2012-06-13 22:15:26 -0400 | [diff] [blame] | 93 | .. versionchanged:: 3.3 |
Georg Brandl | 61063cc | 2012-06-24 22:48:30 +0200 | [diff] [blame] | 94 | The :class:`struct_time` type was extended to provide the :attr:`tm_gmtoff` |
| 95 | and :attr:`tm_zone` attributes when platform supports corresponding |
| 96 | ``struct tm`` members. |
Alexander Belopolsky | c142bba | 2012-06-13 22:15:26 -0400 | [diff] [blame] | 97 | |
Alexander Belopolsky | 18f3a9b | 2016-09-11 22:55:16 -0400 | [diff] [blame] | 98 | .. versionchanged:: 3.6 |
| 99 | The :class:`struct_time` attributes :attr:`tm_gmtoff` and :attr:`tm_zone` |
| 100 | are now available on all platforms. |
| 101 | |
Benjamin Peterson | e0124bd | 2009-03-09 21:04:33 +0000 | [diff] [blame] | 102 | * Use the following functions to convert between time representations: |
| 103 | |
| 104 | +-------------------------+-------------------------+-------------------------+ |
| 105 | | From | To | Use | |
| 106 | +=========================+=========================+=========================+ |
| 107 | | seconds since the epoch | :class:`struct_time` in | :func:`gmtime` | |
| 108 | | | UTC | | |
| 109 | +-------------------------+-------------------------+-------------------------+ |
| 110 | | seconds since the epoch | :class:`struct_time` in | :func:`localtime` | |
| 111 | | | local time | | |
| 112 | +-------------------------+-------------------------+-------------------------+ |
| 113 | | :class:`struct_time` in | seconds since the epoch | :func:`calendar.timegm` | |
| 114 | | UTC | | | |
| 115 | +-------------------------+-------------------------+-------------------------+ |
| 116 | | :class:`struct_time` in | seconds since the epoch | :func:`mktime` | |
| 117 | | local time | | | |
| 118 | +-------------------------+-------------------------+-------------------------+ |
| 119 | |
| 120 | |
Cheryl Sabella | 703ff38 | 2017-10-11 09:29:14 -0400 | [diff] [blame] | 121 | .. _time-functions: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 122 | |
Cheryl Sabella | 703ff38 | 2017-10-11 09:29:14 -0400 | [diff] [blame] | 123 | Functions |
| 124 | --------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 125 | |
| 126 | .. function:: asctime([t]) |
| 127 | |
| 128 | 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] | 129 | :func:`gmtime` or :func:`localtime` to a string of the following |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 130 | form: ``'Sun Jun 20 23:21:05 1993'``. If *t* is not provided, the current time |
| 131 | as returned by :func:`localtime` is used. Locale information is not used by |
| 132 | :func:`asctime`. |
| 133 | |
| 134 | .. note:: |
| 135 | |
Georg Brandl | 538343d | 2012-02-02 22:22:19 +0100 | [diff] [blame] | 136 | Unlike the C function of the same name, :func:`asctime` does not add a |
| 137 | trailing newline. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 138 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 139 | |
Victor Stinner | 4195b5c | 2012-02-08 23:03:19 +0100 | [diff] [blame] | 140 | .. function:: clock() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 141 | |
| 142 | .. index:: |
| 143 | single: CPU time |
| 144 | single: processor time |
| 145 | single: benchmarking |
| 146 | |
| 147 | On Unix, return the current processor time as a floating point number expressed |
| 148 | in seconds. The precision, and in fact the very definition of the meaning of |
Georg Brandl | 01546a8 | 2014-10-28 21:35:35 +0100 | [diff] [blame] | 149 | "processor time", depends on that of the C function of the same name. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 150 | |
| 151 | On Windows, this function returns wall-clock seconds elapsed since the first |
| 152 | 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] | 153 | :c:func:`QueryPerformanceCounter`. The resolution is typically better than one |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 154 | microsecond. |
| 155 | |
Victor Stinner | 47620a6 | 2012-04-29 02:52:39 +0200 | [diff] [blame] | 156 | .. deprecated:: 3.3 |
| 157 | The behaviour of this function depends on the platform: use |
| 158 | :func:`perf_counter` or :func:`process_time` instead, depending on your |
| 159 | requirements, to have a well defined behaviour. |
| 160 | |
pdox | e14679c | 2017-10-05 00:01:56 -0700 | [diff] [blame] | 161 | .. function:: pthread_getcpuclockid(thread_id) |
| 162 | |
| 163 | Return the *clk_id* of the thread-specific CPU-time clock for the specified *thread_id*. |
| 164 | |
| 165 | Use :func:`threading.get_ident` or the :attr:`~threading.Thread.ident` |
| 166 | attribute of :class:`threading.Thread` objects to get a suitable value |
| 167 | for *thread_id*. |
| 168 | |
| 169 | .. warning:: |
| 170 | Passing an invalid or expired *thread_id* may result in |
| 171 | undefined behavior, such as segmentation fault. |
| 172 | |
| 173 | Availability: Unix (see the man page for :manpage:`pthread_getcpuclockid(3)` for |
| 174 | further information) |
| 175 | |
| 176 | .. versionadded:: 3.7 |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 177 | |
Victor Stinner | 4195b5c | 2012-02-08 23:03:19 +0100 | [diff] [blame] | 178 | .. function:: clock_getres(clk_id) |
Victor Stinner | e0be423 | 2011-10-25 13:06:09 +0200 | [diff] [blame] | 179 | |
Cheryl Sabella | 703ff38 | 2017-10-11 09:29:14 -0400 | [diff] [blame] | 180 | Return the resolution (precision) of the specified clock *clk_id*. Refer to |
| 181 | :ref:`time-clock-id-constants` for a list of accepted values for *clk_id*. |
Victor Stinner | e0be423 | 2011-10-25 13:06:09 +0200 | [diff] [blame] | 182 | |
Victor Stinner | ca6e40f | 2012-04-28 23:47:33 +0200 | [diff] [blame] | 183 | Availability: Unix. |
| 184 | |
Victor Stinner | e0be423 | 2011-10-25 13:06:09 +0200 | [diff] [blame] | 185 | .. versionadded:: 3.3 |
| 186 | |
Georg Brandl | 909f5bc | 2012-03-29 09:18:14 +0200 | [diff] [blame] | 187 | |
Victor Stinner | c29b585 | 2017-11-02 07:28:27 -0700 | [diff] [blame] | 188 | .. function:: clock_gettime(clk_id) -> float |
Victor Stinner | e0be423 | 2011-10-25 13:06:09 +0200 | [diff] [blame] | 189 | |
Cheryl Sabella | 703ff38 | 2017-10-11 09:29:14 -0400 | [diff] [blame] | 190 | Return the time of the specified clock *clk_id*. Refer to |
| 191 | :ref:`time-clock-id-constants` for a list of accepted values for *clk_id*. |
Victor Stinner | e0be423 | 2011-10-25 13:06:09 +0200 | [diff] [blame] | 192 | |
Victor Stinner | ca6e40f | 2012-04-28 23:47:33 +0200 | [diff] [blame] | 193 | Availability: Unix. |
| 194 | |
Victor Stinner | e0be423 | 2011-10-25 13:06:09 +0200 | [diff] [blame] | 195 | .. versionadded:: 3.3 |
| 196 | |
Georg Brandl | 909f5bc | 2012-03-29 09:18:14 +0200 | [diff] [blame] | 197 | |
Victor Stinner | c29b585 | 2017-11-02 07:28:27 -0700 | [diff] [blame] | 198 | .. function:: clock_gettime_ns(clk_id) -> int |
| 199 | |
| 200 | Similar to :func:`clock_gettime` but return time as nanoseconds. |
| 201 | |
| 202 | Availability: Unix. |
| 203 | |
| 204 | .. versionadded:: 3.7 |
| 205 | |
| 206 | |
| 207 | .. function:: clock_settime(clk_id, time: float) |
Victor Stinner | 30d7947 | 2012-04-03 00:45:07 +0200 | [diff] [blame] | 208 | |
Cheryl Sabella | 703ff38 | 2017-10-11 09:29:14 -0400 | [diff] [blame] | 209 | Set the time of the specified clock *clk_id*. Currently, |
| 210 | :data:`CLOCK_REALTIME` is the only accepted value for *clk_id*. |
Victor Stinner | e0be423 | 2011-10-25 13:06:09 +0200 | [diff] [blame] | 211 | |
Victor Stinner | ca6e40f | 2012-04-28 23:47:33 +0200 | [diff] [blame] | 212 | Availability: Unix. |
| 213 | |
Victor Stinner | e0be423 | 2011-10-25 13:06:09 +0200 | [diff] [blame] | 214 | .. versionadded:: 3.3 |
| 215 | |
Georg Brandl | 909f5bc | 2012-03-29 09:18:14 +0200 | [diff] [blame] | 216 | |
Victor Stinner | c29b585 | 2017-11-02 07:28:27 -0700 | [diff] [blame] | 217 | .. function:: clock_settime_ns(clk_id, time: int) |
| 218 | |
| 219 | Similar to :func:`clock_settime` but set time with nanoseconds. |
| 220 | |
| 221 | Availability: Unix. |
| 222 | |
| 223 | .. versionadded:: 3.7 |
| 224 | |
| 225 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 226 | .. function:: ctime([secs]) |
| 227 | |
| 228 | Convert a time expressed in seconds since the epoch to a string representing |
| 229 | local time. If *secs* is not provided or :const:`None`, the current time as |
Petri Lehtinen | 1033b31 | 2012-05-18 21:19:17 +0300 | [diff] [blame] | 230 | returned by :func:`.time` is used. ``ctime(secs)`` is equivalent to |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 231 | ``asctime(localtime(secs))``. Locale information is not used by :func:`ctime`. |
| 232 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 233 | |
Victor Stinner | ec89539 | 2012-04-29 02:41:27 +0200 | [diff] [blame] | 234 | .. function:: get_clock_info(name) |
| 235 | |
Victor Stinner | bda4b88 | 2012-06-12 22:11:44 +0200 | [diff] [blame] | 236 | Get information on the specified clock as a namespace object. |
Georg Brandl | 514880c | 2012-04-30 12:50:30 +0200 | [diff] [blame] | 237 | Supported clock names and the corresponding functions to read their value |
| 238 | are: |
Victor Stinner | ec89539 | 2012-04-29 02:41:27 +0200 | [diff] [blame] | 239 | |
Georg Brandl | 514880c | 2012-04-30 12:50:30 +0200 | [diff] [blame] | 240 | * ``'clock'``: :func:`time.clock` |
| 241 | * ``'monotonic'``: :func:`time.monotonic` |
| 242 | * ``'perf_counter'``: :func:`time.perf_counter` |
| 243 | * ``'process_time'``: :func:`time.process_time` |
Antoine Pitrou | 4bd41c9 | 2017-11-15 22:52:21 +0100 | [diff] [blame] | 244 | * ``'thread_time'``: :func:`time.thread_time` |
Georg Brandl | 514880c | 2012-04-30 12:50:30 +0200 | [diff] [blame] | 245 | * ``'time'``: :func:`time.time` |
Victor Stinner | ec89539 | 2012-04-29 02:41:27 +0200 | [diff] [blame] | 246 | |
Victor Stinner | bda4b88 | 2012-06-12 22:11:44 +0200 | [diff] [blame] | 247 | The result has the following attributes: |
| 248 | |
Victor Stinner | 2b89fdf | 2012-06-12 22:46:37 +0200 | [diff] [blame] | 249 | - *adjustable*: ``True`` if the clock can be changed automatically (e.g. by |
| 250 | a NTP daemon) or manually by the system administrator, ``False`` otherwise |
Victor Stinner | bda4b88 | 2012-06-12 22:11:44 +0200 | [diff] [blame] | 251 | - *implementation*: The name of the underlying C function used to get |
Cheryl Sabella | 703ff38 | 2017-10-11 09:29:14 -0400 | [diff] [blame] | 252 | the clock value. Refer to :ref:`time-clock-id-constants` for possible values. |
Victor Stinner | bda4b88 | 2012-06-12 22:11:44 +0200 | [diff] [blame] | 253 | - *monotonic*: ``True`` if the clock cannot go backward, |
| 254 | ``False`` otherwise |
| 255 | - *resolution*: The resolution of the clock in seconds (:class:`float`) |
| 256 | |
Victor Stinner | ec89539 | 2012-04-29 02:41:27 +0200 | [diff] [blame] | 257 | .. versionadded:: 3.3 |
| 258 | |
| 259 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 260 | .. function:: gmtime([secs]) |
| 261 | |
| 262 | Convert a time expressed in seconds since the epoch to a :class:`struct_time` in |
| 263 | UTC in which the dst flag is always zero. If *secs* is not provided or |
Petri Lehtinen | 1033b31 | 2012-05-18 21:19:17 +0300 | [diff] [blame] | 264 | :const:`None`, the current time as returned by :func:`.time` is used. Fractions |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 265 | of a second are ignored. See above for a description of the |
| 266 | :class:`struct_time` object. See :func:`calendar.timegm` for the inverse of this |
| 267 | function. |
| 268 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 269 | |
| 270 | .. function:: localtime([secs]) |
| 271 | |
| 272 | Like :func:`gmtime` but converts to local time. If *secs* is not provided or |
Petri Lehtinen | 1033b31 | 2012-05-18 21:19:17 +0300 | [diff] [blame] | 273 | :const:`None`, the current time as returned by :func:`.time` is used. The dst |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 274 | flag is set to ``1`` when DST applies to the given time. |
| 275 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 276 | |
Victor Stinner | 4195b5c | 2012-02-08 23:03:19 +0100 | [diff] [blame] | 277 | .. function:: mktime(t) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 278 | |
| 279 | This is the inverse function of :func:`localtime`. Its argument is the |
| 280 | :class:`struct_time` or full 9-tuple (since the dst flag is needed; use ``-1`` |
| 281 | as the dst flag if it is unknown) which expresses the time in *local* time, not |
Petri Lehtinen | 1033b31 | 2012-05-18 21:19:17 +0300 | [diff] [blame] | 282 | UTC. It returns a floating point number, for compatibility with :func:`.time`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 283 | If the input value cannot be represented as a valid time, either |
| 284 | :exc:`OverflowError` or :exc:`ValueError` will be raised (which depends on |
| 285 | whether the invalid value is caught by Python or the underlying C libraries). |
| 286 | The earliest date for which it can generate a time is platform-dependent. |
| 287 | |
| 288 | |
Victor Stinner | c29b585 | 2017-11-02 07:28:27 -0700 | [diff] [blame] | 289 | .. function:: monotonic() -> float |
Victor Stinner | 8b30201 | 2012-02-07 23:29:46 +0100 | [diff] [blame] | 290 | |
Georg Brandl | 514880c | 2012-04-30 12:50:30 +0200 | [diff] [blame] | 291 | Return the value (in fractional seconds) of a monotonic clock, i.e. a clock |
| 292 | that cannot go backwards. The clock is not affected by system clock updates. |
| 293 | The reference point of the returned value is undefined, so that only the |
| 294 | difference between the results of consecutive calls is valid. |
Victor Stinner | ec919cc | 2012-03-15 00:58:32 +0100 | [diff] [blame] | 295 | |
Victor Stinner | ec89539 | 2012-04-29 02:41:27 +0200 | [diff] [blame] | 296 | On Windows versions older than Vista, :func:`monotonic` detects |
Georg Brandl | 514880c | 2012-04-30 12:50:30 +0200 | [diff] [blame] | 297 | :c:func:`GetTickCount` integer overflow (32 bits, roll-over after 49.7 days). |
Ezio Melotti | 99bafff | 2012-11-05 22:22:48 +0200 | [diff] [blame] | 298 | It increases an internal epoch (reference time) by 2\ :sup:`32` each time |
Georg Brandl | 514880c | 2012-04-30 12:50:30 +0200 | [diff] [blame] | 299 | that an overflow is detected. The epoch is stored in the process-local state |
| 300 | and so the value of :func:`monotonic` may be different in two Python |
Victor Stinner | ec89539 | 2012-04-29 02:41:27 +0200 | [diff] [blame] | 301 | processes running for more than 49 days. On more recent versions of Windows |
| 302 | and on other operating systems, :func:`monotonic` is system-wide. |
Victor Stinner | 8b30201 | 2012-02-07 23:29:46 +0100 | [diff] [blame] | 303 | |
Victor Stinner | ec89539 | 2012-04-29 02:41:27 +0200 | [diff] [blame] | 304 | .. versionadded:: 3.3 |
Victor Stinner | ae58649 | 2014-09-02 23:18:25 +0200 | [diff] [blame] | 305 | .. versionchanged:: 3.5 |
| 306 | The function is now always available. |
Victor Stinner | ec89539 | 2012-04-29 02:41:27 +0200 | [diff] [blame] | 307 | |
| 308 | |
Victor Stinner | c29b585 | 2017-11-02 07:28:27 -0700 | [diff] [blame] | 309 | .. function:: monotonic_ns() -> int |
| 310 | |
| 311 | Similar to :func:`monotonic`, but return time as nanoseconds. |
| 312 | |
| 313 | .. versionadded:: 3.7 |
| 314 | |
| 315 | .. function:: perf_counter() -> float |
Victor Stinner | ec89539 | 2012-04-29 02:41:27 +0200 | [diff] [blame] | 316 | |
Victor Stinner | 884d13a | 2017-10-17 14:46:45 -0700 | [diff] [blame] | 317 | .. index:: |
| 318 | single: benchmarking |
| 319 | |
Georg Brandl | 514880c | 2012-04-30 12:50:30 +0200 | [diff] [blame] | 320 | Return the value (in fractional seconds) of a performance counter, i.e. a |
| 321 | clock with the highest available resolution to measure a short duration. It |
| 322 | does include time elapsed during sleep and is system-wide. The reference |
| 323 | point of the returned value is undefined, so that only the difference between |
| 324 | the results of consecutive calls is valid. |
Victor Stinner | ec89539 | 2012-04-29 02:41:27 +0200 | [diff] [blame] | 325 | |
| 326 | .. versionadded:: 3.3 |
| 327 | |
Victor Stinner | c29b585 | 2017-11-02 07:28:27 -0700 | [diff] [blame] | 328 | .. function:: perf_counter_ns() -> int |
Victor Stinner | ec89539 | 2012-04-29 02:41:27 +0200 | [diff] [blame] | 329 | |
Victor Stinner | c29b585 | 2017-11-02 07:28:27 -0700 | [diff] [blame] | 330 | Similar to :func:`perf_counter`, but return time as nanoseconds. |
| 331 | |
| 332 | .. versionadded:: 3.7 |
| 333 | |
| 334 | |
| 335 | .. function:: process_time() -> float |
Victor Stinner | ec89539 | 2012-04-29 02:41:27 +0200 | [diff] [blame] | 336 | |
Victor Stinner | 884d13a | 2017-10-17 14:46:45 -0700 | [diff] [blame] | 337 | .. index:: |
| 338 | single: CPU time |
| 339 | single: processor time |
| 340 | single: benchmarking |
| 341 | |
Georg Brandl | 514880c | 2012-04-30 12:50:30 +0200 | [diff] [blame] | 342 | Return the value (in fractional seconds) of the sum of the system and user |
| 343 | CPU time of the current process. It does not include time elapsed during |
| 344 | sleep. It is process-wide by definition. The reference point of the |
| 345 | returned value is undefined, so that only the difference between the results |
| 346 | of consecutive calls is valid. |
Victor Stinner | 071eca3 | 2012-03-15 01:17:09 +0100 | [diff] [blame] | 347 | |
Victor Stinner | 0f7888d | 2012-02-14 02:42:21 +0100 | [diff] [blame] | 348 | .. versionadded:: 3.3 |
Victor Stinner | 8b30201 | 2012-02-07 23:29:46 +0100 | [diff] [blame] | 349 | |
Victor Stinner | c29b585 | 2017-11-02 07:28:27 -0700 | [diff] [blame] | 350 | .. function:: process_time_ns() -> int |
| 351 | |
| 352 | Similar to :func:`process_time` but return time as nanoseconds. |
| 353 | |
| 354 | .. versionadded:: 3.7 |
| 355 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 356 | .. function:: sleep(secs) |
| 357 | |
R David Murray | f1f9675 | 2015-01-25 15:45:14 -0500 | [diff] [blame] | 358 | Suspend execution of the calling thread for the given number of seconds. |
R David Murray | 1923b62 | 2015-01-25 15:46:22 -0500 | [diff] [blame] | 359 | The argument may be a floating point number to indicate a more precise sleep |
| 360 | time. The actual suspension time may be less than that requested because any |
| 361 | caught signal will terminate the :func:`sleep` following execution of that |
| 362 | signal's catching routine. Also, the suspension time may be longer than |
| 363 | requested by an arbitrary amount because of the scheduling of other activity |
| 364 | in the system. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 365 | |
Victor Stinner | 79d68f9 | 2015-03-19 21:54:09 +0100 | [diff] [blame] | 366 | .. versionchanged:: 3.5 |
| 367 | The function now sleeps at least *secs* even if the sleep is interrupted |
| 368 | by a signal, except if the signal handler raises an exception (see |
| 369 | :pep:`475` for the rationale). |
| 370 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 371 | |
| 372 | .. function:: strftime(format[, t]) |
| 373 | |
| 374 | Convert a tuple or :class:`struct_time` representing a time as returned by |
| 375 | :func:`gmtime` or :func:`localtime` to a string as specified by the *format* |
| 376 | argument. If *t* is not provided, the current time as returned by |
| 377 | :func:`localtime` is used. *format* must be a string. :exc:`ValueError` is |
| 378 | raised if any field in *t* is outside of the allowed range. |
| 379 | |
Georg Brandl | 55ac8f0 | 2007-09-01 13:51:09 +0000 | [diff] [blame] | 380 | 0 is a legal argument for any position in the time tuple; if it is normally |
| 381 | illegal the value is forced to a correct one. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 382 | |
| 383 | The following directives can be embedded in the *format* string. They are shown |
| 384 | without the optional field width and precision specification, and are replaced |
| 385 | by the indicated characters in the :func:`strftime` result: |
| 386 | |
Georg Brandl | 55ac8f0 | 2007-09-01 13:51:09 +0000 | [diff] [blame] | 387 | +-----------+------------------------------------------------+-------+ |
| 388 | | Directive | Meaning | Notes | |
| 389 | +===========+================================================+=======+ |
| 390 | | ``%a`` | Locale's abbreviated weekday name. | | |
| 391 | | | | | |
| 392 | +-----------+------------------------------------------------+-------+ |
| 393 | | ``%A`` | Locale's full weekday name. | | |
| 394 | +-----------+------------------------------------------------+-------+ |
| 395 | | ``%b`` | Locale's abbreviated month name. | | |
| 396 | | | | | |
| 397 | +-----------+------------------------------------------------+-------+ |
| 398 | | ``%B`` | Locale's full month name. | | |
| 399 | +-----------+------------------------------------------------+-------+ |
| 400 | | ``%c`` | Locale's appropriate date and time | | |
| 401 | | | representation. | | |
| 402 | +-----------+------------------------------------------------+-------+ |
| 403 | | ``%d`` | Day of the month as a decimal number [01,31]. | | |
| 404 | | | | | |
| 405 | +-----------+------------------------------------------------+-------+ |
| 406 | | ``%H`` | Hour (24-hour clock) as a decimal number | | |
| 407 | | | [00,23]. | | |
| 408 | +-----------+------------------------------------------------+-------+ |
| 409 | | ``%I`` | Hour (12-hour clock) as a decimal number | | |
| 410 | | | [01,12]. | | |
| 411 | +-----------+------------------------------------------------+-------+ |
| 412 | | ``%j`` | Day of the year as a decimal number [001,366]. | | |
| 413 | | | | | |
| 414 | +-----------+------------------------------------------------+-------+ |
| 415 | | ``%m`` | Month as a decimal number [01,12]. | | |
| 416 | | | | | |
| 417 | +-----------+------------------------------------------------+-------+ |
| 418 | | ``%M`` | Minute as a decimal number [00,59]. | | |
| 419 | | | | | |
| 420 | +-----------+------------------------------------------------+-------+ |
| 421 | | ``%p`` | Locale's equivalent of either AM or PM. | \(1) | |
| 422 | | | | | |
| 423 | +-----------+------------------------------------------------+-------+ |
| 424 | | ``%S`` | Second as a decimal number [00,61]. | \(2) | |
| 425 | | | | | |
| 426 | +-----------+------------------------------------------------+-------+ |
| 427 | | ``%U`` | Week number of the year (Sunday as the first | \(3) | |
| 428 | | | day of the week) as a decimal number [00,53]. | | |
| 429 | | | All days in a new year preceding the first | | |
| 430 | | | Sunday are considered to be in week 0. | | |
| 431 | | | | | |
| 432 | | | | | |
| 433 | | | | | |
| 434 | +-----------+------------------------------------------------+-------+ |
| 435 | | ``%w`` | Weekday as a decimal number [0(Sunday),6]. | | |
| 436 | | | | | |
| 437 | +-----------+------------------------------------------------+-------+ |
| 438 | | ``%W`` | Week number of the year (Monday as the first | \(3) | |
| 439 | | | day of the week) as a decimal number [00,53]. | | |
| 440 | | | All days in a new year preceding the first | | |
| 441 | | | Monday are considered to be in week 0. | | |
| 442 | | | | | |
| 443 | | | | | |
| 444 | | | | | |
| 445 | +-----------+------------------------------------------------+-------+ |
| 446 | | ``%x`` | Locale's appropriate date representation. | | |
| 447 | | | | | |
| 448 | +-----------+------------------------------------------------+-------+ |
| 449 | | ``%X`` | Locale's appropriate time representation. | | |
| 450 | | | | | |
| 451 | +-----------+------------------------------------------------+-------+ |
| 452 | | ``%y`` | Year without century as a decimal number | | |
| 453 | | | [00,99]. | | |
| 454 | +-----------+------------------------------------------------+-------+ |
Alexander Belopolsky | 03163ac | 2011-05-02 12:20:52 -0400 | [diff] [blame] | 455 | | ``%Y`` | Year with century as a decimal number. | | |
Georg Brandl | 55ac8f0 | 2007-09-01 13:51:09 +0000 | [diff] [blame] | 456 | | | | | |
| 457 | +-----------+------------------------------------------------+-------+ |
Alexander Belopolsky | c142bba | 2012-06-13 22:15:26 -0400 | [diff] [blame] | 458 | | ``%z`` | Time zone offset indicating a positive or | | |
| 459 | | | negative time difference from UTC/GMT of the | | |
| 460 | | | form +HHMM or -HHMM, where H represents decimal| | |
| 461 | | | hour digits and M represents decimal minute | | |
| 462 | | | digits [-23:59, +23:59]. | | |
| 463 | +-----------+------------------------------------------------+-------+ |
Georg Brandl | 55ac8f0 | 2007-09-01 13:51:09 +0000 | [diff] [blame] | 464 | | ``%Z`` | Time zone name (no characters if no time zone | | |
| 465 | | | exists). | | |
| 466 | +-----------+------------------------------------------------+-------+ |
| 467 | | ``%%`` | A literal ``'%'`` character. | | |
| 468 | +-----------+------------------------------------------------+-------+ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 469 | |
| 470 | Notes: |
| 471 | |
| 472 | (1) |
| 473 | When used with the :func:`strptime` function, the ``%p`` directive only affects |
| 474 | the output hour field if the ``%I`` directive is used to parse the hour. |
| 475 | |
| 476 | (2) |
Alexander Belopolsky | 9971e00 | 2011-01-10 22:56:14 +0000 | [diff] [blame] | 477 | The range really is ``0`` to ``61``; value ``60`` is valid in |
Eric Appelt | 23557d5 | 2017-02-16 05:00:45 -0500 | [diff] [blame] | 478 | timestamps representing `leap seconds`_ and value ``61`` is supported |
Alexander Belopolsky | 9971e00 | 2011-01-10 22:56:14 +0000 | [diff] [blame] | 479 | for historical reasons. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 480 | |
| 481 | (3) |
| 482 | When used with the :func:`strptime` function, ``%U`` and ``%W`` are only used in |
| 483 | calculations when the day of the week and the year are specified. |
| 484 | |
| 485 | Here is an example, a format for dates compatible with that specified in the |
| 486 | :rfc:`2822` Internet email standard. [#]_ :: |
| 487 | |
| 488 | >>> from time import gmtime, strftime |
| 489 | >>> strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime()) |
| 490 | 'Thu, 28 Jun 2001 14:17:15 +0000' |
| 491 | |
Georg Brandl | b7117af | 2013-10-13 18:28:25 +0200 | [diff] [blame] | 492 | Additional directives may be supported on certain platforms, but only the |
| 493 | ones listed here have a meaning standardized by ANSI C. To see the full set |
| 494 | of format codes supported on your platform, consult the :manpage:`strftime(3)` |
| 495 | documentation. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 496 | |
| 497 | On some platforms, an optional field width and precision specification can |
| 498 | immediately follow the initial ``'%'`` of a directive in the following order; |
| 499 | this is also not portable. The field width is normally 2 except for ``%j`` where |
| 500 | it is 3. |
| 501 | |
| 502 | |
| 503 | .. function:: strptime(string[, format]) |
| 504 | |
Brett Cannon | 7f6b4f8 | 2009-03-30 21:30:26 +0000 | [diff] [blame] | 505 | Parse a string representing a time according to a format. The return value |
| 506 | is a :class:`struct_time` as returned by :func:`gmtime` or |
| 507 | :func:`localtime`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 508 | |
| 509 | The *format* parameter uses the same directives as those used by |
| 510 | :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] | 511 | formatting returned by :func:`ctime`. If *string* cannot be parsed according |
| 512 | to *format*, or if it has excess data after parsing, :exc:`ValueError` is |
| 513 | raised. The default values used to fill in any missing data when more |
| 514 | accurate values cannot be inferred are ``(1900, 1, 1, 0, 0, 0, 0, 1, -1)``. |
| 515 | Both *string* and *format* must be strings. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 516 | |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 517 | For example: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 518 | |
| 519 | >>> import time |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 520 | >>> time.strptime("30 Nov 00", "%d %b %y") # doctest: +NORMALIZE_WHITESPACE |
| 521 | time.struct_time(tm_year=2000, tm_mon=11, tm_mday=30, tm_hour=0, tm_min=0, |
| 522 | tm_sec=0, tm_wday=3, tm_yday=335, tm_isdst=-1) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 523 | |
| 524 | Support for the ``%Z`` directive is based on the values contained in ``tzname`` |
| 525 | and whether ``daylight`` is true. Because of this, it is platform-specific |
| 526 | except for recognizing UTC and GMT which are always known (and are considered to |
| 527 | be non-daylight savings timezones). |
| 528 | |
| 529 | Only the directives specified in the documentation are supported. Because |
| 530 | ``strftime()`` is implemented per platform it can sometimes offer more |
| 531 | directives than those listed. But ``strptime()`` is independent of any platform |
| 532 | and thus does not necessarily support all directives available that are not |
| 533 | documented as supported. |
| 534 | |
| 535 | |
Georg Brandl | b67878a | 2010-10-15 17:01:15 +0000 | [diff] [blame] | 536 | .. class:: struct_time |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 537 | |
| 538 | The type of the time value sequence returned by :func:`gmtime`, |
Georg Brandl | b67878a | 2010-10-15 17:01:15 +0000 | [diff] [blame] | 539 | :func:`localtime`, and :func:`strptime`. It is an object with a :term:`named |
| 540 | tuple` interface: values can be accessed by index and by attribute name. The |
| 541 | following values are present: |
| 542 | |
| 543 | +-------+-------------------+---------------------------------+ |
| 544 | | Index | Attribute | Values | |
| 545 | +=======+===================+=================================+ |
| 546 | | 0 | :attr:`tm_year` | (for example, 1993) | |
| 547 | +-------+-------------------+---------------------------------+ |
| 548 | | 1 | :attr:`tm_mon` | range [1, 12] | |
| 549 | +-------+-------------------+---------------------------------+ |
| 550 | | 2 | :attr:`tm_mday` | range [1, 31] | |
| 551 | +-------+-------------------+---------------------------------+ |
| 552 | | 3 | :attr:`tm_hour` | range [0, 23] | |
| 553 | +-------+-------------------+---------------------------------+ |
| 554 | | 4 | :attr:`tm_min` | range [0, 59] | |
| 555 | +-------+-------------------+---------------------------------+ |
Alexander Belopolsky | 04da1e0 | 2011-01-10 19:14:38 +0000 | [diff] [blame] | 556 | | 5 | :attr:`tm_sec` | range [0, 61]; see **(2)** in | |
Georg Brandl | b67878a | 2010-10-15 17:01:15 +0000 | [diff] [blame] | 557 | | | | :func:`strftime` description | |
| 558 | +-------+-------------------+---------------------------------+ |
| 559 | | 6 | :attr:`tm_wday` | range [0, 6], Monday is 0 | |
| 560 | +-------+-------------------+---------------------------------+ |
| 561 | | 7 | :attr:`tm_yday` | range [1, 366] | |
| 562 | +-------+-------------------+---------------------------------+ |
| 563 | | 8 | :attr:`tm_isdst` | 0, 1 or -1; see below | |
| 564 | +-------+-------------------+---------------------------------+ |
Alexander Belopolsky | c142bba | 2012-06-13 22:15:26 -0400 | [diff] [blame] | 565 | | N/A | :attr:`tm_zone` | abbreviation of timezone name | |
| 566 | +-------+-------------------+---------------------------------+ |
Alexander Belopolsky | 93c9cd0 | 2012-06-22 16:04:19 -0400 | [diff] [blame] | 567 | | N/A | :attr:`tm_gmtoff` | offset east of UTC in seconds | |
Alexander Belopolsky | c142bba | 2012-06-13 22:15:26 -0400 | [diff] [blame] | 568 | +-------+-------------------+---------------------------------+ |
Georg Brandl | b67878a | 2010-10-15 17:01:15 +0000 | [diff] [blame] | 569 | |
| 570 | Note that unlike the C structure, the month value is a range of [1, 12], not |
Senthil Kumaran | a880800 | 2016-01-03 00:40:03 -0800 | [diff] [blame] | 571 | [0, 11]. |
| 572 | |
| 573 | In calls to :func:`mktime`, :attr:`tm_isdst` may be set to 1 when daylight |
| 574 | savings time is in effect, and 0 when it is not. A value of -1 indicates that |
| 575 | this is not known, and will usually result in the correct state being filled in. |
Georg Brandl | b67878a | 2010-10-15 17:01:15 +0000 | [diff] [blame] | 576 | |
| 577 | When a tuple with an incorrect length is passed to a function expecting a |
| 578 | :class:`struct_time`, or having elements of the wrong type, a |
| 579 | :exc:`TypeError` is raised. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 580 | |
Victor Stinner | c29b585 | 2017-11-02 07:28:27 -0700 | [diff] [blame] | 581 | .. function:: time() -> float |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 582 | |
Eric Appelt | 23557d5 | 2017-02-16 05:00:45 -0500 | [diff] [blame] | 583 | Return the time in seconds since the epoch_ as a floating point |
| 584 | number. The specific date of the epoch and the handling of |
| 585 | `leap seconds`_ is platform dependent. |
| 586 | On Windows and most Unix systems, the epoch is January 1, 1970, |
| 587 | 00:00:00 (UTC) and leap seconds are not counted towards the time |
| 588 | in seconds since the epoch. This is commonly referred to as |
| 589 | `Unix time <https://en.wikipedia.org/wiki/Unix_time>`_. |
| 590 | To find out what the epoch is on a given platform, look at |
| 591 | ``gmtime(0)``. |
| 592 | |
R David Murray | 38c2754 | 2012-03-15 03:06:15 -0400 | [diff] [blame] | 593 | Note that even though the time is always returned as a floating point |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 594 | number, not all systems provide time with a better precision than 1 second. |
| 595 | While this function normally returns non-decreasing values, it can return a |
Eric Appelt | 23557d5 | 2017-02-16 05:00:45 -0500 | [diff] [blame] | 596 | lower value than a previous call if the system clock has been set back |
| 597 | between the two calls. |
| 598 | |
| 599 | The number returned by :func:`.time` may be converted into a more common |
| 600 | time format (i.e. year, month, day, hour, etc...) in UTC by passing it to |
| 601 | :func:`gmtime` function or in local time by passing it to the |
| 602 | :func:`localtime` function. In both cases a |
| 603 | :class:`struct_time` object is returned, from which the components |
| 604 | of the calendar date may be accessed as attributes. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 605 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 606 | |
Antoine Pitrou | 4bd41c9 | 2017-11-15 22:52:21 +0100 | [diff] [blame] | 607 | .. function:: thread_time() -> float |
| 608 | |
| 609 | .. index:: |
| 610 | single: CPU time |
| 611 | single: processor time |
| 612 | single: benchmarking |
| 613 | |
| 614 | Return the value (in fractional seconds) of the sum of the system and user |
| 615 | CPU time of the current thread. It does not include time elapsed during |
| 616 | sleep. It is thread-specific by definition. The reference point of the |
| 617 | returned value is undefined, so that only the difference between the results |
| 618 | of consecutive calls in the same thread is valid. |
| 619 | |
| 620 | Availability: Windows, Linux, Unix systems supporting |
| 621 | ``CLOCK_THREAD_CPUTIME_ID``. |
| 622 | |
| 623 | .. versionadded:: 3.7 |
| 624 | |
| 625 | |
| 626 | .. function:: thread_time_ns() -> int |
| 627 | |
| 628 | Similar to :func:`thread_time` but return time as nanoseconds. |
| 629 | |
| 630 | .. versionadded:: 3.7 |
| 631 | |
| 632 | |
Victor Stinner | c29b585 | 2017-11-02 07:28:27 -0700 | [diff] [blame] | 633 | .. function:: time_ns() -> int |
| 634 | |
| 635 | Similar to :func:`time` but returns time as an integer number of nanoseconds |
| 636 | since the epoch_. |
| 637 | |
| 638 | .. versionadded:: 3.7 |
| 639 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 640 | .. function:: tzset() |
| 641 | |
Alexander Belopolsky | f810d04 | 2017-01-12 13:17:23 -0500 | [diff] [blame] | 642 | Reset the time conversion rules used by the library routines. The environment |
| 643 | variable :envvar:`TZ` specifies how this is done. It will also set the variables |
| 644 | ``tzname`` (from the :envvar:`TZ` environment variable), ``timezone`` (non-DST |
| 645 | seconds West of UTC), ``altzone`` (DST seconds west of UTC) and ``daylight`` |
| 646 | (to 0 if this timezone does not have any daylight saving time rules, or to |
| 647 | nonzero if there is a time, past, present or future when daylight saving time |
| 648 | applies). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 649 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 650 | Availability: Unix. |
| 651 | |
| 652 | .. note:: |
| 653 | |
| 654 | Although in many cases, changing the :envvar:`TZ` environment variable may |
| 655 | affect the output of functions like :func:`localtime` without calling |
| 656 | :func:`tzset`, this behavior should not be relied on. |
| 657 | |
| 658 | The :envvar:`TZ` environment variable should contain no whitespace. |
| 659 | |
| 660 | The standard format of the :envvar:`TZ` environment variable is (whitespace |
| 661 | added for clarity):: |
| 662 | |
| 663 | std offset [dst [offset [,start[/time], end[/time]]]] |
| 664 | |
| 665 | Where the components are: |
| 666 | |
| 667 | ``std`` and ``dst`` |
| 668 | Three or more alphanumerics giving the timezone abbreviations. These will be |
| 669 | propagated into time.tzname |
| 670 | |
| 671 | ``offset`` |
| 672 | The offset has the form: ``± hh[:mm[:ss]]``. This indicates the value |
| 673 | added the local time to arrive at UTC. If preceded by a '-', the timezone |
| 674 | is east of the Prime Meridian; otherwise, it is west. If no offset follows |
| 675 | dst, summer time is assumed to be one hour ahead of standard time. |
| 676 | |
| 677 | ``start[/time], end[/time]`` |
| 678 | Indicates when to change to and back from DST. The format of the |
| 679 | start and end dates are one of the following: |
| 680 | |
| 681 | :samp:`J{n}` |
| 682 | The Julian day *n* (1 <= *n* <= 365). Leap days are not counted, so in |
| 683 | all years February 28 is day 59 and March 1 is day 60. |
| 684 | |
| 685 | :samp:`{n}` |
| 686 | The zero-based Julian day (0 <= *n* <= 365). Leap days are counted, and |
| 687 | it is possible to refer to February 29. |
| 688 | |
| 689 | :samp:`M{m}.{n}.{d}` |
Alexander Belopolsky | 357cb98 | 2015-08-28 16:56:45 -0400 | [diff] [blame] | 690 | The *d*'th day (0 <= *d* <= 6) of week *n* of month *m* of the year (1 |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 691 | <= *n* <= 5, 1 <= *m* <= 12, where week 5 means "the last *d* day in |
| 692 | month *m*" which may occur in either the fourth or the fifth |
| 693 | week). Week 1 is the first week in which the *d*'th day occurs. Day |
Alexander Belopolsky | 357cb98 | 2015-08-28 16:56:45 -0400 | [diff] [blame] | 694 | zero is a Sunday. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 695 | |
| 696 | ``time`` has the same format as ``offset`` except that no leading sign |
| 697 | ('-' or '+') is allowed. The default, if time is not given, is 02:00:00. |
| 698 | |
| 699 | :: |
| 700 | |
| 701 | >>> os.environ['TZ'] = 'EST+05EDT,M4.1.0,M10.5.0' |
| 702 | >>> time.tzset() |
| 703 | >>> time.strftime('%X %x %Z') |
| 704 | '02:07:36 05/08/03 EDT' |
| 705 | >>> os.environ['TZ'] = 'AEST-10AEDT-11,M10.5.0,M3.5.0' |
| 706 | >>> time.tzset() |
| 707 | >>> time.strftime('%X %x %Z') |
| 708 | '16:08:12 05/08/03 AEST' |
| 709 | |
| 710 | On many Unix systems (including \*BSD, Linux, Solaris, and Darwin), it is more |
| 711 | convenient to use the system's zoneinfo (:manpage:`tzfile(5)`) database to |
| 712 | specify the timezone rules. To do this, set the :envvar:`TZ` environment |
| 713 | variable to the path of the required timezone datafile, relative to the root of |
| 714 | the systems 'zoneinfo' timezone database, usually located at |
| 715 | :file:`/usr/share/zoneinfo`. For example, ``'US/Eastern'``, |
| 716 | ``'Australia/Melbourne'``, ``'Egypt'`` or ``'Europe/Amsterdam'``. :: |
| 717 | |
| 718 | >>> os.environ['TZ'] = 'US/Eastern' |
| 719 | >>> time.tzset() |
| 720 | >>> time.tzname |
| 721 | ('EST', 'EDT') |
| 722 | >>> os.environ['TZ'] = 'Egypt' |
| 723 | >>> time.tzset() |
| 724 | >>> time.tzname |
| 725 | ('EET', 'EEST') |
| 726 | |
| 727 | |
Cheryl Sabella | 703ff38 | 2017-10-11 09:29:14 -0400 | [diff] [blame] | 728 | .. _time-clock-id-constants: |
| 729 | |
| 730 | Clock ID Constants |
| 731 | ------------------ |
| 732 | |
| 733 | These constants are used as parameters for :func:`clock_getres` and |
| 734 | :func:`clock_gettime`. |
| 735 | |
Victor Stinner | a64ce97 | 2017-11-02 04:19:19 -0700 | [diff] [blame] | 736 | .. data:: CLOCK_BOOTTIME |
| 737 | |
| 738 | Identical to :data:`CLOCK_MONOTONIC`, except it also includes any time that |
| 739 | the system is suspended. |
| 740 | |
| 741 | This allows applications to get a suspend-aware monotonic clock without |
| 742 | having to deal with the complications of :data:`CLOCK_REALTIME`, which may |
| 743 | have discontinuities if the time is changed using ``settimeofday()`` or |
| 744 | similar. |
| 745 | |
| 746 | Availability: Linux 2.6.39 or later. |
| 747 | |
| 748 | .. versionadded:: 3.7 |
| 749 | |
| 750 | |
Cheryl Sabella | 703ff38 | 2017-10-11 09:29:14 -0400 | [diff] [blame] | 751 | .. data:: CLOCK_HIGHRES |
| 752 | |
| 753 | The Solaris OS has a ``CLOCK_HIGHRES`` timer that attempts to use an optimal |
| 754 | hardware source, and may give close to nanosecond resolution. |
| 755 | ``CLOCK_HIGHRES`` is the nonadjustable, high-resolution clock. |
| 756 | |
| 757 | Availability: Solaris. |
| 758 | |
| 759 | .. versionadded:: 3.3 |
| 760 | |
| 761 | |
| 762 | .. data:: CLOCK_MONOTONIC |
| 763 | |
| 764 | Clock that cannot be set and represents monotonic time since some unspecified |
| 765 | starting point. |
| 766 | |
| 767 | Availability: Unix. |
| 768 | |
| 769 | .. versionadded:: 3.3 |
| 770 | |
| 771 | |
| 772 | .. data:: CLOCK_MONOTONIC_RAW |
| 773 | |
| 774 | Similar to :data:`CLOCK_MONOTONIC`, but provides access to a raw |
| 775 | hardware-based time that is not subject to NTP adjustments. |
| 776 | |
| 777 | Availability: Linux 2.6.28 or later. |
| 778 | |
| 779 | .. versionadded:: 3.3 |
| 780 | |
| 781 | |
| 782 | .. data:: CLOCK_PROCESS_CPUTIME_ID |
| 783 | |
| 784 | High-resolution per-process timer from the CPU. |
| 785 | |
| 786 | Availability: Unix. |
| 787 | |
| 788 | .. versionadded:: 3.3 |
| 789 | |
| 790 | |
Victor Stinner | a64ce97 | 2017-11-02 04:19:19 -0700 | [diff] [blame] | 791 | .. data:: CLOCK_PROF |
| 792 | |
| 793 | High-resolution per-process timer from the CPU. |
| 794 | |
Victor Stinner | 13ff245 | 2018-01-22 18:32:50 +0100 | [diff] [blame] | 795 | Availability: FreeBSD, NetBSD 7 or later, OpenBSD. |
Victor Stinner | a64ce97 | 2017-11-02 04:19:19 -0700 | [diff] [blame] | 796 | |
| 797 | .. versionadded:: 3.7 |
| 798 | |
| 799 | |
Cheryl Sabella | 703ff38 | 2017-10-11 09:29:14 -0400 | [diff] [blame] | 800 | .. data:: CLOCK_THREAD_CPUTIME_ID |
| 801 | |
| 802 | Thread-specific CPU-time clock. |
| 803 | |
| 804 | Availability: Unix. |
| 805 | |
| 806 | .. versionadded:: 3.3 |
| 807 | |
| 808 | |
Victor Stinner | a64ce97 | 2017-11-02 04:19:19 -0700 | [diff] [blame] | 809 | .. data:: CLOCK_UPTIME |
| 810 | |
| 811 | Time whose absolute value is the time the system has been running and not |
| 812 | suspended, providing accurate uptime measurement, both absolute and |
| 813 | interval. |
| 814 | |
Victor Stinner | 13ff245 | 2018-01-22 18:32:50 +0100 | [diff] [blame] | 815 | Availability: FreeBSD, OpenBSD 5.5 or later. |
Victor Stinner | a64ce97 | 2017-11-02 04:19:19 -0700 | [diff] [blame] | 816 | |
| 817 | .. versionadded:: 3.7 |
| 818 | |
| 819 | |
Cheryl Sabella | 703ff38 | 2017-10-11 09:29:14 -0400 | [diff] [blame] | 820 | The following constant is the only parameter that can be sent to |
| 821 | :func:`clock_settime`. |
| 822 | |
| 823 | .. data:: CLOCK_REALTIME |
| 824 | |
| 825 | System-wide real-time clock. Setting this clock requires appropriate |
| 826 | privileges. |
| 827 | |
| 828 | Availability: Unix. |
| 829 | |
| 830 | .. versionadded:: 3.3 |
| 831 | |
| 832 | |
| 833 | .. _time-timezone-constants: |
| 834 | |
| 835 | Timezone Constants |
| 836 | ------------------- |
| 837 | |
| 838 | .. data:: altzone |
| 839 | |
| 840 | The offset of the local DST timezone, in seconds west of UTC, if one is defined. |
| 841 | This is negative if the local DST timezone is east of UTC (as in Western Europe, |
| 842 | including the UK). Only use this if ``daylight`` is nonzero. See note below. |
| 843 | |
| 844 | .. data:: daylight |
| 845 | |
| 846 | Nonzero if a DST timezone is defined. See note below. |
| 847 | |
| 848 | .. data:: timezone |
| 849 | |
| 850 | The offset of the local (non-DST) timezone, in seconds west of UTC (negative in |
| 851 | most of Western Europe, positive in the US, zero in the UK). See note below. |
| 852 | |
| 853 | .. data:: tzname |
| 854 | |
| 855 | A tuple of two strings: the first is the name of the local non-DST timezone, the |
| 856 | second is the name of the local DST timezone. If no DST timezone is defined, |
| 857 | the second string should not be used. See note below. |
| 858 | |
| 859 | .. note:: |
| 860 | |
| 861 | For the above Timezone constants (:data:`altzone`, :data:`daylight`, :data:`timezone`, |
| 862 | and :data:`tzname`), the value is determined by the timezone rules in effect |
| 863 | at module load time or the last time :func:`tzset` is called and may be incorrect |
| 864 | for times in the past. It is recommended to use the :attr:`tm_gmtoff` and |
| 865 | :attr:`tm_zone` results from :func:`localtime` to obtain timezone information. |
| 866 | |
| 867 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 868 | .. seealso:: |
| 869 | |
| 870 | Module :mod:`datetime` |
| 871 | More object-oriented interface to dates and times. |
| 872 | |
| 873 | Module :mod:`locale` |
Terry Jan Reedy | b5e2e7e | 2013-04-03 12:34:57 -0400 | [diff] [blame] | 874 | Internationalization services. The locale setting affects the interpretation |
Terry Jan Reedy | 41459a9 | 2013-04-03 12:45:24 -0400 | [diff] [blame] | 875 | of many format specifiers in :func:`strftime` and :func:`strptime`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 876 | |
| 877 | Module :mod:`calendar` |
Serhiy Storchaka | bfdcd43 | 2013-10-13 23:09:14 +0300 | [diff] [blame] | 878 | General calendar-related functions. :func:`~calendar.timegm` is the |
| 879 | inverse of :func:`gmtime` from this module. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 880 | |
| 881 | .. rubric:: Footnotes |
| 882 | |
| 883 | .. [#] The use of ``%Z`` is now deprecated, but the ``%z`` escape that expands to the |
| 884 | preferred hour/minute offset is not supported by all ANSI C libraries. Also, a |
| 885 | strict reading of the original 1982 :rfc:`822` standard calls for a two-digit |
| 886 | 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] | 887 | year 2000. After that, :rfc:`822` became obsolete and the 4-digit year has |
| 888 | been first recommended by :rfc:`1123` and then mandated by :rfc:`2822`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 889 | |