/Doc/library/time.rst
http://unladen-swallow.googlecode.com/ · ReStructuredText · 558 lines · 424 code · 134 blank · 0 comment · 0 complexity · f6fc870e78c81b541e8eb80693ac9813 MD5 · raw file
- :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`, may be considered as 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.
- .. versionchanged:: 2.2
- The time value sequence was changed from a tuple to a :class:`struct_time`, with
- the addition of attribute names for the fields.
- * 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.
- .. versionchanged:: 2.1
- Allowed *t* to be omitted.
- .. 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`.
- .. versionchanged:: 2.1
- Allowed *secs* to be omitted.
- .. versionchanged:: 2.4
- If *secs* is :const:`None`, the current time is used.
- .. 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.
- .. versionchanged:: 2.1
- Allowed *secs* to be omitted.
- .. versionchanged:: 2.4
- If *secs* is :const:`None`, the current time is used.
- .. 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.
- .. versionchanged:: 2.1
- Allowed *secs* to be omitted.
- .. versionchanged:: 2.4
- If *secs* is :const:`None`, the current time is used.
- .. 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.
- .. versionchanged:: 2.1
- Allowed *t* to be omitted.
- .. versionchanged:: 2.4
- :exc:`ValueError` raised if a field in *t* is out of range.
- .. versionchanged:: 2.5
- 0 is now 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 | \(1) |
- | | AM or PM. | |
- +-----------+--------------------------------+-------+
- | ``%S`` | Second as a decimal number | \(2) |
- | | [00,61]. | |
- +-----------+--------------------------------+-------+
- | ``%U`` | Week number of the year | \(3) |
- | | (Sunday as the first 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 | \(3) |
- | | (Monday as the first 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)``.
- 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`.
- .. versionadded:: 2.2
- .. 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.
- .. versionadded:: 2.3
- 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`.