Doc/lib/libtime.tex

   1 \section{\module{time} ---
   2          Time access and conversions.}
   3 \declaremodule{builtin}{time}
   4
   5 \modulesynopsis{Time access and conversions.}
   6
   7
   8 This module provides various time-related functions.
   9 It is always available.
  10
  11 An explanation of some terminology and conventions is in order.
  12
  13 \begin{itemize}
  14
  15 \item
  16 The \dfn{epoch}\index{epoch} is the point where the time starts.  On
  17 January 1st of that year, at 0 hours, the ``time since the epoch'' is
  18 zero.  For \UNIX{}, the epoch is 1970.  To find out what the epoch is,
  19 look at \code{gmtime(0)}.%
  20 \index{epoch}
  21
  22 \item
  23 The functions in this module do not handle dates and times before the
  24 epoch or far in the future.  The cut-off point in the future is
  25 determined by the \C{} library; for \UNIX{}, it is typically in 2038.%
  26 \index{Year 2038}
  27
  28 \item
  29 \strong{Year 2000 (Y2K) issues}: Python depends on the platform's \C{}
  30 library, which generally doesn't have year 2000 issues, since all
  31 dates and times are represented internally as seconds since the
  32 epoch.  Functions accepting a time tuple (see below) generally require
  33 a 4-digit year.  For backward compatibility, 2-digit years are
  34 supported if the module variable \code{accept2dyear} is a non-zero
  35 integer; this variable is initialized to \code{1} unless the
  36 environment variable \envvar{PYTHONY2K} is set to a non-empty string,
  37 in which case it is initialized to \code{0}.  Thus, you can set
  38 \envvar{PYTHONY2K} to a non-empty string in the environment to require 4-digit
  39 years for all year input.  When 2-digit years are accepted, they are
  40 converted according to the \POSIX{} or X/Open standard: values 69-99
  41 are mapped to 1969-1999, and values 0--68 are mapped to 2000--2068.
  42 Values 100--1899 are always illegal.  Note that this is new as of
  43 Python 1.5.2(a2); earlier versions, up to Python 1.5.1 and 1.5.2a1,
  44 would add 1900 to year values below 1900.%
  45 \index{Year 2000}%
  46 \index{Y2K}
  47
  48 \item
  49 UTC is Coordinated Universal Time (formerly known as Greenwich Mean
  50 Time, or GMT).  The acronym UTC is not a mistake but a compromise
  51 between English and French.%
  52 \index{UTC}%
  53 \index{Coordinated Universal Time}%
  54 \index{Greenwich Mean Time}
  55
  56 \item
  57 DST is Daylight Saving Time, an adjustment of the timezone by
  58 (usually) one hour during part of the year.  DST rules are magic
  59 (determined by local law) and can change from year to year.  The \C{}
  60 library has a table containing the local rules (often it is read from
  61 a system file for flexibility) and is the only source of True Wisdom
  62 in this respect.%
  63 \index{Daylight Saving Time}
  64
  65 \item
  66 The precision of the various real-time functions may be less than
  67 suggested by the units in which their value or argument is expressed.
  68 E.g.\ on most \UNIX{} systems, the clock ``ticks'' only 50 or 100 times a
  69 second, and on the Mac, times are only accurate to whole seconds.
  70
  71 \item
  72 On the other hand, the precision of \function{time()} and
  73 \function{sleep()} is better than their \UNIX{} equivalents: times are
  74 expressed as floating point numbers, \function{time()} returns the
  75 most accurate time available (using \UNIX{} \cfunction{gettimeofday()}
  76 where available), and \function{sleep()} will accept a time with a
  77 nonzero fraction (\UNIX{} \cfunction{select()} is used to implement
  78 this, where available).
  79
  80 \item
  81 The time tuple as returned by \function{gmtime()},
  82 \function{localtime()}, and \function{strptime()}, and accepted by
  83 \function{asctime()}, \function{mktime()} and \function{strftime()},
  84 is a tuple of 9 integers: year (e.g.\ 1993), month (1--12), day
  85 (1--31), hour (0--23), minute (0--59), second (0--59), weekday (0--6,
  86 monday is 0), Julian day (1--366) and daylight savings flag (-1, 0 or
  87 1).  Note that unlike the \C{} structure, the month value is a range
  88 of 1-12, not 0-11.  A year value will be handled as descibed under
  89 ``Year 2000 (Y2K) issues'' above.  A \code{-1} argument as daylight
  90 savings flag, passed to \function{mktime()} will usually result in the
  91 correct daylight savings state to be filled in.
  92
  93 \end{itemize}
  94
  95 The module defines the following functions and data items:
  96
  97
  98 \begin{datadesc}{accept2dyear}
  99 Boolean value indicating whether two-digit year values will be
 100 accepted.  This is true by default, but will be set to false if the
 101 environment variable \envvar{PYTHONY2K} has been set to a non-empty
 102 string.  It may also be modified at run time.
 103 \end{datadesc}
 104
 105 \begin{datadesc}{altzone}
 106 The offset of the local DST timezone, in seconds west of the 0th
 107 meridian, if one is defined.  Negative if the local DST timezone is
 108 east of the 0th meridian (as in Western Europe, including the UK).
 109 Only use this if \code{daylight} is nonzero.
 110 \end{datadesc}
 111
 112 \begin{funcdesc}{asctime}{tuple}
 113 Convert a tuple representing a time as returned by \function{gmtime()}
 114 or \function{localtime()} to a 24-character string of the following form:
 115 \code{'Sun Jun 20 23:21:05 1993'}.  Note: unlike the \C{} function of
 116 the same name, there is no trailing newline.
 117 \end{funcdesc}
 118
 119 \begin{funcdesc}{clock}{}
 120 Return the current CPU time as a floating point number expressed in
 121 seconds.  The precision, and in fact the very definiton of the meaning
 122 of ``CPU time''\index{CPU time}, depends on that of the \C{} function
 123 of the same name, but in any case, this is the function to use for
 124 benchmarking\index{benchmarking} Python or timing algorithms.
 125 \end{funcdesc}
 126
 127 \begin{funcdesc}{ctime}{secs}
 128 Convert a time expressed in seconds since the epoch to a string
 129 representing local time.  \code{ctime(\var{secs})} is equivalent to
 130 \code{asctime(localtime(\var{secs}))}.
 131 \end{funcdesc}
 132
 133 \begin{datadesc}{daylight}
 134 Nonzero if a DST timezone is defined.
 135 \end{datadesc}
 136
 137 \begin{funcdesc}{gmtime}{secs}
 138 Convert a time expressed in seconds since the epoch to a time tuple
 139 in UTC in which the dst flag is always zero.  Fractions of a second are
 140 ignored.  See above for a description of the tuple lay-out.
 141 \end{funcdesc}
 142
 143 \begin{funcdesc}{localtime}{secs}
 144 Like \function{gmtime()} but converts to local time.  The dst flag is
 145 set to \code{1} when DST applies to the given time.
 146 \end{funcdesc}
 147
 148 \begin{funcdesc}{mktime}{tuple}
 149 This is the inverse function of \function{localtime()}.  Its argument
 150 is the full 9-tuple (since the dst flag is needed --- pass \code{-1}
 151 as the dst flag if it is unknown) which expresses the time in
 152 \emph{local} time, not UTC.  It returns a floating point number, for
 153 compatibility with \function{time()}.  If the input value cannot be
 154 represented as a valid time, \exception{OverflowError} is raised.
 155 \end{funcdesc}
 156
 157 \begin{funcdesc}{sleep}{secs}
 158 Suspend execution for the given number of seconds.  The argument may
 159 be a floating point number to indicate a more precise sleep time.
 160 \end{funcdesc}
 161
 162 \begin{funcdesc}{strftime}{format, tuple}
 163 Convert a tuple representing a time as returned by \function{gmtime()}
 164 or \function{localtime()} to a string as specified by the \var{format}
 165 argument.  \var{format} must be a string.
 166
 167 The following directives can be embedded in the \var{format} string.
 168 They are shown without the optional field width and precision
 169 specification, and are replaced by the indicated characters in the
 170 \function{strftime()} result:
 171
 172 \begin{tableii}{c|p{24em}}{code}{Directive}{Meaning}
 173   \lineii{\%a}{Locale's abbreviated weekday name.}
 174   \lineii{\%A}{Locale's full weekday name.}
 175   \lineii{\%b}{Locale's abbreviated month name.}
 176   \lineii{\%B}{Locale's full month name.}
 177   \lineii{\%c}{Locale's appropriate date and time representation.}
 178   \lineii{\%d}{Day of the month as a decimal number [01,31].}
 179   \lineii{\%H}{Hour (24-hour clock) as a decimal number [00,23].}
 180   \lineii{\%I}{Hour (12-hour clock) as a decimal number [01,12].}
 181   \lineii{\%j}{Day of the year as a decimal number [001,366].}
 182   \lineii{\%m}{Month as a decimal number [01,12].}
 183   \lineii{\%M}{Minute as a decimal number [00,59].}
 184   \lineii{\%p}{Locale's equivalent of either AM or PM.}
 185   \lineii{\%S}{Second as a decimal number [00,61].}
 186   \lineii{\%U}{Week number of the year (Sunday as the first day of the
 187                week) as a decimal number [00,53].  All days in a new year
 188                preceding the first Sunday are considered to be in week 0.}
 189   \lineii{\%w}{Weekday as a decimal number [0(Sunday),6].}
 190   \lineii{\%W}{Week number of the year (Monday as the first day of the
 191                week) as a decimal number [00,53].  All days in a new year
 192                preceding the first Sunday are considered to be in week 0.}
 193   \lineii{\%x}{Locale's appropriate date representation.}
 194   \lineii{\%X}{Locale's appropriate time representation.}
 195   \lineii{\%y}{Year without century as a decimal number [00,99].}
 196   \lineii{\%Y}{Year with century as a decimal number.}
 197   \lineii{\%Z}{Time zone name (or by no characters if no time zone exists).}
 198   \lineii{\%\%}{\%}
 199 \end{tableii}
 200
 201 Additional directives may be supported on certain platforms, but
 202 only the ones listed here have a meaning standardized by ANSI \C{}.
 203
 204 On some platforms, an optional field width and precision
 205 specification can immediately follow the initial \character{\%} of a
 206 directive in the following order; this is also not portable.
 207 The field width is normally 2 except for \code{\%j} where it is 3.
 208 \end{funcdesc}
 209
 210 \begin{funcdesc}{strptime}{string\optional{, format}}
 211 Parse a string representing a time according to a format.  The return
 212 value is a tuple as returned by \function{gmtime()} or
 213 \function{localtime()}.  The \var{format} parameter uses the same
 214 directives as those used by \function{strftime()}; it defaults to
 215 \code{"\%a \%b \%d \%H:\%M:\%S \%Y"} which matches the formatting
 216 returned by \function{ctime()}.  The same platform caveats apply; see
 217 the local \UNIX{} documentation for restrictions or additional
 218 supported directives.  If \var{string} cannot be parsed according to
 219 \var{format}, \exception{ValueError} is raised.  This function may not
 220 be defined on all platforms.
 221 \end{funcdesc}
 222
 223 \begin{funcdesc}{time}{}
 224 Return the time as a floating point number expressed in seconds since
 225 the epoch, in UTC.  Note that even though the time is always returned
 226 as a floating point number, not all systems provide time with a better
 227 precision than 1 second.
 228 \end{funcdesc}
 229
 230 \begin{datadesc}{timezone}
 231 The offset of the local (non-DST) timezone, in seconds west of the 0th
 232 meridian (i.e. negative in most of Western Europe, positive in the US,
 233 zero in the UK).
 234 \end{datadesc}
 235
 236 \begin{datadesc}{tzname}
 237 A tuple of two strings: the first is the name of the local non-DST
 238 timezone, the second is the name of the local DST timezone.  If no DST
 239 timezone is defined, the second string should not be used.
 240 \end{datadesc}
 241