242 lines
10 KiB
TeX
242 lines
10 KiB
TeX
\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 will be handled as descibed under
|
|
``Year 2000 (Y2K) issues'' above. 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}{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 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}
|
|
|