mirror of https://github.com/python/cpython
437 lines
18 KiB
TeX
437 lines
18 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, but not all functions are available on all platforms. Most
|
|
of the functions defined in this module call platform C library
|
|
functions with the same name. It may sometimes be helpful to consult
|
|
the platform documentation, because the semantics of these functions
|
|
varies among platforms.
|
|
|
|
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)}.
|
|
|
|
\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}:\index{Year 2000}\index{Y2K} 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 \class{struct_time}
|
|
(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} to a non-empty string in the environment 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.
|
|
|
|
\item
|
|
UTC\index{UTC} is Coordinated Universal Time\index{Coordinated
|
|
Universal Time} (formerly known as Greenwich Mean
|
|
Time,\index{Greenwich Mean Time} or GMT). The acronym UTC is not a
|
|
mistake but a compromise between English and French.
|
|
|
|
\item
|
|
DST is Daylight Saving Time,\index{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.
|
|
|
|
\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 value as returned by \function{gmtime()},
|
|
\function{localtime()}, and \function{strptime()}, and accepted by
|
|
\function{asctime()}, \function{mktime()} and \function{strftime()},
|
|
is a sequence of 9 integers. The return values of \function{gmtime()},
|
|
\function{localtime()}, and \function{strptime()} also offer attribute
|
|
names for individual fields.
|
|
|
|
\begin{tableiii}{c|l|l}{textrm}{Index}{Attribute}{Values}
|
|
\lineiii{0}{\member{tm_year}}{(for example, 1993)}
|
|
\lineiii{1}{\member{tm_mon}}{range [1,12]}
|
|
\lineiii{2}{\member{tm_mday}}{range [1,31]}
|
|
\lineiii{3}{\member{tm_hour}}{range [0,23]}
|
|
\lineiii{4}{\member{tm_min}}{range [0,59]}
|
|
\lineiii{5}{\member{tm_sec}}{range [0,61]; see \strong{(1)} in \function{strftime()} description}
|
|
\lineiii{6}{\member{tm_wday}}{range [0,6], Monday is 0}
|
|
\lineiii{7}{\member{tm_yday}}{range [1,366]}
|
|
\lineiii{8}{\member{tm_isdst}}{0, 1 or -1; see below}
|
|
\end{tableiii}
|
|
|
|
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 described
|
|
under ``Year 2000 (Y2K) issues'' above. A \code{-1} argument as the
|
|
daylight savings flag, passed to \function{mktime()} will usually
|
|
result in the correct daylight savings state to be filled in.
|
|
|
|
When a tuple with an incorrect length is passed to a function
|
|
expecting a \class{struct_time}, or having elements of the wrong type, a
|
|
\exception{TypeError} is raised.
|
|
|
|
\versionchanged[The time value sequence was changed from a tuple to a
|
|
\class{struct_time}, with the addition of attribute names
|
|
for the fields]{2.2}
|
|
\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 UTC, if one
|
|
is defined. This is negative if the local DST timezone is east of UTC
|
|
(as in Western Europe, including the UK). Only use this if
|
|
\code{daylight} is nonzero.
|
|
\end{datadesc}
|
|
|
|
\begin{funcdesc}{asctime}{\optional{t}}
|
|
Convert a tuple or \class{struct_time} 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'}. If \var{t} is not provided, the
|
|
current time as returned by \function{localtime()} is used.
|
|
Locale information is not used by \function{asctime()}.
|
|
\note{Unlike the C function of the same name, there is no trailing
|
|
newline.}
|
|
\versionchanged[Allowed \var{t} to be omitted]{2.1}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{clock}{}
|
|
On \UNIX, return
|
|
the current processor time as a floating point number expressed in
|
|
seconds. The precision, and in fact the very definition of the meaning
|
|
of ``processor time''\index{CPU time}\index{processor 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.
|
|
|
|
On Windows, this function returns wall-clock seconds elapsed since the
|
|
first call to this function, as a floating point number,
|
|
based on the Win32 function \cfunction{QueryPerformanceCounter()}.
|
|
The resolution is typically better than one microsecond.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{ctime}{\optional{secs}}
|
|
Convert a time expressed in seconds since the epoch to a string
|
|
representing local time. If \var{secs} is not provided, the current time
|
|
as returned by \function{time()} is used. \code{ctime(\var{secs})}
|
|
is equivalent to \code{asctime(localtime(\var{secs}))}.
|
|
Locale information is not used by \function{ctime()}.
|
|
\versionchanged[Allowed \var{secs} to be omitted]{2.1}
|
|
\end{funcdesc}
|
|
|
|
\begin{datadesc}{daylight}
|
|
Nonzero if a DST timezone is defined.
|
|
\end{datadesc}
|
|
|
|
\begin{funcdesc}{gmtime}{\optional{secs}}
|
|
Convert a time expressed in seconds since the epoch to a \class{struct_time}
|
|
in UTC in which the dst flag is always zero. If \var{secs} is not
|
|
provided, the current time as returned by \function{time()} is used.
|
|
Fractions of a second are ignored. See above for a description of the
|
|
\class{struct_time} object.
|
|
\versionchanged[Allowed \var{secs} to be omitted]{2.1}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{localtime}{\optional{secs}}
|
|
Like \function{gmtime()} but converts to local time. The dst flag is
|
|
set to \code{1} when DST applies to the given time.
|
|
\versionchanged[Allowed \var{secs} to be omitted]{2.1}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{mktime}{t}
|
|
This is the inverse function of \function{localtime()}. Its argument
|
|
is the \class{struct_time} or full 9-tuple (since the dst flag is
|
|
needed; use \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, either \exception{OverflowError} or
|
|
\exception{ValueError} will be raised (which depends on whether the
|
|
invalid value is caught by Python or the underlying C libraries). The
|
|
earliest date for which it can generate a time is platform-dependent.
|
|
\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.
|
|
The actual suspension time may be less than that requested because any
|
|
caught signal will terminate the \function{sleep()} following
|
|
execution of that signal's catching routine. Also, the suspension
|
|
time may be longer than requested by an arbitrary amount because of
|
|
the scheduling of other activity in the system.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{strftime}{format\optional{, t}}
|
|
Convert a tuple or \class{struct_time} representing a time as returned
|
|
by \function{gmtime()} or \function{localtime()} to a string as
|
|
specified by the \var{format} argument. If \var{t} is not
|
|
provided, the current time as returned by \function{localtime()} is
|
|
used. \var{format} must be a string.
|
|
\versionchanged[Allowed \var{t} to be omitted]{2.1}
|
|
|
|
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{tableiii}{c|p{24em}|c}{code}{Directive}{Meaning}{Notes}
|
|
\lineiii{\%a}{Locale's abbreviated weekday name.}{}
|
|
\lineiii{\%A}{Locale's full weekday name.}{}
|
|
\lineiii{\%b}{Locale's abbreviated month name.}{}
|
|
\lineiii{\%B}{Locale's full month name.}{}
|
|
\lineiii{\%c}{Locale's appropriate date and time representation.}{}
|
|
\lineiii{\%d}{Day of the month as a decimal number [01,31].}{}
|
|
\lineiii{\%H}{Hour (24-hour clock) as a decimal number [00,23].}{}
|
|
\lineiii{\%I}{Hour (12-hour clock) as a decimal number [01,12].}{}
|
|
\lineiii{\%j}{Day of the year as a decimal number [001,366].}{}
|
|
\lineiii{\%m}{Month as a decimal number [01,12].}{}
|
|
\lineiii{\%M}{Minute as a decimal number [00,59].}{}
|
|
\lineiii{\%p}{Locale's equivalent of either AM or PM.}{}
|
|
\lineiii{\%S}{Second as a decimal number [00,61].}{(1)}
|
|
\lineiii{\%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.}{}
|
|
\lineiii{\%w}{Weekday as a decimal number [0(Sunday),6].}{}
|
|
\lineiii{\%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 Monday are considered to be in week 0.}{}
|
|
\lineiii{\%x}{Locale's appropriate date representation.}{}
|
|
\lineiii{\%X}{Locale's appropriate time representation.}{}
|
|
\lineiii{\%y}{Year without century as a decimal number [00,99].}{}
|
|
\lineiii{\%Y}{Year with century as a decimal number.}{}
|
|
\lineiii{\%Z}{Time zone name (no characters if no time zone exists).}{}
|
|
\lineiii{\%\%}{A literal \character{\%} character.}{}
|
|
\end{tableiii}
|
|
|
|
\noindent
|
|
Notes:
|
|
|
|
\begin{description}
|
|
\item[(1)]
|
|
The range really is \code{0} to \code{61}; this accounts for leap
|
|
seconds and the (very rare) double leap seconds.
|
|
\end{description}
|
|
|
|
Here is an example, a format for dates compatible with that specified
|
|
in the \rfc{2822} Internet email standard.
|
|
\footnote{The use of \code{\%Z} is now
|
|
deprecated, but the \code{\%z} escape that expands to the preferred
|
|
hour/minute offset is not supported by all ANSI C libraries. Also,
|
|
a strict reading of the original 1982 \rfc{822} standard calls for
|
|
a two-digit year (\%y rather than \%Y), but practice moved to
|
|
4-digit years long before the year 2000. The 4-digit year has
|
|
been mandated by \rfc{2822}, which obsoletes \rfc{822}.}
|
|
|
|
\begin{verbatim}
|
|
>>> from time import gmtime, strftime
|
|
>>> strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime())
|
|
'Thu, 28 Jun 2001 14:17:15 +0000'
|
|
\end{verbatim}
|
|
|
|
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 \class{struct_time} 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()}. If \var{string} cannot be parsed
|
|
according to \var{format}, \exception{ValueError} is raised. If the
|
|
string to be parsed has excess data after parsing,
|
|
\exception{ValueError} is raised. The default values used to fill in
|
|
any missing data is \code{(1900, 1, 1, 0, 0, 0, 0, 1, -1)} .
|
|
|
|
Support for the \code{\%Z} directive is based on the values contained in
|
|
\code{tzname} and whether \code{daylight} is true. Because of this,
|
|
it is platform-specific except for recognizing UTC and GMT which are
|
|
always known (and are considered to be non-daylight savings
|
|
timezones).
|
|
\end{funcdesc}
|
|
|
|
\begin{datadesc}{struct_time}
|
|
The type of the time value sequence returned by \function{gmtime()},
|
|
\function{localtime()}, and \function{strptime()}.
|
|
\versionadded{2.2}
|
|
\end{datadesc}
|
|
|
|
\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. While this function normally returns
|
|
non-decreasing values, it can return a lower value than a previous
|
|
call if the system clock has been set back between the two calls.
|
|
\end{funcdesc}
|
|
|
|
\begin{datadesc}{timezone}
|
|
The offset of the local (non-DST) timezone, in seconds west of UTC
|
|
(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}
|
|
|
|
\begin{funcdesc}{tzset}{}
|
|
Resets the time conversion rules used by the library routines.
|
|
The environment variable \envvar{TZ} specifies how this is done.
|
|
\versionadded{2.3}
|
|
|
|
Availability: \UNIX.
|
|
|
|
\begin{notice}
|
|
Although in many cases, changing the \envvar{TZ} environment variable
|
|
may affect the output of functions like \function{localtime} without calling
|
|
\function{tzset}, this behavior should not be relied on.
|
|
|
|
The \envvar{TZ} environment variable should contain no whitespace.
|
|
\end{notice}
|
|
|
|
The standard format of the \envvar{TZ} environment variable is:
|
|
(whitespace added for clarity)
|
|
\begin{itemize}
|
|
\item[std offset [dst [offset] [,start[/time], end[/time]]]]
|
|
\end{itemize}
|
|
|
|
Where:
|
|
|
|
\begin{itemize}
|
|
\item[std and dst]
|
|
Three or more alphanumerics giving the timezone abbreviations.
|
|
These will be propogated into time.tzname
|
|
|
|
\item[offset]
|
|
The offset has the form: \plusminus{} hh[:mm[:ss]].
|
|
This indicates the value added the local time to arrive at UTC.
|
|
If preceded by a '-', the timezone is east of the Prime
|
|
Meridian; otherwise, it is west. If no offset follows
|
|
dst, summmer time is assumed to be one hour ahead of standard time.
|
|
|
|
\item[start[/time],end[/time]]
|
|
Indicates when to change to and back from DST. The format of the
|
|
start and end dates are one of the following:
|
|
|
|
\begin{itemize}
|
|
\item[J\var{n}]
|
|
The Julian day \var{n} (1 <= \var{n} <= 365). Leap days are not
|
|
counted, so in all years February 28 is day 59 and
|
|
March 1 is day 60.
|
|
|
|
\item[\var{n}]
|
|
The zero-based Julian day (0 <= \var{n} <= 365). Leap days are
|
|
counted, and it is possible to refer to February 29.
|
|
|
|
\item[M\var{m}.\var{n}.\var{d}]
|
|
The \var{d}'th day (0 <= \var{d} <= 6) or week \var{n}
|
|
of month \var{m} of the year (1 <= \var{n} <= 5,
|
|
1 <= \var{m} <= 12, where week 5 means "the last \var{d} day
|
|
in month \var{m}" which may occur in either the fourth or
|
|
the fifth week). Week 1 is the first week in which the
|
|
\var{d}'th day occurs. Day zero is Sunday.
|
|
\end{itemize}
|
|
|
|
time has the same format as offset except that no leading sign ('-' or
|
|
'+') is allowed. The default, if time is not given, is 02:00:00.
|
|
\end{itemize}
|
|
|
|
|
|
\begin{verbatim}
|
|
>>> os.environ['TZ'] = 'EST+05EDT,M4.1.0,M10.5.0'
|
|
>>> time.tzset()
|
|
>>> time.strftime('%X %x %Z')
|
|
'02:07:36 05/08/03 EDT'
|
|
>>> os.environ['TZ'] = 'AEST-10AEDT-11,M10.5.0,M3.5.0'
|
|
>>> time.tzset()
|
|
>>> time.strftime('%X %x %Z')
|
|
'16:08:12 05/08/03 AEST'
|
|
\end{verbatim}
|
|
|
|
On many Unix systems (including *BSD, Linux, Solaris, and Darwin), it
|
|
is more convenient to use the system's zoneinfo (\manpage{tzfile}{5})
|
|
database to specify the timezone rules. To do this, set the
|
|
\envvar{TZ} environment variable to the path of the required timezone
|
|
datafile, relative to the root of the systems 'zoneinfo' timezone database,
|
|
usually located at \file{/usr/share/zoneinfo}. For example,
|
|
\code{'US/Eastern'}, \code{'Australia/Melbourne'}, \code{'Egypt'} or
|
|
\code{'Europe/Amsterdam'}.
|
|
|
|
\begin{verbatim}
|
|
>>> os.environ['TZ'] = 'US/Eastern'
|
|
>>> time.tzset()
|
|
>>> time.tzname
|
|
('EST', 'EDT')
|
|
>>> os.environ['TZ'] = 'Egypt'
|
|
>>> time.tzset()
|
|
>>> time.tzname
|
|
('EET', 'EEST')
|
|
\end{verbatim}
|
|
|
|
\end{funcdesc}
|
|
|
|
|
|
\begin{seealso}
|
|
\seemodule{datetime}{More object-oriented interface to dates and times.}
|
|
\seemodule{locale}{Internationalization services. The locale
|
|
settings can affect the return values for some of
|
|
the functions in the \module{time} module.}
|
|
\seemodule{calendar}{General calendar-related functions.
|
|
\function{timegm()} is the inverse of
|
|
\function{gmtime()} from this module.}
|
|
\end{seealso}
|