sandbox/morph / Doc / library / time.rst

Full commit

:mod:`time` --- 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.

  • 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).
  • 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.
  • 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.
  • 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.

The module defines the following functions and data items:

The type of the time value sequence returned by :func:`gmtime`, :func:`localtime`, and :func:`strptime`. It is an object with a :term:`named tuple` interface: values can be accessed by index and by attribute name. The following values are present:

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 :ref:`Year 2000 (Y2K) issues <time-y2kissues>` 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.


[1]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. After that, RFC 822 became obsolete and the 4-digit year has been first recommended by RFC 1123 and then mandated by RFC 2822.