| \section{Built-in Module \sectcode{time}} |
| |
| \bimodindex{time} |
| 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 ``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 |
| UTC is Coordinated Universal Time (formerly known as Greenwich Mean |
| Time). The acronym UTC is not a mistake but a compromise between |
| English and French. |
| |
| \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. |
| |
| \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 |
| The time tuple as returned by \code{gmtime()} and \code{localtime()}, |
| or as accpted by \code{mktime()} 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 of $<$ 100 will typically be silently converted to |
| 1900 $+$ year value. A -1 argument as daylight savings flag, passed to |
| \code{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: |
| |
| \renewcommand{\indexsubitem}{(in module time)} |
| |
| \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 \code{gmtime()} or |
| \code{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'', depends on that of the C function of the same name. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{ctime}{secs} |
| Convert a time expressed in seconds since the epoch to a string |
| representing local time. \code{ctime(t)} is equivalent to |
| \code{asctime(localtime(t))}. |
| \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. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{localtime}{secs} |
| Like \code{gmtime} but converts to local time. The dst flag is set |
| to 1 when DST applies to the given time. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{mktime}{tuple} |
| This is the inverse function of \code{localtime}. Its argument is the |
| full 9-tuple (since the dst flag is needed --- pass -1 as the dst flag if |
| it is unknown) which expresses the time |
| in \em{local} time, not UTC. It returns a floating |
| point number, for compatibility with \code{time.time()}. If the input |
| value can't be represented as a valid time, 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 \code{gmtime()} or |
| \code{localtime()} to a string as specified by the format argument. |
| |
| The following directives, shown without the optional field width and |
| precision specification, are replaced by the indicated characters: |
| |
| \begin{tabular}{lp{25em}} |
| \%a & Locale's abbreviated weekday name. \\ |
| \%A & Locale's full weekday name. \\ |
| \%b & Locale's abbreviated month name. \\ |
| \%B & Locale's full month name. \\ |
| \%c & Locale's appropriate date and time representation. \\ |
| \%d & Day of the month as a decimal number [01,31]. \\ |
| \%E & Locale's combined Emperor/Era name and year. \\ |
| \%H & Hour (24-hour clock) as a decimal number [00,23]. \\ |
| \%I & Hour (12-hour clock) as a decimal number [01,12]. \\ |
| \%j & Day of the year as a decimal number [001,366]. \\ |
| \%m & Month as a decimal number [01,12]. \\ |
| \%M & Minute as a decimal number [00,59]. \\ |
| \%n & New-line character. \\ |
| \%N & Locale's Emperor/Era name. \\ |
| \%o & Locale's Emperor/Era year. \\ |
| \%p & Locale's equivalent of either AM or PM. \\ |
| \%S & Second as a decimal number [00,61]. \\ |
| \%t & Tab character. \\ |
| \%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. \\ |
| \%w & Weekday as a decimal number [0(Sunday),6]. \\ |
| \%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. \\ |
| \%x & Locale's appropriate date representation. \\ |
| \%X & Locale's appropriate time representation. \\ |
| \%y & Year without century as a decimal number [00,99]. \\ |
| \%Y & Year with century as a decimal number. \\ |
| \%Z & Time zone name (or by no characters if no time zone |
| exists). \\ |
| \%\% & \% \\ |
| \end{tabular} |
| |
| An optional field width and precision specification can immediately |
| follow the initial \% of a directive in the following order: \\ |
| |
| \begin{tabular}{lp{25em}} |
| [-|0]w & the decimal digit string w specifies a minimum field |
| width in which the result of the conversion is right- |
| or left-justified. It is right-justified (with space |
| padding) by default. If the optional flag `-' is |
| specified, it is left-justified with space padding on |
| the right. If the optional flag `0' is specified, it |
| is right-justified and padded with zeros on the left. \\ |
| .p & the decimal digit string p specifies the minimum number |
| of digits to appear for the d, H, I, j, m, M, o, S, U, |
| w, W, y and Y directives, and the maximum number of |
| characters to be used from the a, A, b, B, c, D, E, F, |
| h, n, N, p, r, t, T, x, X, z, Z, and % directives. In |
| the first case, if a directive supplies fewer digits |
| than specified by the precision, it will be expanded |
| with leading zeros. In the second case, if a directive |
| supplies more characters than specified by the |
| precision, excess characters will truncated on the |
| right. |
| \end{tabular} |
| |
| If no field width or precision is specified for a d, H, I, m, M, S, U, |
| W, y, or j directive, a default of .2 is used for all but j for which |
| .3 is used. |
| |
| \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} |
| |