| \section{\module{time} --- |
| Time access and conversions} |
| |
| \declaremodule{builtin}{time} |
| \modulesynopsis{Time access and conversions.} |
| |
| |
| This module provides various time-related functions. It is always |
| available, but 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. |
| |
| \begin{itemize} |
| |
| \item |
| The \dfn{epoch}\index{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 \code{gmtime(0)}. |
| |
| \item |
| 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{Year 2038}. |
| |
| \item |
| \strong{Year 2000 (Y2K) issues}:\index{Year 2000}\index{Y2K} 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 |
| \code{accept2dyear} is a non-zero integer; this variable is |
| initialized to \code{1} unless the environment variable |
| \envvar{PYTHONY2K} is set to a non-empty string, in which case it is |
| initialized to \code{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. |
| |
| \item |
| UTC\index{UTC} is Coordinated Universal Time\index{Coordinated |
| Universal Time} (formerly known as Greenwich Mean |
| Time,\index{Greenwich Mean Time} or GMT). The acronym UTC is not a |
| mistake but a compromise between English and French. |
| |
| \item |
| DST is Daylight Saving Time,\index{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. |
| |
| \item |
| 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, and on the Mac, times are only accurate to whole seconds. |
| |
| \item |
| On the other hand, the precision of \function{time()} and |
| \function{sleep()} is better than their \UNIX{} equivalents: times are |
| expressed as floating point numbers, \function{time()} returns the |
| most accurate time available (using \UNIX{} \cfunction{gettimeofday()} |
| where available), and \function{sleep()} will accept a time with a |
| nonzero fraction (\UNIX{} \cfunction{select()} is used to implement |
| this, where available). |
| |
| \item |
| The time value as returned by \function{gmtime()}, |
| \function{localtime()}, and \function{strptime()}, and accepted by |
| \function{asctime()}, \function{mktime()} and \function{strftime()}, |
| is a sequence of 9 integers. The return values of \function{gmtime()}, |
| \function{localtime()}, and \function{strptime()} also offer attribute |
| names for individual fields. |
| |
| \begin{tableiii}{c|l|l}{textrm}{Index}{Attribute}{Values} |
| \lineiii{0}{\member{tm_year}}{(for example, 1993)} |
| \lineiii{1}{\member{tm_mon}}{range [1,12]} |
| \lineiii{2}{\member{tm_mday}}{range [1,31]} |
| \lineiii{3}{\member{tm_hour}}{range [0,23]} |
| \lineiii{4}{\member{tm_min}}{range [0,59]} |
| \lineiii{5}{\member{tm_sec}}{range [0,61]; see \strong{(1)} in \function{strftime()} description} |
| \lineiii{6}{\member{tm_wday}}{range [0,6], Monday is 0} |
| \lineiii{7}{\member{tm_yday}}{range [1,366]} |
| \lineiii{8}{\member{tm_isdst}}{0, 1 or -1; see below} |
| \end{tableiii} |
| |
| 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 \code{-1} argument as the |
| daylight savings flag, passed to \function{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 |
| \exception{TypeError} is raised. |
| |
| \versionchanged[The time value sequence was changed from a tuple to a |
| \class{struct_time}, with the addition of attribute names |
| for the fields]{2.2} |
| \end{itemize} |
| |
| The module defines the following functions and data items: |
| |
| |
| \begin{datadesc}{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. |
| \end{datadesc} |
| |
| \begin{datadesc}{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 |
| \code{daylight} is nonzero. |
| \end{datadesc} |
| |
| \begin{funcdesc}{asctime}{\optional{t}} |
| Convert a tuple or \class{struct_time} representing a time as returned |
| by \function{gmtime()} |
| or \function{localtime()} to a 24-character string of the following form: |
| \code{'Sun Jun 20 23:21:05 1993'}. If \var{t} is not provided, the |
| current time as returned by \function{localtime()} is used. |
| Locale information is not used by \function{asctime()}. |
| \note{Unlike the C function of the same name, there is no trailing |
| newline.} |
| \versionchanged[Allowed \var{t} to be omitted]{2.1} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{clock}{} |
| 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''\index{CPU time}\index{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\index{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 \cfunction{QueryPerformanceCounter()}. |
| The resolution is typically better than one microsecond. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{ctime}{\optional{secs}} |
| Convert a time expressed in seconds since the epoch to a string |
| representing local time. If \var{secs} is not provided or |
| \constant{None}, the current time as returned by \function{time()} is |
| used. \code{ctime(\var{secs})} is equivalent to |
| \code{asctime(localtime(\var{secs}))}. |
| Locale information is not used by \function{ctime()}. |
| \versionchanged[Allowed \var{secs} to be omitted]{2.1} |
| \versionchanged[If \var{secs} is \constant{None}, the current time is |
| used]{2.4} |
| \end{funcdesc} |
| |
| \begin{datadesc}{daylight} |
| Nonzero if a DST timezone is defined. |
| \end{datadesc} |
| |
| \begin{funcdesc}{gmtime}{\optional{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 \var{secs} is not |
| provided or \constant{None}, the current time as returned by |
| \function{time()} is used. Fractions of a second are ignored. See |
| above for a description of the \class{struct_time} object. |
| \versionchanged[Allowed \var{secs} to be omitted]{2.1} |
| \versionchanged[If \var{secs} is \constant{None}, the current time is |
| used]{2.4} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{localtime}{\optional{secs}} |
| Like \function{gmtime()} but converts to local time. If \var{secs} is |
| not provided or \constant{None}, the current time as returned by |
| \function{time()} is used. The dst flag is set to \code{1} when DST |
| applies to the given time. |
| \versionchanged[Allowed \var{secs} to be omitted]{2.1} |
| \versionchanged[If \var{secs} is \constant{None}, the current time is |
| used]{2.4} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{mktime}{t} |
| This is the inverse function of \function{localtime()}. Its argument |
| is the \class{struct_time} or full 9-tuple (since the dst flag is |
| needed; use \code{-1} as the dst flag if it is unknown) which |
| expresses the time in |
| \emph{local} time, not UTC. It returns a floating point number, for |
| compatibility with \function{time()}. If the input value cannot be |
| represented as a valid time, either \exception{OverflowError} or |
| \exception{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. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{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 \function{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. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{strftime}{format\optional{, t}} |
| Convert a tuple or \class{struct_time} representing a time as returned |
| by \function{gmtime()} or \function{localtime()} to a string as |
| specified by the \var{format} argument. If \var{t} is not |
| provided, the current time as returned by \function{localtime()} is |
| used. \var{format} must be a string. \exception{ValueError} is raised |
| if any field in \var{t} is outside of the allowed range. |
| \versionchanged[Allowed \var{t} to be omitted]{2.1} |
| \versionchanged[\exception{ValueError} raised if a field in \var{t} is |
| out of range.]{2.4} |
| |
| The following directives can be embedded in the \var{format} string. |
| They are shown without the optional field width and precision |
| specification, and are replaced by the indicated characters in the |
| \function{strftime()} result: |
| |
| \begin{tableiii}{c|p{24em}|c}{code}{Directive}{Meaning}{Notes} |
| \lineiii{\%a}{Locale's abbreviated weekday name.}{} |
| \lineiii{\%A}{Locale's full weekday name.}{} |
| \lineiii{\%b}{Locale's abbreviated month name.}{} |
| \lineiii{\%B}{Locale's full month name.}{} |
| \lineiii{\%c}{Locale's appropriate date and time representation.}{} |
| \lineiii{\%d}{Day of the month as a decimal number [01,31].}{} |
| \lineiii{\%H}{Hour (24-hour clock) as a decimal number [00,23].}{} |
| \lineiii{\%I}{Hour (12-hour clock) as a decimal number [01,12].}{} |
| \lineiii{\%j}{Day of the year as a decimal number [001,366].}{} |
| \lineiii{\%m}{Month as a decimal number [01,12].}{} |
| \lineiii{\%M}{Minute as a decimal number [00,59].}{} |
| \lineiii{\%p}{Locale's equivalent of either AM or PM.}{(1)} |
| \lineiii{\%S}{Second as a decimal number [00,61].}{(2)} |
| \lineiii{\%U}{Week number of the year (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.}{} |
| \lineiii{\%w}{Weekday as a decimal number [0(Sunday),6].}{} |
| \lineiii{\%W}{Week number of the year (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.}{} |
| \lineiii{\%x}{Locale's appropriate date representation.}{} |
| \lineiii{\%X}{Locale's appropriate time representation.}{} |
| \lineiii{\%y}{Year without century as a decimal number [00,99].}{} |
| \lineiii{\%Y}{Year with century as a decimal number.}{} |
| \lineiii{\%Z}{Time zone name (no characters if no time zone exists).}{} |
| \lineiii{\%\%}{A literal \character{\%} character.}{} |
| \end{tableiii} |
| |
| \noindent |
| Notes: |
| |
| \begin{description} |
| \item[(1)] |
| When used with the \function{strptime()} function, the \code{\%p} |
| directive only affects the output hour field if the \code{\%I} directive |
| is used to parse the hour. |
| \item[(2)] |
| The range really is \code{0} to \code{61}; this accounts for leap |
| seconds and the (very rare) double leap seconds. |
| \end{description} |
| |
| Here is an example, a format for dates compatible with that specified |
| in the \rfc{2822} Internet email standard. |
| \footnote{The use of \code{\%Z} is now |
| deprecated, but the \code{\%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}.} |
| |
| \begin{verbatim} |
| >>> from time import gmtime, strftime |
| >>> strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime()) |
| 'Thu, 28 Jun 2001 14:17:15 +0000' |
| \end{verbatim} |
| |
| 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 \character{\%} of a |
| directive in the following order; this is also not portable. |
| The field width is normally 2 except for \code{\%j} where it is 3. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{strptime}{string\optional{, format}} |
| Parse a string representing a time according to a format. The return |
| value is a \class{struct_time} as returned by \function{gmtime()} or |
| \function{localtime()}. The \var{format} parameter uses the same |
| directives as those used by \function{strftime()}; it defaults to |
| \code{"\%a \%b \%d \%H:\%M:\%S \%Y"} which matches the formatting |
| returned by \function{ctime()}. If \var{string} cannot be parsed |
| according to \var{format}, \exception{ValueError} is raised. If the |
| string to be parsed has excess data after parsing, |
| \exception{ValueError} is raised. The default values used to fill in |
| any missing data are \code{(1900, 1, 1, 0, 0, 0, 0, 1, -1)} . |
| |
| Support for the \code{\%Z} directive is based on the values contained in |
| \code{tzname} and whether \code{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). |
| \end{funcdesc} |
| |
| \begin{datadesc}{struct_time} |
| The type of the time value sequence returned by \function{gmtime()}, |
| \function{localtime()}, and \function{strptime()}. |
| \versionadded{2.2} |
| \end{datadesc} |
| |
| \begin{funcdesc}{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. |
| \end{funcdesc} |
| |
| \begin{datadesc}{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). |
| \end{datadesc} |
| |
| \begin{datadesc}{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. |
| \end{datadesc} |
| |
| \begin{funcdesc}{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. |
| |
| \begin{notice} |
| Although in many cases, changing the \envvar{TZ} environment variable |
| may affect the output of functions like \function{localtime} without calling |
| \function{tzset}, this behavior should not be relied on. |
| |
| The \envvar{TZ} environment variable should contain no whitespace. |
| \end{notice} |
| |
| The standard format of the \envvar{TZ} environment variable is: |
| (whitespace added for clarity) |
| \begin{itemize} |
| \item[std offset [dst [offset] [,start[/time], end[/time]]]] |
| \end{itemize} |
| |
| Where: |
| |
| \begin{itemize} |
| \item[std and dst] |
| Three or more alphanumerics giving the timezone abbreviations. |
| These will be propogated into time.tzname |
| |
| \item[offset] |
| The offset has the form: \plusminus{} 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, summmer time is assumed to be one hour ahead of standard time. |
| |
| \item[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: |
| |
| \begin{itemize} |
| \item[J\var{n}] |
| The Julian day \var{n} (1 <= \var{n} <= 365). Leap days are not |
| counted, so in all years February 28 is day 59 and |
| March 1 is day 60. |
| |
| \item[\var{n}] |
| The zero-based Julian day (0 <= \var{n} <= 365). Leap days are |
| counted, and it is possible to refer to February 29. |
| |
| \item[M\var{m}.\var{n}.\var{d}] |
| The \var{d}'th day (0 <= \var{d} <= 6) or week \var{n} |
| of month \var{m} of the year (1 <= \var{n} <= 5, |
| 1 <= \var{m} <= 12, where week 5 means "the last \var{d} day |
| in month \var{m}" which may occur in either the fourth or |
| the fifth week). Week 1 is the first week in which the |
| \var{d}'th day occurs. Day zero is Sunday. |
| \end{itemize} |
| |
| 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. |
| \end{itemize} |
| |
| |
| \begin{verbatim} |
| >>> 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' |
| \end{verbatim} |
| |
| 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, |
| \code{'US/Eastern'}, \code{'Australia/Melbourne'}, \code{'Egypt'} or |
| \code{'Europe/Amsterdam'}. |
| |
| \begin{verbatim} |
| >>> os.environ['TZ'] = 'US/Eastern' |
| >>> time.tzset() |
| >>> time.tzname |
| ('EST', 'EDT') |
| >>> os.environ['TZ'] = 'Egypt' |
| >>> time.tzset() |
| >>> time.tzname |
| ('EET', 'EEST') |
| \end{verbatim} |
| |
| \end{funcdesc} |
| |
| |
| \begin{seealso} |
| \seemodule{datetime}{More object-oriented interface to dates and times.} |
| \seemodule{locale}{Internationalization services. The locale |
| settings can affect the return values for some of |
| the functions in the \module{time} module.} |
| \seemodule{calendar}{General calendar-related functions. |
| \function{timegm()} is the inverse of |
| \function{gmtime()} from this module.} |
| \end{seealso} |