1
:mod:`time` --- Time access and conversions
2
===========================================
5
:synopsis: Time access and conversions.
8
This module provides various time-related functions. For related
9
functionality, see also the :mod:`datetime` and :mod:`calendar` modules.
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.
17
An explanation of some terminology and conventions is in order.
19
.. index:: single: epoch
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)``.
25
.. index:: single: Year 2038
27
* The functions in this module may not handle dates and times before the epoch or
28
far in the future. The cut-off point in the future is determined by the C
29
library; for 32-bit systems, it is typically in 2038.
37
* **Year 2000 (Y2K) issues**: Python depends on the platform's C library, which
38
generally doesn't have year 2000 issues, since all dates and times are
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.
46
single: Coordinated Universal Time
47
single: Greenwich Mean Time
49
* UTC is Coordinated Universal Time (formerly known as Greenwich Mean Time, or
50
GMT). The acronym UTC is not a mistake but a compromise between English and
53
.. index:: single: Daylight Saving Time
55
* DST is Daylight Saving Time, an adjustment of the timezone by (usually) one
56
hour during part of the year. DST rules are magic (determined by local law) and
57
can change from year to year. The C library has a table containing the local
58
rules (often it is read from a system file for flexibility) and is the only
59
source of True Wisdom in this respect.
61
* The precision of the various real-time functions may be less than suggested by
62
the units in which their value or argument is expressed. E.g. on most Unix
63
systems, the clock "ticks" only 50 or 100 times a second.
65
* On the other hand, the precision of :func:`.time` and :func:`sleep` is better
66
than their Unix equivalents: times are expressed as floating point numbers,
67
:func:`.time` returns the most accurate time available (using Unix
68
:c:func:`gettimeofday` where available), and :func:`sleep` will accept a time
69
with a nonzero fraction (Unix :c:func:`select` is used to implement this, where
72
* The time value as returned by :func:`gmtime`, :func:`localtime`, and
73
:func:`strptime`, and accepted by :func:`asctime`, :func:`mktime` and
74
:func:`strftime`, is a sequence of 9 integers. The return values of
75
:func:`gmtime`, :func:`localtime`, and :func:`strptime` also offer attribute
76
names for individual fields.
78
See :class:`struct_time` for a description of these objects.
80
.. versionchanged:: 3.3
81
The :class:`struct_time` type was extended to provide the :attr:`tm_gmtoff`
82
and :attr:`tm_zone` attributes when platform supports corresponding
83
``struct tm`` members.
85
* Use the following functions to convert between time representations:
87
+-------------------------+-------------------------+-------------------------+
89
+=========================+=========================+=========================+
90
| seconds since the epoch | :class:`struct_time` in | :func:`gmtime` |
92
+-------------------------+-------------------------+-------------------------+
93
| seconds since the epoch | :class:`struct_time` in | :func:`localtime` |
95
+-------------------------+-------------------------+-------------------------+
96
| :class:`struct_time` in | seconds since the epoch | :func:`calendar.timegm` |
98
+-------------------------+-------------------------+-------------------------+
99
| :class:`struct_time` in | seconds since the epoch | :func:`mktime` |
101
+-------------------------+-------------------------+-------------------------+
104
The module defines the following functions and data items:
108
The offset of the local DST timezone, in seconds west of UTC, if one is defined.
109
This is negative if the local DST timezone is east of UTC (as in Western Europe,
110
including the UK). Only use this if ``daylight`` is nonzero.
113
.. function:: asctime([t])
115
Convert a tuple or :class:`struct_time` representing a time as returned by
116
:func:`gmtime` or :func:`localtime` to a string of the following
117
form: ``'Sun Jun 20 23:21:05 1993'``. If *t* is not provided, the current time
118
as returned by :func:`localtime` is used. Locale information is not used by
123
Unlike the C function of the same name, :func:`asctime` does not add a
127
.. function:: clock()
131
single: processor time
134
On Unix, return the current processor time as a floating point number expressed
135
in seconds. The precision, and in fact the very definition of the meaning of
136
"processor time", depends on that of the C function of the same name.
138
On Windows, this function returns wall-clock seconds elapsed since the first
139
call to this function, as a floating point number, based on the Win32 function
140
:c:func:`QueryPerformanceCounter`. The resolution is typically better than one
144
The behaviour of this function depends on the platform: use
145
:func:`perf_counter` or :func:`process_time` instead, depending on your
146
requirements, to have a well defined behaviour.
149
.. function:: clock_getres(clk_id)
151
Return the resolution (precision) of the specified clock *clk_id*.
155
.. versionadded:: 3.3
158
.. function:: clock_gettime(clk_id)
160
Return the time of the specified clock *clk_id*.
164
.. versionadded:: 3.3
167
.. function:: clock_settime(clk_id, time)
169
Set the time of the specified clock *clk_id*.
173
.. versionadded:: 3.3
176
.. data:: CLOCK_HIGHRES
178
The Solaris OS has a CLOCK_HIGHRES timer that attempts to use an optimal
179
hardware source, and may give close to nanosecond resolution. CLOCK_HIGHRES
180
is the nonadjustable, high-resolution clock.
182
Availability: Solaris.
184
.. versionadded:: 3.3
187
.. data:: CLOCK_MONOTONIC
189
Clock that cannot be set and represents monotonic time since some unspecified
194
.. versionadded:: 3.3
197
.. data:: CLOCK_MONOTONIC_RAW
199
Similar to :data:`CLOCK_MONOTONIC`, but provides access to a raw
200
hardware-based time that is not subject to NTP adjustments.
202
Availability: Linux 2.6.28 or later.
204
.. versionadded:: 3.3
207
.. data:: CLOCK_PROCESS_CPUTIME_ID
209
High-resolution per-process timer from the CPU.
213
.. versionadded:: 3.3
216
.. data:: CLOCK_REALTIME
218
System-wide real-time clock. Setting this clock requires appropriate
223
.. versionadded:: 3.3
226
.. data:: CLOCK_THREAD_CPUTIME_ID
228
Thread-specific CPU-time clock.
232
.. versionadded:: 3.3
235
.. function:: ctime([secs])
237
Convert a time expressed in seconds since the epoch to a string representing
238
local time. If *secs* is not provided or :const:`None`, the current time as
239
returned by :func:`.time` is used. ``ctime(secs)`` is equivalent to
240
``asctime(localtime(secs))``. Locale information is not used by :func:`ctime`.
245
Nonzero if a DST timezone is defined.
248
.. function:: get_clock_info(name)
250
Get information on the specified clock as a namespace object.
251
Supported clock names and the corresponding functions to read their value
254
* ``'clock'``: :func:`time.clock`
255
* ``'monotonic'``: :func:`time.monotonic`
256
* ``'perf_counter'``: :func:`time.perf_counter`
257
* ``'process_time'``: :func:`time.process_time`
258
* ``'time'``: :func:`time.time`
260
The result has the following attributes:
262
- *adjustable*: ``True`` if the clock can be changed automatically (e.g. by
263
a NTP daemon) or manually by the system administrator, ``False`` otherwise
264
- *implementation*: The name of the underlying C function used to get
266
- *monotonic*: ``True`` if the clock cannot go backward,
268
- *resolution*: The resolution of the clock in seconds (:class:`float`)
270
.. versionadded:: 3.3
273
.. function:: gmtime([secs])
275
Convert a time expressed in seconds since the epoch to a :class:`struct_time` in
276
UTC in which the dst flag is always zero. If *secs* is not provided or
277
:const:`None`, the current time as returned by :func:`.time` is used. Fractions
278
of a second are ignored. See above for a description of the
279
:class:`struct_time` object. See :func:`calendar.timegm` for the inverse of this
283
.. function:: localtime([secs])
285
Like :func:`gmtime` but converts to local time. If *secs* is not provided or
286
:const:`None`, the current time as returned by :func:`.time` is used. The dst
287
flag is set to ``1`` when DST applies to the given time.
290
.. function:: mktime(t)
292
This is the inverse function of :func:`localtime`. Its argument is the
293
:class:`struct_time` or full 9-tuple (since the dst flag is needed; use ``-1``
294
as the dst flag if it is unknown) which expresses the time in *local* time, not
295
UTC. It returns a floating point number, for compatibility with :func:`.time`.
296
If the input value cannot be represented as a valid time, either
297
:exc:`OverflowError` or :exc:`ValueError` will be raised (which depends on
298
whether the invalid value is caught by Python or the underlying C libraries).
299
The earliest date for which it can generate a time is platform-dependent.
302
.. function:: monotonic()
304
Return the value (in fractional seconds) of a monotonic clock, i.e. a clock
305
that cannot go backwards. The clock is not affected by system clock updates.
306
The reference point of the returned value is undefined, so that only the
307
difference between the results of consecutive calls is valid.
309
On Windows versions older than Vista, :func:`monotonic` detects
310
:c:func:`GetTickCount` integer overflow (32 bits, roll-over after 49.7 days).
311
It increases an internal epoch (reference time) by 2\ :sup:`32` each time
312
that an overflow is detected. The epoch is stored in the process-local state
313
and so the value of :func:`monotonic` may be different in two Python
314
processes running for more than 49 days. On more recent versions of Windows
315
and on other operating systems, :func:`monotonic` is system-wide.
317
.. versionadded:: 3.3
318
.. versionchanged:: 3.5
319
The function is now always available.
322
.. function:: perf_counter()
324
Return the value (in fractional seconds) of a performance counter, i.e. a
325
clock with the highest available resolution to measure a short duration. It
326
does include time elapsed during sleep and is system-wide. The reference
327
point of the returned value is undefined, so that only the difference between
328
the results of consecutive calls is valid.
330
.. versionadded:: 3.3
333
.. function:: process_time()
335
Return the value (in fractional seconds) of the sum of the system and user
336
CPU time of the current process. It does not include time elapsed during
337
sleep. It is process-wide by definition. The reference point of the
338
returned value is undefined, so that only the difference between the results
339
of consecutive calls is valid.
341
.. versionadded:: 3.3
343
.. function:: sleep(secs)
345
Suspend execution of the calling thread for the given number of seconds.
346
The argument may be a floating point number to indicate a more precise sleep
347
time. The actual suspension time may be less than that requested because any
348
caught signal will terminate the :func:`sleep` following execution of that
349
signal's catching routine. Also, the suspension time may be longer than
350
requested by an arbitrary amount because of the scheduling of other activity
353
.. versionchanged:: 3.5
354
The function now sleeps at least *secs* even if the sleep is interrupted
355
by a signal, except if the signal handler raises an exception (see
356
:pep:`475` for the rationale).
359
.. function:: strftime(format[, t])
361
Convert a tuple or :class:`struct_time` representing a time as returned by
362
:func:`gmtime` or :func:`localtime` to a string as specified by the *format*
363
argument. If *t* is not provided, the current time as returned by
364
:func:`localtime` is used. *format* must be a string. :exc:`ValueError` is
365
raised if any field in *t* is outside of the allowed range.
367
0 is a legal argument for any position in the time tuple; if it is normally
368
illegal the value is forced to a correct one.
370
The following directives can be embedded in the *format* string. They are shown
371
without the optional field width and precision specification, and are replaced
372
by the indicated characters in the :func:`strftime` result:
374
+-----------+------------------------------------------------+-------+
375
| Directive | Meaning | Notes |
376
+===========+================================================+=======+
377
| ``%a`` | Locale's abbreviated weekday name. | |
379
+-----------+------------------------------------------------+-------+
380
| ``%A`` | Locale's full weekday name. | |
381
+-----------+------------------------------------------------+-------+
382
| ``%b`` | Locale's abbreviated month name. | |
384
+-----------+------------------------------------------------+-------+
385
| ``%B`` | Locale's full month name. | |
386
+-----------+------------------------------------------------+-------+
387
| ``%c`` | Locale's appropriate date and time | |
388
| | representation. | |
389
+-----------+------------------------------------------------+-------+
390
| ``%d`` | Day of the month as a decimal number [01,31]. | |
392
+-----------+------------------------------------------------+-------+
393
| ``%H`` | Hour (24-hour clock) as a decimal number | |
395
+-----------+------------------------------------------------+-------+
396
| ``%I`` | Hour (12-hour clock) as a decimal number | |
398
+-----------+------------------------------------------------+-------+
399
| ``%j`` | Day of the year as a decimal number [001,366]. | |
401
+-----------+------------------------------------------------+-------+
402
| ``%m`` | Month as a decimal number [01,12]. | |
404
+-----------+------------------------------------------------+-------+
405
| ``%M`` | Minute as a decimal number [00,59]. | |
407
+-----------+------------------------------------------------+-------+
408
| ``%p`` | Locale's equivalent of either AM or PM. | \(1) |
410
+-----------+------------------------------------------------+-------+
411
| ``%S`` | Second as a decimal number [00,61]. | \(2) |
413
+-----------+------------------------------------------------+-------+
414
| ``%U`` | Week number of the year (Sunday as the first | \(3) |
415
| | day of the week) as a decimal number [00,53]. | |
416
| | All days in a new year preceding the first | |
417
| | Sunday are considered to be in week 0. | |
421
+-----------+------------------------------------------------+-------+
422
| ``%w`` | Weekday as a decimal number [0(Sunday),6]. | |
424
+-----------+------------------------------------------------+-------+
425
| ``%W`` | Week number of the year (Monday as the first | \(3) |
426
| | day of the week) as a decimal number [00,53]. | |
427
| | All days in a new year preceding the first | |
428
| | Monday are considered to be in week 0. | |
432
+-----------+------------------------------------------------+-------+
433
| ``%x`` | Locale's appropriate date representation. | |
435
+-----------+------------------------------------------------+-------+
436
| ``%X`` | Locale's appropriate time representation. | |
438
+-----------+------------------------------------------------+-------+
439
| ``%y`` | Year without century as a decimal number | |
441
+-----------+------------------------------------------------+-------+
442
| ``%Y`` | Year with century as a decimal number. | |
444
+-----------+------------------------------------------------+-------+
445
| ``%z`` | Time zone offset indicating a positive or | |
446
| | negative time difference from UTC/GMT of the | |
447
| | form +HHMM or -HHMM, where H represents decimal| |
448
| | hour digits and M represents decimal minute | |
449
| | digits [-23:59, +23:59]. | |
450
+-----------+------------------------------------------------+-------+
451
| ``%Z`` | Time zone name (no characters if no time zone | |
453
+-----------+------------------------------------------------+-------+
454
| ``%%`` | A literal ``'%'`` character. | |
455
+-----------+------------------------------------------------+-------+
460
When used with the :func:`strptime` function, the ``%p`` directive only affects
461
the output hour field if the ``%I`` directive is used to parse the hour.
464
The range really is ``0`` to ``61``; value ``60`` is valid in
465
timestamps representing leap seconds and value ``61`` is supported
466
for historical reasons.
469
When used with the :func:`strptime` function, ``%U`` and ``%W`` are only used in
470
calculations when the day of the week and the year are specified.
472
Here is an example, a format for dates compatible with that specified in the
473
:rfc:`2822` Internet email standard. [#]_ ::
475
>>> from time import gmtime, strftime
476
>>> strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime())
477
'Thu, 28 Jun 2001 14:17:15 +0000'
479
Additional directives may be supported on certain platforms, but only the
480
ones listed here have a meaning standardized by ANSI C. To see the full set
481
of format codes supported on your platform, consult the :manpage:`strftime(3)`
484
On some platforms, an optional field width and precision specification can
485
immediately follow the initial ``'%'`` of a directive in the following order;
486
this is also not portable. The field width is normally 2 except for ``%j`` where
490
.. function:: strptime(string[, format])
492
Parse a string representing a time according to a format. The return value
493
is a :class:`struct_time` as returned by :func:`gmtime` or
496
The *format* parameter uses the same directives as those used by
497
:func:`strftime`; it defaults to ``"%a %b %d %H:%M:%S %Y"`` which matches the
498
formatting returned by :func:`ctime`. If *string* cannot be parsed according
499
to *format*, or if it has excess data after parsing, :exc:`ValueError` is
500
raised. The default values used to fill in any missing data when more
501
accurate values cannot be inferred are ``(1900, 1, 1, 0, 0, 0, 0, 1, -1)``.
502
Both *string* and *format* must be strings.
507
>>> time.strptime("30 Nov 00", "%d %b %y") # doctest: +NORMALIZE_WHITESPACE
508
time.struct_time(tm_year=2000, tm_mon=11, tm_mday=30, tm_hour=0, tm_min=0,
509
tm_sec=0, tm_wday=3, tm_yday=335, tm_isdst=-1)
511
Support for the ``%Z`` directive is based on the values contained in ``tzname``
512
and whether ``daylight`` is true. Because of this, it is platform-specific
513
except for recognizing UTC and GMT which are always known (and are considered to
514
be non-daylight savings timezones).
516
Only the directives specified in the documentation are supported. Because
517
``strftime()`` is implemented per platform it can sometimes offer more
518
directives than those listed. But ``strptime()`` is independent of any platform
519
and thus does not necessarily support all directives available that are not
520
documented as supported.
523
.. class:: struct_time
525
The type of the time value sequence returned by :func:`gmtime`,
526
:func:`localtime`, and :func:`strptime`. It is an object with a :term:`named
527
tuple` interface: values can be accessed by index and by attribute name. The
528
following values are present:
530
+-------+-------------------+---------------------------------+
531
| Index | Attribute | Values |
532
+=======+===================+=================================+
533
| 0 | :attr:`tm_year` | (for example, 1993) |
534
+-------+-------------------+---------------------------------+
535
| 1 | :attr:`tm_mon` | range [1, 12] |
536
+-------+-------------------+---------------------------------+
537
| 2 | :attr:`tm_mday` | range [1, 31] |
538
+-------+-------------------+---------------------------------+
539
| 3 | :attr:`tm_hour` | range [0, 23] |
540
+-------+-------------------+---------------------------------+
541
| 4 | :attr:`tm_min` | range [0, 59] |
542
+-------+-------------------+---------------------------------+
543
| 5 | :attr:`tm_sec` | range [0, 61]; see **(2)** in |
544
| | | :func:`strftime` description |
545
+-------+-------------------+---------------------------------+
546
| 6 | :attr:`tm_wday` | range [0, 6], Monday is 0 |
547
+-------+-------------------+---------------------------------+
548
| 7 | :attr:`tm_yday` | range [1, 366] |
549
+-------+-------------------+---------------------------------+
550
| 8 | :attr:`tm_isdst` | 0, 1 or -1; see below |
551
+-------+-------------------+---------------------------------+
552
| N/A | :attr:`tm_zone` | abbreviation of timezone name |
553
+-------+-------------------+---------------------------------+
554
| N/A | :attr:`tm_gmtoff` | offset east of UTC in seconds |
555
+-------+-------------------+---------------------------------+
557
Note that unlike the C structure, the month value is a range of [1, 12], not
560
In calls to :func:`mktime`, :attr:`tm_isdst` may be set to 1 when daylight
561
savings time is in effect, and 0 when it is not. A value of -1 indicates that
562
this is not known, and will usually result in the correct state being filled in.
564
When a tuple with an incorrect length is passed to a function expecting a
565
:class:`struct_time`, or having elements of the wrong type, a
566
:exc:`TypeError` is raised.
568
.. versionchanged:: 3.3
569
:attr:`tm_gmtoff` and :attr:`tm_zone` attributes are available on platforms
570
with C library supporting the corresponding fields in ``struct tm``.
574
Return the time in seconds since the epoch as a floating point number.
575
Note that even though the time is always returned as a floating point
576
number, not all systems provide time with a better precision than 1 second.
577
While this function normally returns non-decreasing values, it can return a
578
lower value than a previous call if the system clock has been set back between
583
The offset of the local (non-DST) timezone, in seconds west of UTC (negative in
584
most of Western Europe, positive in the US, zero in the UK).
589
A tuple of two strings: the first is the name of the local non-DST timezone, the
590
second is the name of the local DST timezone. If no DST timezone is defined,
591
the second string should not be used.
594
.. function:: tzset()
596
Resets the time conversion rules used by the library routines. The environment
597
variable :envvar:`TZ` specifies how this is done.
603
Although in many cases, changing the :envvar:`TZ` environment variable may
604
affect the output of functions like :func:`localtime` without calling
605
:func:`tzset`, this behavior should not be relied on.
607
The :envvar:`TZ` environment variable should contain no whitespace.
609
The standard format of the :envvar:`TZ` environment variable is (whitespace
612
std offset [dst [offset [,start[/time], end[/time]]]]
614
Where the components are:
617
Three or more alphanumerics giving the timezone abbreviations. These will be
618
propagated into time.tzname
621
The offset has the form: ``± hh[:mm[:ss]]``. This indicates the value
622
added the local time to arrive at UTC. If preceded by a '-', the timezone
623
is east of the Prime Meridian; otherwise, it is west. If no offset follows
624
dst, summer time is assumed to be one hour ahead of standard time.
626
``start[/time], end[/time]``
627
Indicates when to change to and back from DST. The format of the
628
start and end dates are one of the following:
631
The Julian day *n* (1 <= *n* <= 365). Leap days are not counted, so in
632
all years February 28 is day 59 and March 1 is day 60.
635
The zero-based Julian day (0 <= *n* <= 365). Leap days are counted, and
636
it is possible to refer to February 29.
639
The *d*'th day (0 <= *d* <= 6) or week *n* of month *m* of the year (1
640
<= *n* <= 5, 1 <= *m* <= 12, where week 5 means "the last *d* day in
641
month *m*" which may occur in either the fourth or the fifth
642
week). Week 1 is the first week in which the *d*'th day occurs. Day
645
``time`` has the same format as ``offset`` except that no leading sign
646
('-' or '+') is allowed. The default, if time is not given, is 02:00:00.
650
>>> os.environ['TZ'] = 'EST+05EDT,M4.1.0,M10.5.0'
652
>>> time.strftime('%X %x %Z')
653
'02:07:36 05/08/03 EDT'
654
>>> os.environ['TZ'] = 'AEST-10AEDT-11,M10.5.0,M3.5.0'
656
>>> time.strftime('%X %x %Z')
657
'16:08:12 05/08/03 AEST'
659
On many Unix systems (including \*BSD, Linux, Solaris, and Darwin), it is more
660
convenient to use the system's zoneinfo (:manpage:`tzfile(5)`) database to
661
specify the timezone rules. To do this, set the :envvar:`TZ` environment
662
variable to the path of the required timezone datafile, relative to the root of
663
the systems 'zoneinfo' timezone database, usually located at
664
:file:`/usr/share/zoneinfo`. For example, ``'US/Eastern'``,
665
``'Australia/Melbourne'``, ``'Egypt'`` or ``'Europe/Amsterdam'``. ::
667
>>> os.environ['TZ'] = 'US/Eastern'
671
>>> os.environ['TZ'] = 'Egypt'
679
Module :mod:`datetime`
680
More object-oriented interface to dates and times.
683
Internationalization services. The locale setting affects the interpretation
684
of many format specifiers in :func:`strftime` and :func:`strptime`.
686
Module :mod:`calendar`
687
General calendar-related functions. :func:`~calendar.timegm` is the
688
inverse of :func:`gmtime` from this module.
690
.. rubric:: Footnotes
692
.. [#] The use of ``%Z`` is now deprecated, but the ``%z`` escape that expands to the
693
preferred hour/minute offset is not supported by all ANSI C libraries. Also, a
694
strict reading of the original 1982 :rfc:`822` standard calls for a two-digit
695
year (%y rather than %Y), but practice moved to 4-digit years long before the
696
year 2000. After that, :rfc:`822` became obsolete and the 4-digit year has
697
been first recommended by :rfc:`1123` and then mandated by :rfc:`2822`.
added
removed
python-3.5.1-docs-html/_sources/library/time.txt
