| \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. |
| |
| 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)}.% |
| \index{epoch} |
| |
| \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}: 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 time tuple (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} in the environment to \code{x} 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.% |
| \index{Year 2000}% |
| \index{Y2K} |
| |
| \item |
| 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.% |
| \index{UTC}% |
| \index{Coordinated Universal Time}% |
| \index{Greenwich Mean Time} |
| |
| \item |
| 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.% |
| \index{Daylight Saving Time} |
| |
| \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 tuple as returned by \function{gmtime()}, |
| \function{localtime()}, and \function{strptime()}, and accepted by |
| \function{asctime()}, \function{mktime()} and \function{strftime()}, is a |
| tuple of 9 integers: year (e.g.\ 1993), month (1--12), day (1--31), |
| hour (0--23), minute (0--59), second (0--59), weekday (0--6, monday is |
| 0), Julian day (1--366) and daylight savings flag (-1, 0 or 1). |
| Note that unlike the \C{} structure, the month value is a range of 1-12, not |
| 0-11. A year value less than 100 will typically be silently converted to |
| 1900 plus the year value. A \code{-1} argument as daylight savings |
| flag, passed to \function{mktime()} will usually result in the correct |
| daylight savings state to be filled in. |
| |
| \end{itemize} |
| |
| The module defines the following functions and data items: |
| |
| |
| \begin{datadesc}{altzone} |
| The offset of the local DST timezone, in seconds west of the 0th |
| meridian, if one is defined. Negative if the local DST timezone is |
| east of the 0th meridian (as in Western Europe, including the UK). |
| Only use this if \code{daylight} is nonzero. |
| \end{datadesc} |
| |
| \begin{funcdesc}{asctime}{tuple} |
| Convert a tuple 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'}. Note: unlike the \C{} function of |
| the same name, there is no trailing newline. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{clock}{} |
| Return the current CPU time as a floating point number expressed in |
| seconds. The precision, and in fact the very definiton of the meaning |
| of ``CPU time''\index{CPU 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. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{ctime}{secs} |
| Convert a time expressed in seconds since the epoch to a string |
| representing local time. \code{ctime(\var{secs})} is equivalent to |
| \code{asctime(localtime(\var{secs}))}. |
| \end{funcdesc} |
| |
| \begin{datadesc}{daylight} |
| Nonzero if a DST timezone is defined. |
| \end{datadesc} |
| |
| \begin{funcdesc}{gmtime}{secs} |
| Convert a time expressed in seconds since the epoch to a time tuple |
| in UTC in which the dst flag is always zero. Fractions of a second are |
| ignored. See above for a description of the tuple lay-out. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{localtime}{secs} |
| Like \function{gmtime()} but converts to local time. The dst flag is |
| set to \code{1} when DST applies to the given time. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{mktime}{tuple} |
| This is the inverse function of \function{localtime()}. Its argument |
| is the full 9-tuple (since the dst flag is needed --- pass \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, \exception{OverflowError} is raised. |
| \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. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{strftime}{format, tuple} |
| Convert a tuple representing a time as returned by \function{gmtime()} |
| or \function{localtime()} to a string as specified by the \var{format} |
| argument. \var{format} must be a string. |
| |
| 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{tableii}{c|p{24em}}{code}{Directive}{Meaning} |
| \lineii{\%a}{Locale's abbreviated weekday name.} |
| \lineii{\%A}{Locale's full weekday name.} |
| \lineii{\%b}{Locale's abbreviated month name.} |
| \lineii{\%B}{Locale's full month name.} |
| \lineii{\%c}{Locale's appropriate date and time representation.} |
| \lineii{\%d}{Day of the month as a decimal number [01,31].} |
| \lineii{\%H}{Hour (24-hour clock) as a decimal number [00,23].} |
| \lineii{\%I}{Hour (12-hour clock) as a decimal number [01,12].} |
| \lineii{\%j}{Day of the year as a decimal number [001,366].} |
| \lineii{\%m}{Month as a decimal number [01,12].} |
| \lineii{\%M}{Minute as a decimal number [00,59].} |
| \lineii{\%p}{Locale's equivalent of either AM or PM.} |
| \lineii{\%S}{Second as a decimal number [00,61].} |
| \lineii{\%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.} |
| \lineii{\%w}{Weekday as a decimal number [0(Sunday),6].} |
| \lineii{\%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 Sunday are considered to be in week 0.} |
| \lineii{\%x}{Locale's appropriate date representation.} |
| \lineii{\%X}{Locale's appropriate time representation.} |
| \lineii{\%y}{Year without century as a decimal number [00,99].} |
| \lineii{\%Y}{Year with century as a decimal number.} |
| \lineii{\%Z}{Time zone name (or by no characters if no time zone exists).} |
| \lineii{\%\%}{\%} |
| \end{tableii} |
| |
| 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 tuple 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()}. The same platform caveats apply; see |
| the local \UNIX{} documentation for restrictions or additional |
| supported directives. If \var{string} cannot be parsed according to |
| \var{format}, \exception{ValueError} is raised. This function may not |
| be defined on all platforms. |
| \end{funcdesc} |
| |
| \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. |
| \end{funcdesc} |
| |
| \begin{datadesc}{timezone} |
| The offset of the local (non-DST) timezone, in seconds west of the 0th |
| meridian (i.e. 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} |
| |