diff options
Diffstat (limited to 'Doc/lib/libtime.tex')
| -rw-r--r-- | Doc/lib/libtime.tex | 475 |
1 files changed, 0 insertions, 475 deletions
diff --git a/Doc/lib/libtime.tex b/Doc/lib/libtime.tex deleted file mode 100644 index 8a45bfcc..0000000 --- a/Doc/lib/libtime.tex +++ /dev/null @@ -1,475 +0,0 @@ -\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 or -\constant{None}, 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} -\versionchanged[If \var{secs} is \constant{None}, the current time is - used]{2.4} -\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 or \constant{None}, 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. See -\function{calendar.timegm()} for the inverse of this function. -\versionchanged[Allowed \var{secs} to be omitted]{2.1} -\versionchanged[If \var{secs} is \constant{None}, the current time is - used]{2.4} -\end{funcdesc} - -\begin{funcdesc}{localtime}{\optional{secs}} -Like \function{gmtime()} but converts to local time. If \var{secs} is -not provided or \constant{None}, the current time as returned by -\function{time()} is used. The dst flag is set to \code{1} when DST -applies to the given time. -\versionchanged[Allowed \var{secs} to be omitted]{2.1} -\versionchanged[If \var{secs} is \constant{None}, the current time is - used]{2.4} -\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. \exception{ValueError} is raised -if any field in \var{t} is outside of the allowed range. -\versionchanged[Allowed \var{t} to be omitted]{2.1} -\versionchanged[\exception{ValueError} raised if a field in \var{t} is -out of range]{2.4} -\versionchanged[0 is now a legal argument for any position in the time tuple; -if it is normally illegal the value is forced to a correct one.]{2.5} - - -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.}{(1)} - \lineiii{\%S}{Second as a decimal number [00,61].}{(2)} - \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.}{(3)} - \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.}{(3)} - \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)] - When used with the \function{strptime()} function, the \code{\%p} - directive only affects the output hour field if the \code{\%I} directive - is used to parse the hour. - \item[(2)] - The range really is \code{0} to \code{61}; this accounts for leap - seconds and the (very rare) double leap seconds. - \item[(3)] - When used with the \function{strptime()} function, \code{\%U} and \code{\%W} - are only used in calculations when the day of the week and the year are - specified. -\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}, or if it -has excess data after parsing, \exception{ValueError} is raised. The -default values used to fill in any missing data when more accurate -values cannot be inferred are \code{(1900, 1, 1, 0, 0, 0, 0, 1, -1)}. - -For example: - -\begin{verbatim} ->>> import time ->>> time.strptime("30 Nov 00", "%d %b %y") -(2000, 11, 30, 0, 0, 0, 3, 335, -1) -\end{verbatim} - -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). - -Only the directives specified in the documentation are supported. Because -\code{strftime()} is implemented per platform it can sometimes offer more -directives than those listed. But \code{strptime()} is independent of any -platform and thus does not necessarily support all directives available that -are not documented as supported. -\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 propagated 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, summer 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} |