Source

cpython / 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 may 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 32-bit systems, 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. Function :func:`strptime` can parse 2-digit years when given %y format code. When 2-digit years are parsed, they are converted according to the POSIX and ISO C standards: values 69--99 are mapped to 1969--1999, and values 0--68 are mapped to 2000--2068.
  • 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 (2) 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
N/A :attr:`tm_zone` abbreviation of timezone name
N/A :attr:`tm_gmtoff` offset east of UTC in seconds

Note that unlike the C structure, the month value is a range of [1, 12], not [0, 11]. 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.

Footnotes

[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.