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

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

The module defines the following functions and data items:

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. The 4-digit year has been mandated by RFC 2822, which obsoletes RFC 822.