mirror of https://github.com/python/cpython
526 lines
25 KiB
ReStructuredText
526 lines
25 KiB
ReStructuredText
:mod:`time` --- Time access and conversions
|
|
===========================================
|
|
|
|
.. module:: time
|
|
:synopsis: Time access and conversions.
|
|
|
|
|
|
This module provides various time-related functions. For related
|
|
functionality, see also the :mod:`datetime` and :mod:`calendar` modules.
|
|
|
|
Although this module is always available,
|
|
not all functions are available on all platforms. Most of the functions
|
|
defined in this module call platform C library functions with the same name. It
|
|
may sometimes be helpful to consult the platform documentation, because the
|
|
semantics of these functions varies among platforms.
|
|
|
|
An explanation of some terminology and conventions is in order.
|
|
|
|
.. index:: single: epoch
|
|
|
|
* The :dfn:`epoch` is the point where the time starts. On January 1st of that
|
|
year, at 0 hours, the "time since the epoch" is zero. For Unix, the epoch is
|
|
1970. To find out what the epoch is, look at ``gmtime(0)``.
|
|
|
|
.. index:: single: Year 2038
|
|
|
|
* The functions in this module do not handle dates and times before the epoch or
|
|
far in the future. The cut-off point in the future is determined by the C
|
|
library; for Unix, it is typically in 2038.
|
|
|
|
.. index::
|
|
single: Year 2000
|
|
single: Y2K
|
|
|
|
* **Year 2000 (Y2K) issues**: Python depends on the platform's C library, which
|
|
generally doesn't have year 2000 issues, since all dates and times are
|
|
represented internally as seconds since the epoch. Functions accepting a
|
|
:class:`struct_time` (see below) generally require a 4-digit year. For backward
|
|
compatibility, 2-digit years are supported if the module variable
|
|
``accept2dyear`` is a non-zero integer; this variable is initialized to ``1``
|
|
unless the environment variable :envvar:`PYTHONY2K` is set to a non-empty
|
|
string, in which case it is initialized to ``0``. Thus, you can set
|
|
:envvar:`PYTHONY2K` to a non-empty string in the environment to require 4-digit
|
|
years for all year input. When 2-digit years are accepted, they are converted
|
|
according to the POSIX or X/Open standard: values 69-99 are mapped to 1969-1999,
|
|
and values 0--68 are mapped to 2000--2068. Values 100--1899 are always illegal.
|
|
Note that this is new as of Python 1.5.2(a2); earlier versions, up to Python
|
|
1.5.1 and 1.5.2a1, would add 1900 to year values below 1900.
|
|
|
|
.. index::
|
|
single: UTC
|
|
single: Coordinated Universal Time
|
|
single: Greenwich Mean Time
|
|
|
|
* UTC is Coordinated Universal Time (formerly known as Greenwich Mean Time, or
|
|
GMT). The acronym UTC is not a mistake but a compromise between English and
|
|
French.
|
|
|
|
.. index:: single: Daylight Saving Time
|
|
|
|
* DST is Daylight Saving Time, an adjustment of the timezone by (usually) one
|
|
hour during part of the year. DST rules are magic (determined by local law) and
|
|
can change from year to year. The C library has a table containing the local
|
|
rules (often it is read from a system file for flexibility) and is the only
|
|
source of True Wisdom in this respect.
|
|
|
|
* The precision of the various real-time functions may be less than suggested by
|
|
the units in which their value or argument is expressed. E.g. on most Unix
|
|
systems, the clock "ticks" only 50 or 100 times a second.
|
|
|
|
* On the other hand, the precision of :func:`time` and :func:`sleep` is better
|
|
than their Unix equivalents: times are expressed as floating point numbers,
|
|
:func:`time` returns the most accurate time available (using Unix
|
|
:cfunc:`gettimeofday` where available), and :func:`sleep` will accept a time
|
|
with a nonzero fraction (Unix :cfunc:`select` is used to implement this, where
|
|
available).
|
|
|
|
* The time value as returned by :func:`gmtime`, :func:`localtime`, and
|
|
:func:`strptime`, and accepted by :func:`asctime`, :func:`mktime` and
|
|
:func:`strftime`, is a sequence of 9 integers. The return values of
|
|
:func:`gmtime`, :func:`localtime`, and :func:`strptime` also offer attribute
|
|
names for individual fields.
|
|
|
|
+-------+-------------------+---------------------------------+
|
|
| Index | Attribute | Values |
|
|
+=======+===================+=================================+
|
|
| 0 | :attr:`tm_year` | (for example, 1993) |
|
|
+-------+-------------------+---------------------------------+
|
|
| 1 | :attr:`tm_mon` | range [1, 12] |
|
|
+-------+-------------------+---------------------------------+
|
|
| 2 | :attr:`tm_mday` | range [1, 31] |
|
|
+-------+-------------------+---------------------------------+
|
|
| 3 | :attr:`tm_hour` | range [0, 23] |
|
|
+-------+-------------------+---------------------------------+
|
|
| 4 | :attr:`tm_min` | range [0, 59] |
|
|
+-------+-------------------+---------------------------------+
|
|
| 5 | :attr:`tm_sec` | range [0, 61]; see **(1)** in |
|
|
| | | :func:`strftime` description |
|
|
+-------+-------------------+---------------------------------+
|
|
| 6 | :attr:`tm_wday` | range [0, 6], Monday is 0 |
|
|
+-------+-------------------+---------------------------------+
|
|
| 7 | :attr:`tm_yday` | range [1, 366] |
|
|
+-------+-------------------+---------------------------------+
|
|
| 8 | :attr:`tm_isdst` | 0, 1 or -1; see below |
|
|
+-------+-------------------+---------------------------------+
|
|
|
|
Note that unlike the C structure, the month value is a range of [1, 12],
|
|
not [0, 11].
|
|
A year value will be handled as described under "Year 2000 (Y2K) issues" above.
|
|
A ``-1`` argument as the daylight savings flag, passed to :func:`mktime` will
|
|
usually result in the correct daylight savings state to be filled in.
|
|
|
|
When a tuple with an incorrect length is passed to a function expecting a
|
|
:class:`struct_time`, or having elements of the wrong type, a :exc:`TypeError`
|
|
is raised.
|
|
|
|
* Use the following functions to convert between time representations:
|
|
|
|
+-------------------------+-------------------------+-------------------------+
|
|
| From | To | Use |
|
|
+=========================+=========================+=========================+
|
|
| seconds since the epoch | :class:`struct_time` in | :func:`gmtime` |
|
|
| | UTC | |
|
|
+-------------------------+-------------------------+-------------------------+
|
|
| seconds since the epoch | :class:`struct_time` in | :func:`localtime` |
|
|
| | local time | |
|
|
+-------------------------+-------------------------+-------------------------+
|
|
| :class:`struct_time` in | seconds since the epoch | :func:`calendar.timegm` |
|
|
| UTC | | |
|
|
+-------------------------+-------------------------+-------------------------+
|
|
| :class:`struct_time` in | seconds since the epoch | :func:`mktime` |
|
|
| local time | | |
|
|
+-------------------------+-------------------------+-------------------------+
|
|
|
|
|
|
The module defines the following functions and data items:
|
|
|
|
|
|
.. data:: accept2dyear
|
|
|
|
Boolean value indicating whether two-digit year values will be accepted. This
|
|
is true by default, but will be set to false if the environment variable
|
|
:envvar:`PYTHONY2K` has been set to a non-empty string. It may also be modified
|
|
at run time.
|
|
|
|
|
|
.. data:: altzone
|
|
|
|
The offset of the local DST timezone, in seconds west of UTC, if one is defined.
|
|
This is negative if the local DST timezone is east of UTC (as in Western Europe,
|
|
including the UK). Only use this if ``daylight`` is nonzero.
|
|
|
|
|
|
.. function:: asctime([t])
|
|
|
|
Convert a tuple or :class:`struct_time` representing a time as returned by
|
|
:func:`gmtime` or :func:`localtime` to a 24-character string of the following
|
|
form: ``'Sun Jun 20 23:21:05 1993'``. If *t* is not provided, the current time
|
|
as returned by :func:`localtime` is used. Locale information is not used by
|
|
:func:`asctime`.
|
|
|
|
.. note::
|
|
|
|
Unlike the C function of the same name, there is no trailing newline.
|
|
|
|
|
|
.. function:: clock()
|
|
|
|
.. index::
|
|
single: CPU time
|
|
single: processor time
|
|
single: benchmarking
|
|
|
|
On Unix, return the current processor time as a floating point number expressed
|
|
in seconds. The precision, and in fact the very definition of the meaning of
|
|
"processor time", depends on that of the C function of the same name, but in any
|
|
case, this is the function to use for benchmarking Python or timing algorithms.
|
|
|
|
On Windows, this function returns wall-clock seconds elapsed since the first
|
|
call to this function, as a floating point number, based on the Win32 function
|
|
:cfunc:`QueryPerformanceCounter`. The resolution is typically better than one
|
|
microsecond.
|
|
|
|
|
|
.. function:: ctime([secs])
|
|
|
|
Convert a time expressed in seconds since the epoch to a string representing
|
|
local time. If *secs* is not provided or :const:`None`, the current time as
|
|
returned by :func:`time` is used. ``ctime(secs)`` is equivalent to
|
|
``asctime(localtime(secs))``. Locale information is not used by :func:`ctime`.
|
|
|
|
|
|
.. data:: daylight
|
|
|
|
Nonzero if a DST timezone is defined.
|
|
|
|
|
|
.. function:: gmtime([secs])
|
|
|
|
Convert a time expressed in seconds since the epoch to a :class:`struct_time` in
|
|
UTC in which the dst flag is always zero. If *secs* is not provided or
|
|
:const:`None`, the current time as returned by :func:`time` is used. Fractions
|
|
of a second are ignored. See above for a description of the
|
|
:class:`struct_time` object. See :func:`calendar.timegm` for the inverse of this
|
|
function.
|
|
|
|
|
|
.. function:: localtime([secs])
|
|
|
|
Like :func:`gmtime` but converts to local time. If *secs* is not provided or
|
|
:const:`None`, the current time as returned by :func:`time` is used. The dst
|
|
flag is set to ``1`` when DST applies to the given time.
|
|
|
|
|
|
.. function:: mktime(t)
|
|
|
|
This is the inverse function of :func:`localtime`. Its argument is the
|
|
:class:`struct_time` or full 9-tuple (since the dst flag is needed; use ``-1``
|
|
as the dst flag if it is unknown) which expresses the time in *local* time, not
|
|
UTC. It returns a floating point number, for compatibility with :func:`time`.
|
|
If the input value cannot be represented as a valid time, either
|
|
:exc:`OverflowError` or :exc:`ValueError` will be raised (which depends on
|
|
whether the invalid value is caught by Python or the underlying C libraries).
|
|
The earliest date for which it can generate a time is platform-dependent.
|
|
|
|
|
|
.. function:: sleep(secs)
|
|
|
|
Suspend execution for the given number of seconds. The argument may be a
|
|
floating point number to indicate a more precise sleep time. The actual
|
|
suspension time may be less than that requested because any caught signal will
|
|
terminate the :func:`sleep` following execution of that signal's catching
|
|
routine. Also, the suspension time may be longer than requested by an arbitrary
|
|
amount because of the scheduling of other activity in the system.
|
|
|
|
|
|
.. function:: strftime(format[, t])
|
|
|
|
Convert a tuple or :class:`struct_time` representing a time as returned by
|
|
:func:`gmtime` or :func:`localtime` to a string as specified by the *format*
|
|
argument. If *t* is not provided, the current time as returned by
|
|
:func:`localtime` is used. *format* must be a string. :exc:`ValueError` is
|
|
raised if any field in *t* is outside of the allowed range.
|
|
|
|
0 is a legal argument for any position in the time tuple; if it is normally
|
|
illegal the value is forced to a correct one.
|
|
|
|
The following directives can be embedded in the *format* string. They are shown
|
|
without the optional field width and precision specification, and are replaced
|
|
by the indicated characters in the :func:`strftime` result:
|
|
|
|
+-----------+------------------------------------------------+-------+
|
|
| Directive | Meaning | Notes |
|
|
+===========+================================================+=======+
|
|
| ``%a`` | Locale's abbreviated weekday name. | |
|
|
| | | |
|
|
+-----------+------------------------------------------------+-------+
|
|
| ``%A`` | Locale's full weekday name. | |
|
|
+-----------+------------------------------------------------+-------+
|
|
| ``%b`` | Locale's abbreviated month name. | |
|
|
| | | |
|
|
+-----------+------------------------------------------------+-------+
|
|
| ``%B`` | Locale's full month name. | |
|
|
+-----------+------------------------------------------------+-------+
|
|
| ``%c`` | Locale's appropriate date and time | |
|
|
| | representation. | |
|
|
+-----------+------------------------------------------------+-------+
|
|
| ``%d`` | Day of the month as a decimal number [01,31]. | |
|
|
| | | |
|
|
+-----------+------------------------------------------------+-------+
|
|
| ``%H`` | Hour (24-hour clock) as a decimal number | |
|
|
| | [00,23]. | |
|
|
+-----------+------------------------------------------------+-------+
|
|
| ``%I`` | Hour (12-hour clock) as a decimal number | |
|
|
| | [01,12]. | |
|
|
+-----------+------------------------------------------------+-------+
|
|
| ``%j`` | Day of the year as a decimal number [001,366]. | |
|
|
| | | |
|
|
+-----------+------------------------------------------------+-------+
|
|
| ``%m`` | Month as a decimal number [01,12]. | |
|
|
| | | |
|
|
+-----------+------------------------------------------------+-------+
|
|
| ``%M`` | Minute as a decimal number [00,59]. | |
|
|
| | | |
|
|
+-----------+------------------------------------------------+-------+
|
|
| ``%p`` | Locale's equivalent of either AM or PM. | \(1) |
|
|
| | | |
|
|
+-----------+------------------------------------------------+-------+
|
|
| ``%S`` | Second as a decimal number [00,61]. | \(2) |
|
|
| | | |
|
|
+-----------+------------------------------------------------+-------+
|
|
| ``%U`` | Week number of the year (Sunday as the first | \(3) |
|
|
| | day of the week) as a decimal number [00,53]. | |
|
|
| | All days in a new year preceding the first | |
|
|
| | Sunday are considered to be in week 0. | |
|
|
| | | |
|
|
| | | |
|
|
| | | |
|
|
+-----------+------------------------------------------------+-------+
|
|
| ``%w`` | Weekday as a decimal number [0(Sunday),6]. | |
|
|
| | | |
|
|
+-----------+------------------------------------------------+-------+
|
|
| ``%W`` | Week number of the year (Monday as the first | \(3) |
|
|
| | day of the week) as a decimal number [00,53]. | |
|
|
| | All days in a new year preceding the first | |
|
|
| | Monday are considered to be in week 0. | |
|
|
| | | |
|
|
| | | |
|
|
| | | |
|
|
+-----------+------------------------------------------------+-------+
|
|
| ``%x`` | Locale's appropriate date representation. | |
|
|
| | | |
|
|
+-----------+------------------------------------------------+-------+
|
|
| ``%X`` | Locale's appropriate time representation. | |
|
|
| | | |
|
|
+-----------+------------------------------------------------+-------+
|
|
| ``%y`` | Year without century as a decimal number | |
|
|
| | [00,99]. | |
|
|
+-----------+------------------------------------------------+-------+
|
|
| ``%Y`` | Year with century as a decimal number. | |
|
|
| | | |
|
|
+-----------+------------------------------------------------+-------+
|
|
| ``%Z`` | Time zone name (no characters if no time zone | |
|
|
| | exists). | |
|
|
+-----------+------------------------------------------------+-------+
|
|
| ``%%`` | A literal ``'%'`` character. | |
|
|
+-----------+------------------------------------------------+-------+
|
|
|
|
Notes:
|
|
|
|
(1)
|
|
When used with the :func:`strptime` function, the ``%p`` directive only affects
|
|
the output hour field if the ``%I`` directive is used to parse the hour.
|
|
|
|
(2)
|
|
The range really is ``0`` to ``61``; this accounts for leap seconds and the
|
|
(very rare) double leap seconds.
|
|
|
|
(3)
|
|
When used with the :func:`strptime` function, ``%U`` and ``%W`` are only used in
|
|
calculations when the day of the week and the year are specified.
|
|
|
|
Here is an example, a format for dates compatible with that specified in the
|
|
:rfc:`2822` Internet email standard. [#]_ ::
|
|
|
|
>>> from time import gmtime, strftime
|
|
>>> strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime())
|
|
'Thu, 28 Jun 2001 14:17:15 +0000'
|
|
|
|
Additional directives may be supported on certain platforms, but only the ones
|
|
listed here have a meaning standardized by ANSI C.
|
|
|
|
On some platforms, an optional field width and precision specification can
|
|
immediately follow the initial ``'%'`` of a directive in the following order;
|
|
this is also not portable. The field width is normally 2 except for ``%j`` where
|
|
it is 3.
|
|
|
|
|
|
.. function:: strptime(string[, format])
|
|
|
|
Parse a string representing a time according to a format. The return value
|
|
is a :class:`struct_time` as returned by :func:`gmtime` or
|
|
:func:`localtime`.
|
|
|
|
The *format* parameter uses the same directives as those used by
|
|
:func:`strftime`; it defaults to ``"%a %b %d %H:%M:%S %Y"`` which matches the
|
|
formatting returned by :func:`ctime`. If *string* cannot be parsed according
|
|
to *format*, or if it has excess data after parsing, :exc:`ValueError` is
|
|
raised. The default values used to fill in any missing data when more
|
|
accurate values cannot be inferred are ``(1900, 1, 1, 0, 0, 0, 0, 1, -1)``.
|
|
Both *string* and *format* must be strings.
|
|
|
|
For example:
|
|
|
|
>>> import time
|
|
>>> time.strptime("30 Nov 00", "%d %b %y") # doctest: +NORMALIZE_WHITESPACE
|
|
time.struct_time(tm_year=2000, tm_mon=11, tm_mday=30, tm_hour=0, tm_min=0,
|
|
tm_sec=0, tm_wday=3, tm_yday=335, tm_isdst=-1)
|
|
|
|
Support for the ``%Z`` directive is based on the values contained in ``tzname``
|
|
and whether ``daylight`` is true. Because of this, it is platform-specific
|
|
except for recognizing UTC and GMT which are always known (and are considered to
|
|
be non-daylight savings timezones).
|
|
|
|
Only the directives specified in the documentation are supported. Because
|
|
``strftime()`` is implemented per platform it can sometimes offer more
|
|
directives than those listed. But ``strptime()`` is independent of any platform
|
|
and thus does not necessarily support all directives available that are not
|
|
documented as supported.
|
|
|
|
|
|
.. data:: struct_time
|
|
|
|
The type of the time value sequence returned by :func:`gmtime`,
|
|
:func:`localtime`, and :func:`strptime`.
|
|
|
|
|
|
.. function:: time()
|
|
|
|
Return the time as a floating point number expressed in seconds since the epoch,
|
|
in UTC. Note that even though the time is always returned as a floating point
|
|
number, not all systems provide time with a better precision than 1 second.
|
|
While this function normally returns non-decreasing values, it can return a
|
|
lower value than a previous call if the system clock has been set back between
|
|
the two calls.
|
|
|
|
|
|
.. data:: timezone
|
|
|
|
The offset of the local (non-DST) timezone, in seconds west of UTC (negative in
|
|
most of Western Europe, positive in the US, zero in the UK).
|
|
|
|
|
|
.. data:: tzname
|
|
|
|
A tuple of two strings: the first is the name of the local non-DST timezone, the
|
|
second is the name of the local DST timezone. If no DST timezone is defined,
|
|
the second string should not be used.
|
|
|
|
|
|
.. function:: tzset()
|
|
|
|
Resets the time conversion rules used by the library routines. The environment
|
|
variable :envvar:`TZ` specifies how this is done.
|
|
|
|
Availability: Unix.
|
|
|
|
.. note::
|
|
|
|
Although in many cases, changing the :envvar:`TZ` environment variable may
|
|
affect the output of functions like :func:`localtime` without calling
|
|
:func:`tzset`, this behavior should not be relied on.
|
|
|
|
The :envvar:`TZ` environment variable should contain no whitespace.
|
|
|
|
The standard format of the :envvar:`TZ` environment variable is (whitespace
|
|
added for clarity)::
|
|
|
|
std offset [dst [offset [,start[/time], end[/time]]]]
|
|
|
|
Where the components are:
|
|
|
|
``std`` and ``dst``
|
|
Three or more alphanumerics giving the timezone abbreviations. These will be
|
|
propagated into time.tzname
|
|
|
|
``offset``
|
|
The offset has the form: ``± hh[:mm[:ss]]``. This indicates the value
|
|
added the local time to arrive at UTC. If preceded by a '-', the timezone
|
|
is east of the Prime Meridian; otherwise, it is west. If no offset follows
|
|
dst, summer time is assumed to be one hour ahead of standard time.
|
|
|
|
``start[/time], end[/time]``
|
|
Indicates when to change to and back from DST. The format of the
|
|
start and end dates are one of the following:
|
|
|
|
:samp:`J{n}`
|
|
The Julian day *n* (1 <= *n* <= 365). Leap days are not counted, so in
|
|
all years February 28 is day 59 and March 1 is day 60.
|
|
|
|
:samp:`{n}`
|
|
The zero-based Julian day (0 <= *n* <= 365). Leap days are counted, and
|
|
it is possible to refer to February 29.
|
|
|
|
:samp:`M{m}.{n}.{d}`
|
|
The *d*'th day (0 <= *d* <= 6) or week *n* of month *m* of the year (1
|
|
<= *n* <= 5, 1 <= *m* <= 12, where week 5 means "the last *d* day in
|
|
month *m*" which may occur in either the fourth or the fifth
|
|
week). Week 1 is the first week in which the *d*'th day occurs. Day
|
|
zero is Sunday.
|
|
|
|
``time`` has the same format as ``offset`` except that no leading sign
|
|
('-' or '+') is allowed. The default, if time is not given, is 02:00:00.
|
|
|
|
::
|
|
|
|
>>> os.environ['TZ'] = 'EST+05EDT,M4.1.0,M10.5.0'
|
|
>>> time.tzset()
|
|
>>> time.strftime('%X %x %Z')
|
|
'02:07:36 05/08/03 EDT'
|
|
>>> os.environ['TZ'] = 'AEST-10AEDT-11,M10.5.0,M3.5.0'
|
|
>>> time.tzset()
|
|
>>> time.strftime('%X %x %Z')
|
|
'16:08:12 05/08/03 AEST'
|
|
|
|
On many Unix systems (including \*BSD, Linux, Solaris, and Darwin), it is more
|
|
convenient to use the system's zoneinfo (:manpage:`tzfile(5)`) database to
|
|
specify the timezone rules. To do this, set the :envvar:`TZ` environment
|
|
variable to the path of the required timezone datafile, relative to the root of
|
|
the systems 'zoneinfo' timezone database, usually located at
|
|
:file:`/usr/share/zoneinfo`. For example, ``'US/Eastern'``,
|
|
``'Australia/Melbourne'``, ``'Egypt'`` or ``'Europe/Amsterdam'``. ::
|
|
|
|
>>> os.environ['TZ'] = 'US/Eastern'
|
|
>>> time.tzset()
|
|
>>> time.tzname
|
|
('EST', 'EDT')
|
|
>>> os.environ['TZ'] = 'Egypt'
|
|
>>> time.tzset()
|
|
>>> time.tzname
|
|
('EET', 'EEST')
|
|
|
|
|
|
.. seealso::
|
|
|
|
Module :mod:`datetime`
|
|
More object-oriented interface to dates and times.
|
|
|
|
Module :mod:`locale`
|
|
Internationalization services. The locale settings can affect the return values
|
|
for some of the functions in the :mod:`time` module.
|
|
|
|
Module :mod:`calendar`
|
|
General calendar-related functions. :func:`timegm` is the inverse of
|
|
:func:`gmtime` from this module.
|
|
|
|
.. rubric:: Footnotes
|
|
|
|
.. [#] The use of ``%Z`` is now deprecated, but the ``%z`` escape that expands to the
|
|
preferred hour/minute offset is not supported by all ANSI C libraries. Also, a
|
|
strict reading of the original 1982 :rfc:`822` standard calls for a two-digit
|
|
year (%y rather than %Y), but practice moved to 4-digit years long before the
|
|
year 2000. The 4-digit year has been mandated by :rfc:`2822`, which obsoletes
|
|
:rfc:`822`.
|
|
|