15.3. time — Time access and conversions

This module provides various time-related functions. For related functionality, see also the datetime and 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 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 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 PYTHONY2K is set to a non-empty string, in which case it is initialized to 0. Thus, you can set 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 time() and sleep() is better than their Unix equivalents: times are expressed as floating point numbers, time() returns the most accurate time available (using Unix :cfunc:`gettimeofday` where available), and 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 gmtime(), localtime(), and strptime(), and accepted by asctime(), mktime() and strftime(), may be considered as a sequence of 9 integers. The return values of gmtime(), localtime(), and strptime() also offer attribute names for individual fields.

    Index Attribute Values
    0 tm_year (for example, 1993)
    1 tm_mon range [1,12]
    2 tm_mday range [1,31]
    3 tm_hour range [0,23]
    4 tm_min range [0,59]
    5 tm_sec range [0,61]; see (1) in strftime() description
    6 tm_wday range [0,6], Monday is 0
    7 tm_yday range [1,366]
    8 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 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 struct_time, or having elements of the wrong type, a TypeError is raised.

    Changed in version 2.2:

    Changed in version 2.2: The time value sequence was changed from a tuple to a 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 struct_time in UTC gmtime()
    seconds since the epoch struct_time in local time localtime()
    struct_time in UTC seconds since the epoch calendar.timegm()
    struct_time in local time seconds since the epoch mktime()

    • The module defines the following functions and data items:

    time.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 PYTHONY2K has been set to a non-empty string. It may also be modified at run time.

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

    time.asctime([t])

    Convert a tuple or struct_time representing a time as returned by gmtime() or 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 localtime() is used. Locale information is not used by asctime().

    Note

    Unlike the C function of the same name, there is no trailing newline.

    Changed in version 2.1:

    Changed in version 2.1: Allowed t to be omitted.