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.
 215 \versionchanged[Allowed \var{t} to be omitted]{2.1}
 216
 217 The following directives can be embedded in the \var{format} string.
 218 They are shown without the optional field width and precision
 219 specification, and are replaced by the indicated characters in the
 220 \function{strftime()} result:
 221
 222 \begin{tableiii}{c|p{24em}|c}{code}{Directive}{Meaning}{Notes}
 223   \lineiii{\%a}{Locale's abbreviated weekday name.}{}
 224   \lineiii{\%A}{Locale's full weekday name.}{}
 225   \lineiii{\%b}{Locale's abbreviated month name.}{}
 226   \lineiii{\%B}{Locale's full month name.}{}
 227   \lineiii{\%c}{Locale's appropriate date and time representation.}{}
 228   \lineiii{\%d}{Day of the month as a decimal number [01,31].}{}
 229   \lineiii{\%H}{Hour (24-hour clock) as a decimal number [00,23].}{}
 230   \lineiii{\%I}{Hour (12-hour clock) as a decimal number [01,12].}{}
 231   \lineiii{\%j}{Day of the year as a decimal number [001,366].}{}
 232   \lineiii{\%m}{Month as a decimal number [01,12].}{}
 233   \lineiii{\%M}{Minute as a decimal number [00,59].}{}
 234   \lineiii{\%p}{Locale's equivalent of either AM or PM.}{}
 235   \lineiii{\%S}{Second as a decimal number [00,61].}{(1)}
 236   \lineiii{\%U}{Week number of the year (Sunday as the first day of the
 237                 week) as a decimal number [00,53].  All days in a new year
 238                 preceding the first Sunday are considered to be in week 0.}{}
 239   \lineiii{\%w}{Weekday as a decimal number [0(Sunday),6].}{}
 240   \lineiii{\%W}{Week number of the year (Monday as the first day of the
 241                 week) as a decimal number [00,53].  All days in a new year
 242                 preceding the first Monday are considered to be in week 0.}{}
 243   \lineiii{\%x}{Locale's appropriate date representation.}{}
 244   \lineiii{\%X}{Locale's appropriate time representation.}{}
 245   \lineiii{\%y}{Year without century as a decimal number [00,99].}{}
 246   \lineiii{\%Y}{Year with century as a decimal number.}{}
 247   \lineiii{\%Z}{Time zone name (no characters if no time zone exists).}{}
 248   \lineiii{\%\%}{A literal \character{\%} character.}{}
 249 \end{tableiii}
 250
 251 \noindent
 252 Notes:
 253
 254 \begin{description}
 255   \item[(1)]
 256     The range really is \code{0} to \code{61}; this accounts for leap
 257     seconds and the (very rare) double leap seconds.
 258 \end{description}
 259
 260 Here is an example, a format for dates compatible with that specified
 261 in the \rfc{2822} Internet email standard.
 262         \footnote{The use of \code{\%Z} is now
 263         deprecated, but the \code{\%z} escape that expands to the preferred
 264         hour/minute offset is not supported by all ANSI C libraries. Also,
 265         a strict reading of the original 1982 \rfc{822} standard calls for
 266         a two-digit year (\%y rather than \%Y), but practice moved to
 267         4-digit years long before the year 2000.  The 4-digit year has
 268         been mandated by \rfc{2822}, which obsoletes \rfc{822}.}
 269
 270 \begin{verbatim}
 271 >>> from time import gmtime, strftime
 272 >>> strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime())
 273 'Thu, 28 Jun 2001 14:17:15 +0000'
 274 \end{verbatim}
 275
 276 Additional directives may be supported on certain platforms, but
 277 only the ones listed here have a meaning standardized by ANSI C.
 278
 279 On some platforms, an optional field width and precision
 280 specification can immediately follow the initial \character{\%} of a
 281 directive in the following order; this is also not portable.
 282 The field width is normally 2 except for \code{\%j} where it is 3.
 283 \end{funcdesc}
 284
 285 \begin{funcdesc}{strptime}{string\optional{, format}}
 286 Parse a string representing a time according to a format.  The return
 287 value is a \class{struct_time} as returned by \function{gmtime()} or
 288 \function{localtime()}.  The \var{format} parameter uses the same
 289 directives as those used by \function{strftime()}; it defaults to
 290 \code{"\%a \%b \%d \%H:\%M:\%S \%Y"} which matches the formatting
 291 returned by \function{ctime()}.  If \var{string} cannot be parsed
 292 according to \var{format}, \exception{ValueError} is raised.  If the
 293 string to be parsed has excess data after parsing,
 294 \exception{ValueError} is raised.  The default values used to fill in
 295 any missing data is \code{(1900, 1, 1, 0, 0, 0, 0, 1, -1)} .
 296
 297 Support for the \code{\%Z} directive is based on the values contained in
 298 \code{tzname} and whether \code{daylight} is true.  Because of this,
 299 it is platform-specific except for recognizing UTC and GMT which are
 300 always known (and are considered to be non-daylight savings
 301 timezones).
 302 \end{funcdesc}
 303
 304 \begin{datadesc}{struct_time}
 305 The type of the time value sequence returned by \function{gmtime()},
 306 \function{localtime()}, and \function{strptime()}.
 307 \versionadded{2.2}
 308 \end{datadesc}
 309
 310 \begin{funcdesc}{time}{}
 311 Return the time as a floating point number expressed in seconds since
 312 the epoch, in UTC.  Note that even though the time is always returned
 313 as a floating point number, not all systems provide time with a better
 314 precision than 1 second.  While this function normally returns
 315 non-decreasing values, it can return a lower value than a previous
 316 call if the system clock has been set back between the two calls.
 317 \end{funcdesc}
 318
 319 \begin{datadesc}{timezone}
 320 The offset of the local (non-DST) timezone, in seconds west of UTC
 321 (negative in most of Western Europe, positive in the US, zero in the
 322 UK).
 323 \end{datadesc}
 324
 325 \begin{datadesc}{tzname}
 326 A tuple of two strings: the first is the name of the local non-DST
 327 timezone, the second is the name of the local DST timezone.  If no DST
 328 timezone is defined, the second string should not be used.
 329 \end{datadesc}
 330
 331 \begin{funcdesc}{tzset}{}
 332 Resets the time conversion rules used by the library routines.
 333 The environment variable \envvar{TZ} specifies how this is done.
 334 \versionadded{2.3}
 335
 336 Availability: \UNIX.
 337
 338 \begin{notice}
 339 Although in many cases, changing the \envvar{TZ} environment variable
 340 may affect the output of functions like \function{localtime} without calling
 341 \function{tzset}, this behavior should not be relied on.
 342
 343 The \envvar{TZ} environment variable should contain no whitespace.
 344 \end{notice}
 345
 346 The standard format of the \envvar{TZ} environment variable is:
 347 (whitespace added for clarity)
 348 \begin{itemize}
 349     \item[std offset [dst [offset] [,start[/time], end[/time]]]]
 350 \end{itemize}
 351
 352 Where:
 353
 354 \begin{itemize}
 355   \item[std and dst]
 356     Three or more alphanumerics giving the timezone abbreviations.
 357     These will be propogated into time.tzname
 358
 359   \item[offset]
 360     The offset has the form: \plusminus hh[:mm[:ss]].
 361     This indicates the value added the local time to arrive at UTC.
 362     If preceded by a '-', the timezone is east of the Prime
 363     Meridian; otherwise, it is west. If no offset follows
 364     dst, summmer time is assumed to be one hour ahead of standard time.
 365
 366   \item[start[/time],end[/time]]
 367     Indicates when to change to and back from DST. The format of the
 368     start and end dates are one of the following:
 369
 370     \begin{itemize}
 371       \item[J\var{n}]
 372         The Julian day \var{n} (1 <= \var{n} <= 365). Leap days are not
 373         counted, so in all years February 28 is day 59 and
 374         March 1 is day 60.
 375
 376     \item[\var{n}]
 377         The zero-based Julian day (0 <= \var{n} <= 365). Leap days are
 378         counted, and it is possible to refer to February 29.
 379
 380       \item[M\var{m}.\var{n}.\var{d}]
 381         The \var{d}'th day (0 <= \var{d} <= 6) or week \var{n}
 382         of month \var{m} of the year (1 <= \var{n} <= 5,
 383         1 <= \var{m} <= 12, where week 5 means "the last \var{d} day
 384         in month \var{m}" which may occur in either the fourth or
 385         the fifth week). Week 1 is the first week in which the
 386         \var{d}'th day occurs. Day zero is Sunday.
 387     \end{itemize}
 388
 389     time has the same format as offset except that no leading sign ('-' or
 390     '+') is allowed. The default, if time is not given, is 02:00:00.
 391 \end{itemize}
 392
 393
 394 \begin{verbatim}
 395 >>> os.environ['TZ'] = 'EST+05EDT,M4.1.0,M10.5.0'
 396 >>> time.tzset()
 397 >>> time.strftime('%X %x %Z')
 398 '02:07:36 05/08/03 EDT'
 399 >>> os.environ['TZ'] = 'AEST-10AEDT-11,M10.5.0,M3.5.0'
 400 >>> time.tzset()
 401 >>> time.strftime('%X %x %Z')
 402 '16:08:12 05/08/03 AEST'
 403 \end{verbatim}
 404
 405 On many Unix systems (including *BSD, Linux, Solaris, and Darwin), it
 406 is more convenient to use the system's zoneinfo (\manpage{tzfile}{5})
 407 database to specify the timezone rules. To do this, set the
 408 \envvar{TZ} environment variable to the path of the required timezone
 409 datafile, relative to the root of the systems 'zoneinfo' timezone database,
 410 usually located at \file{/usr/share/zoneinfo}. For example,
 411 \code{'US/Eastern'}, \code{'Australia/Melbourne'}, \code{'Egypt'} or
 412 \code{'Europe/Amsterdam'}.
 413
 414 \begin{verbatim}
 415 >>> os.environ['TZ'] = 'US/Eastern'
 416 >>> time.tzset()
 417 >>> time.tzname
 418 ('EST', 'EDT')
 419 >>> os.environ['TZ'] = 'Egypt'
 420 >>> time.tzset()
 421 >>> time.tzname
 422 ('EET', 'EEST')
 423 \end{verbatim}
 424
 425 \end{funcdesc}
 426
 427
 428 \begin{seealso}
 429   \seemodule{locale}{Internationalization services.  The locale
 430                      settings can affect the return values for some of
 431                      the functions in the \module{time} module.}
 432   \seemodule{calendar}{General calendar-related functions.
 433                        \function{timegm()} is the inverse of
 434                        \function{gmtime()} from this module.}
 435 \end{seealso}