Doc/lib/libtime.tex

   1 \section{\module{time} ---
   2          Time access and conversions}
   3
   4 \declaremodule{builtin}{time}
   5 \modulesynopsis{Time access and conversions.}
   6
   7
   8 This module provides various time-related functions.  It is always
   9 available, but not all functions are available on all platforms.  Most
  10 of the functions defined in this module call platform C library
  11 functions with the same name.  It may sometimes be helpful to consult
  12 the platform documentation, because the semantics of these functions
  13 varies among platforms.
  14
  15 An explanation of some terminology and conventions is in order.
  16
  17 \begin{itemize}
  18
  19 \item
  20 The \dfn{epoch}\index{epoch} is the point where the time starts.  On
  21 January 1st of that year, at 0 hours, the ``time since the epoch'' is
  22 zero.  For \UNIX, the epoch is 1970.  To find out what the epoch is,
  23 look at \code{gmtime(0)}.
  24
  25 \item
  26 The functions in this module do not handle dates and times before the
  27 epoch or far in the future.  The cut-off point in the future is
  28 determined by the C library; for \UNIX, it is typically in
  29 2038\index{Year 2038}.
  30
  31 \item
  32 \strong{Year 2000 (Y2K) issues}:\index{Year 2000}\index{Y2K}  Python
  33 depends on the platform's C library, which generally doesn't have year
  34 2000 issues, since all dates and times are represented internally as
  35 seconds since the epoch.  Functions accepting a \class{struct_time}
  36 (see below) generally require a 4-digit year.  For backward
  37 compatibility, 2-digit years are supported if the module variable
  38 \code{accept2dyear} is a non-zero integer; this variable is
  39 initialized to \code{1} unless the environment variable
  40 \envvar{PYTHONY2K} is set to a non-empty string, in which case it is
  41 initialized to \code{0}.  Thus, you can set
  42 \envvar{PYTHONY2K} to a non-empty string in the environment to require 4-digit
  43 years for all year input.  When 2-digit years are accepted, they are
  44 converted according to the \POSIX{} or X/Open standard: values 69-99
  45 are mapped to 1969-1999, and values 0--68 are mapped to 2000--2068.
  46 Values 100--1899 are always illegal.  Note that this is new as of
  47 Python 1.5.2(a2); earlier versions, up to Python 1.5.1 and 1.5.2a1,
  48 would add 1900 to year values below 1900.
  49
  50 \item
  51 UTC\index{UTC} is Coordinated Universal Time\index{Coordinated
  52 Universal Time} (formerly known as Greenwich Mean
  53 Time,\index{Greenwich Mean Time} or GMT).  The acronym UTC is not a
  54 mistake but a compromise between English and French.
  55
  56 \item
  57 DST is Daylight Saving Time,\index{Daylight Saving Time} an adjustment
  58 of the timezone by (usually) one hour during part of the year.  DST
  59 rules are magic (determined by local law) and can change from year to
  60 year.  The C library has a table containing the local rules (often it
  61 is read from a system file for flexibility) and is the only source of
  62 True Wisdom in this respect.
  63
  64 \item
  65 The precision of the various real-time functions may be less than
  66 suggested by the units in which their value or argument is expressed.
  67 E.g.\ on most \UNIX{} systems, the clock ``ticks'' only 50 or 100 times a
  68 second, and on the Mac, times are only accurate to whole seconds.
  69
  70 \item
  71 On the other hand, the precision of \function{time()} and
  72 \function{sleep()} is better than their \UNIX{} equivalents: times are
  73 expressed as floating point numbers, \function{time()} returns the
  74 most accurate time available (using \UNIX{} \cfunction{gettimeofday()}
  75 where available), and \function{sleep()} will accept a time with a
  76 nonzero fraction (\UNIX{} \cfunction{select()} is used to implement
  77 this, where available).
  78
  79 \item
  80 The time value as returned by \function{gmtime()},
  81 \function{localtime()}, and \function{strptime()}, and accepted by
  82 \function{asctime()}, \function{mktime()} and \function{strftime()},
  83 is a sequence of 9 integers.  The return values of \function{gmtime()},
  84 \function{localtime()}, and \function{strptime()} also offer attribute
  85 names for individual fields.
  86
  87 \begin{tableiii}{c|l|l}{textrm}{Index}{Attribute}{Values}
  88   \lineiii{0}{\member{tm_year}}{(for example, 1993)}
  89   \lineiii{1}{\member{tm_mon}}{range [1,12]}
  90   \lineiii{2}{\member{tm_mday}}{range [1,31]}
  91   \lineiii{3}{\member{tm_hour}}{range [0,23]}
  92   \lineiii{4}{\member{tm_min}}{range [0,59]}
  93   \lineiii{5}{\member{tm_sec}}{range [0,61]; see \strong{(1)} in \function{strftime()} description}
  94   \lineiii{6}{\member{tm_wday}}{range [0,6], Monday is 0}
  95   \lineiii{7}{\member{tm_yday}}{range [1,366]}
  96   \lineiii{8}{\member{tm_isdst}}{0, 1 or -1; see below}
  97 \end{tableiii}
  98
  99 Note that unlike the C structure, the month value is a
 100 range of 1-12, not 0-11.  A year value will be handled as described
 101 under ``Year 2000 (Y2K) issues'' above.  A \code{-1} argument as the
 102 daylight savings flag, passed to \function{mktime()} will usually
 103 result in the correct daylight savings state to be filled in.
 104
 105 When a tuple with an incorrect length is passed to a function
 106 expecting a \class{struct_time}, or having elements of the wrong type, a
 107 \exception{TypeError} is raised.
 108
 109 \versionchanged[The time value sequence was changed from a tuple to a
 110                 \class{struct_time}, with the addition of attribute names
 111                 for the fields]{2.2}
 112 \end{itemize}
 113
 114 The module defines the following functions and data items:
 115
 116
 117 \begin{datadesc}{accept2dyear}
 118 Boolean value indicating whether two-digit year values will be
 119 accepted.  This is true by default, but will be set to false if the
 120 environment variable \envvar{PYTHONY2K} has been set to a non-empty
 121 string.  It may also be modified at run time.
 122 \end{datadesc}
 123
 124 \begin{datadesc}{altzone}
 125 The offset of the local DST timezone, in seconds west of UTC, if one
 126 is defined.  This is negative if the local DST timezone is east of UTC
 127 (as in Western Europe, including the UK).  Only use this if
 128 \code{daylight} is nonzero.
 129 \end{datadesc}
 130
 131 \begin{funcdesc}{asctime}{\optional{t}}
 132 Convert a tuple or \class{struct_time} representing a time as returned
 133 by \function{gmtime()}
 134 or \function{localtime()} to a 24-character string of the following form:
 135 \code{'Sun Jun 20 23:21:05 1993'}.  If \var{t} is not provided, the
 136 current time as returned by \function{localtime()} is used.
 137 Locale information is not used by \function{asctime()}.
 138 \note{Unlike the C function of the same name, there is no trailing
 139 newline.}
 140 \versionchanged[Allowed \var{t} to be omitted]{2.1}
 141 \end{funcdesc}
 142
 143 \begin{funcdesc}{clock}{}
 144 On \UNIX, return
 145 the current processor time as a floating point number expressed in
 146 seconds.  The precision, and in fact the very definition of the meaning
 147 of ``processor time''\index{CPU time}\index{processor time}, depends
 148 on that of the C function of the same name, but in any case, this is
 149 the function to use for benchmarking\index{benchmarking} Python or
 150 timing algorithms.
 151
 152 On Windows, this function returns wall-clock seconds elapsed since the
 153 first call to this function, as a floating point number,
 154 based on the Win32 function \cfunction{QueryPerformanceCounter()}.
 155 The resolution is typically better than one microsecond.
 156 \end{funcdesc}
 157
 158 \begin{funcdesc}{ctime}{\optional{secs}}
 159 Convert a time expressed in seconds since the epoch to a string
 160 representing local time. If \var{secs} is not provided, the current time
 161 as returned by \function{time()} is used.  \code{ctime(\var{secs})}
 162 is equivalent to \code{asctime(localtime(\var{secs}))}.
 163 Locale information is not used by \function{ctime()}.
 164 \versionchanged[Allowed \var{secs} to be omitted]{2.1}
 165 \end{funcdesc}
 166
 167 \begin{datadesc}{daylight}
 168 Nonzero if a DST timezone is defined.
 169 \end{datadesc}
 170
 171 \begin{funcdesc}{gmtime}{\optional{secs}}
 172 Convert a time expressed in seconds since the epoch to a \class{struct_time}
 173 in UTC in which the dst flag is always zero.  If \var{secs} is not
 174 provided, the current time as returned by \function{time()} is used.
 175 Fractions of a second are ignored.  See above for a description of the
 176 \class{struct_time} object.
 177 \versionchanged[Allowed \var{secs} to be omitted]{2.1}
 178 \end{funcdesc}
 179
 180 \begin{funcdesc}{localtime}{\optional{secs}}
 181 Like \function{gmtime()} but converts to local time.  The dst flag is
 182 set to \code{1} when DST applies to the given time.
 183 \versionchanged[Allowed \var{secs} to be omitted]{2.1}
 184 \end{funcdesc}
 185
 186 \begin{funcdesc}{mktime}{t}
 187 This is the inverse function of \function{localtime()}.  Its argument
 188 is the \class{struct_time} or full 9-tuple (since the dst flag is
 189 needed; use \code{-1} as the dst flag if it is unknown) which
 190 expresses the time in
 191 \emph{local} time, not UTC.  It returns a floating point number, for
 192 compatibility with \function{time()}.  If the input value cannot be
 193 represented as a valid time, either \exception{OverflowError} or
 194 \exception{ValueError} will be raised (which depends on whether the
 195 invalid value is caught by Python or the underlying C libraries).  The
 196 earliest date for which it can generate a time is platform-dependent.
 197 \end{funcdesc}
 198
 199 \begin{funcdesc}{sleep}{secs}
 200 Suspend execution for the given number of seconds.  The argument may
 201 be a floating point number to indicate a more precise sleep time.
 202 The actual suspension time may be less than that requested because any
 203 caught signal will terminate the \function{sleep()} following
 204 execution of that signal's catching routine.  Also, the suspension
 205 time may be longer than requested by an arbitrary amount because of
 206 the scheduling of other activity in the system.
 207 \end{funcdesc}
 208
 209 \begin{funcdesc}{strftime}{format\optional{, t}}
 210 Convert a tuple or \class{struct_time} representing a time as returned
 211 by \function{gmtime()} or \function{localtime()} to a string as
 212 specified by the \var{format} argument.  If \var{t} is not
 213 provided, the current time as returned by \function{localtime()} is
 214 used.  \var{format} must be a string.  \exception{ValueError} is raised
 215 if any field in \var{t} is outside of the allowed range.
 216 \versionchanged[Allowed \var{t} to be omitted]{2.1}
 217 \versionchanged[\exception{ValueError} raised if a field in \var{t} is
 218 out of range.]{2.4}
 219
 220 The following directives can be embedded in the \var{format} string.
 221 They are shown without the optional field width and precision
 222 specification, and are replaced by the indicated characters in the
 223 \function{strftime()} result:
 224
 225 \begin{tableiii}{c|p{24em}|c}{code}{Directive}{Meaning}{Notes}
 226   \lineiii{\%a}{Locale's abbreviated weekday name.}{}
 227   \lineiii{\%A}{Locale's full weekday name.}{}
 228   \lineiii{\%b}{Locale's abbreviated month name.}{}
 229   \lineiii{\%B}{Locale's full month name.}{}
 230   \lineiii{\%c}{Locale's appropriate date and time representation.}{}
 231   \lineiii{\%d}{Day of the month as a decimal number [01,31].}{}
 232   \lineiii{\%H}{Hour (24-hour clock) as a decimal number [00,23].}{}
 233   \lineiii{\%I}{Hour (12-hour clock) as a decimal number [01,12].}{}
 234   \lineiii{\%j}{Day of the year as a decimal number [001,366].}{}
 235   \lineiii{\%m}{Month as a decimal number [01,12].}{}
 236   \lineiii{\%M}{Minute as a decimal number [00,59].}{}
 237   \lineiii{\%p}{Locale's equivalent of either AM or PM.}{(1)}
 238   \lineiii{\%S}{Second as a decimal number [00,61].}{(2)}
 239   \lineiii{\%U}{Week number of the year (Sunday as the first day of the
 240                 week) as a decimal number [00,53].  All days in a new year
 241                 preceding the first Sunday are considered to be in week 0.}{}
 242   \lineiii{\%w}{Weekday as a decimal number [0(Sunday),6].}{}
 243   \lineiii{\%W}{Week number of the year (Monday as the first day of the
 244                 week) as a decimal number [00,53].  All days in a new year
 245                 preceding the first Monday are considered to be in week 0.}{}
 246   \lineiii{\%x}{Locale's appropriate date representation.}{}
 247   \lineiii{\%X}{Locale's appropriate time representation.}{}
 248   \lineiii{\%y}{Year without century as a decimal number [00,99].}{}
 249   \lineiii{\%Y}{Year with century as a decimal number.}{}
 250   \lineiii{\%Z}{Time zone name (no characters if no time zone exists).}{}
 251   \lineiii{\%\%}{A literal \character{\%} character.}{}
 252 \end{tableiii}
 253
 254 \noindent
 255 Notes:
 256
 257 \begin{description}
 258   \item[(1)]
 259     When used with the \function{strptime()} function, the \code{\%p}
 260     directive only affects the output hour field if the \code{\%I} directive
 261     is used to parse the hour.
 262   \item[(2)]
 263     The range really is \code{0} to \code{61}; this accounts for leap
 264     seconds and the (very rare) double leap seconds.
 265 \end{description}
 266
 267 Here is an example, a format for dates compatible with that specified
 268 in the \rfc{2822} Internet email standard.
 269         \footnote{The use of \code{\%Z} is now
 270         deprecated, but the \code{\%z} escape that expands to the preferred
 271         hour/minute offset is not supported by all ANSI C libraries. Also,
 272         a strict reading of the original 1982 \rfc{822} standard calls for
 273         a two-digit year (\%y rather than \%Y), but practice moved to
 274         4-digit years long before the year 2000.  The 4-digit year has
 275         been mandated by \rfc{2822}, which obsoletes \rfc{822}.}
 276
 277 \begin{verbatim}
 278 >>> from time import gmtime, strftime
 279 >>> strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime())
 280 'Thu, 28 Jun 2001 14:17:15 +0000'
 281 \end{verbatim}
 282
 283 Additional directives may be supported on certain platforms, but
 284 only the ones listed here have a meaning standardized by ANSI C.
 285
 286 On some platforms, an optional field width and precision
 287 specification can immediately follow the initial \character{\%} of a
 288 directive in the following order; this is also not portable.
 289 The field width is normally 2 except for \code{\%j} where it is 3.
 290 \end{funcdesc}
 291
 292 \begin{funcdesc}{strptime}{string\optional{, format}}
 293 Parse a string representing a time according to a format.  The return
 294 value is a \class{struct_time} as returned by \function{gmtime()} or
 295 \function{localtime()}.  The \var{format} parameter uses the same
 296 directives as those used by \function{strftime()}; it defaults to
 297 \code{"\%a \%b \%d \%H:\%M:\%S \%Y"} which matches the formatting
 298 returned by \function{ctime()}.  If \var{string} cannot be parsed
 299 according to \var{format}, \exception{ValueError} is raised.  If the
 300 string to be parsed has excess data after parsing,
 301 \exception{ValueError} is raised.  The default values used to fill in
 302 any missing data is \code{(1900, 1, 1, 0, 0, 0, 0, 1, -1)} .
 303
 304 Support for the \code{\%Z} directive is based on the values contained in
 305 \code{tzname} and whether \code{daylight} is true.  Because of this,
 306 it is platform-specific except for recognizing UTC and GMT which are
 307 always known (and are considered to be non-daylight savings
 308 timezones).
 309 \end{funcdesc}
 310
 311 \begin{datadesc}{struct_time}
 312 The type of the time value sequence returned by \function{gmtime()},
 313 \function{localtime()}, and \function{strptime()}.
 314 \versionadded{2.2}
 315 \end{datadesc}
 316
 317 \begin{funcdesc}{time}{}
 318 Return the time as a floating point number expressed in seconds since
 319 the epoch, in UTC.  Note that even though the time is always returned
 320 as a floating point number, not all systems provide time with a better
 321 precision than 1 second.  While this function normally returns
 322 non-decreasing values, it can return a lower value than a previous
 323 call if the system clock has been set back between the two calls.
 324 \end{funcdesc}
 325
 326 \begin{datadesc}{timezone}
 327 The offset of the local (non-DST) timezone, in seconds west of UTC
 328 (negative in most of Western Europe, positive in the US, zero in the
 329 UK).
 330 \end{datadesc}
 331
 332 \begin{datadesc}{tzname}
 333 A tuple of two strings: the first is the name of the local non-DST
 334 timezone, the second is the name of the local DST timezone.  If no DST
 335 timezone is defined, the second string should not be used.
 336 \end{datadesc}
 337
 338 \begin{funcdesc}{tzset}{}
 339 Resets the time conversion rules used by the library routines.
 340 The environment variable \envvar{TZ} specifies how this is done.
 341 \versionadded{2.3}
 342
 343 Availability: \UNIX.
 344
 345 \begin{notice}
 346 Although in many cases, changing the \envvar{TZ} environment variable
 347 may affect the output of functions like \function{localtime} without calling
 348 \function{tzset}, this behavior should not be relied on.
 349
 350 The \envvar{TZ} environment variable should contain no whitespace.
 351 \end{notice}
 352
 353 The standard format of the \envvar{TZ} environment variable is:
 354 (whitespace added for clarity)
 355 \begin{itemize}
 356     \item[std offset [dst [offset] [,start[/time], end[/time]]]]
 357 \end{itemize}
 358
 359 Where:
 360
 361 \begin{itemize}
 362   \item[std and dst]
 363     Three or more alphanumerics giving the timezone abbreviations.
 364     These will be propogated into time.tzname
 365
 366   \item[offset]
 367     The offset has the form: \plusminus{} hh[:mm[:ss]].
 368     This indicates the value added the local time to arrive at UTC.
 369     If preceded by a '-', the timezone is east of the Prime
 370     Meridian; otherwise, it is west. If no offset follows
 371     dst, summmer time is assumed to be one hour ahead of standard time.
 372
 373   \item[start[/time],end[/time]]
 374     Indicates when to change to and back from DST. The format of the
 375     start and end dates are one of the following:
 376
 377     \begin{itemize}
 378       \item[J\var{n}]
 379         The Julian day \var{n} (1 <= \var{n} <= 365). Leap days are not
 380         counted, so in all years February 28 is day 59 and
 381         March 1 is day 60.
 382
 383     \item[\var{n}]
 384         The zero-based Julian day (0 <= \var{n} <= 365). Leap days are
 385         counted, and it is possible to refer to February 29.
 386
 387       \item[M\var{m}.\var{n}.\var{d}]
 388         The \var{d}'th day (0 <= \var{d} <= 6) or week \var{n}
 389         of month \var{m} of the year (1 <= \var{n} <= 5,
 390         1 <= \var{m} <= 12, where week 5 means "the last \var{d} day
 391         in month \var{m}" which may occur in either the fourth or
 392         the fifth week). Week 1 is the first week in which the
 393         \var{d}'th day occurs. Day zero is Sunday.
 394     \end{itemize}
 395
 396     time has the same format as offset except that no leading sign ('-' or
 397     '+') is allowed. The default, if time is not given, is 02:00:00.
 398 \end{itemize}
 399
 400
 401 \begin{verbatim}
 402 >>> os.environ['TZ'] = 'EST+05EDT,M4.1.0,M10.5.0'
 403 >>> time.tzset()
 404 >>> time.strftime('%X %x %Z')
 405 '02:07:36 05/08/03 EDT'
 406 >>> os.environ['TZ'] = 'AEST-10AEDT-11,M10.5.0,M3.5.0'
 407 >>> time.tzset()
 408 >>> time.strftime('%X %x %Z')
 409 '16:08:12 05/08/03 AEST'
 410 \end{verbatim}
 411
 412 On many Unix systems (including *BSD, Linux, Solaris, and Darwin), it
 413 is more convenient to use the system's zoneinfo (\manpage{tzfile}{5})
 414 database to specify the timezone rules. To do this, set the
 415 \envvar{TZ} environment variable to the path of the required timezone
 416 datafile, relative to the root of the systems 'zoneinfo' timezone database,
 417 usually located at \file{/usr/share/zoneinfo}. For example,
 418 \code{'US/Eastern'}, \code{'Australia/Melbourne'}, \code{'Egypt'} or
 419 \code{'Europe/Amsterdam'}.
 420
 421 \begin{verbatim}
 422 >>> os.environ['TZ'] = 'US/Eastern'
 423 >>> time.tzset()
 424 >>> time.tzname
 425 ('EST', 'EDT')
 426 >>> os.environ['TZ'] = 'Egypt'
 427 >>> time.tzset()
 428 >>> time.tzname
 429 ('EET', 'EEST')
 430 \end{verbatim}
 431
 432 \end{funcdesc}
 433
 434
 435 \begin{seealso}
 436   \seemodule{datetime}{More object-oriented interface to dates and times.}
 437   \seemodule{locale}{Internationalization services.  The locale
 438                      settings can affect the return values for some of
 439                      the functions in the \module{time} module.}
 440   \seemodule{calendar}{General calendar-related functions.
 441                        \function{timegm()} is the inverse of
 442                        \function{gmtime()} from this module.}
 443 \end{seealso}