Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 1 | \section{Built-in Module \sectcode{time}} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame^] | 2 | \label{module-time} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 3 | |
| 4 | \bimodindex{time} |
| 5 | This module provides various time-related functions. |
Guido van Rossum | bd851cd | 1994-08-23 13:26:22 +0000 | [diff] [blame] | 6 | It is always available. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 7 | |
| 8 | An explanation of some terminology and conventions is in order. |
| 9 | |
| 10 | \begin{itemize} |
| 11 | |
| 12 | \item |
Guido van Rossum | 16d6e71 | 1994-08-08 12:30:22 +0000 | [diff] [blame] | 13 | The ``epoch'' is the point where the time starts. On January 1st of that |
Fred Drake | 094579e | 1996-12-13 22:09:52 +0000 | [diff] [blame] | 14 | year, at 0 hours, the ``time since the epoch'' is zero. For \UNIX{}, the |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 15 | epoch is 1970. To find out what the epoch is, look at \code{gmtime(0)}. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 16 | |
| 17 | \item |
| 18 | UTC is Coordinated Universal Time (formerly known as Greenwich Mean |
| 19 | Time). The acronym UTC is not a mistake but a compromise between |
| 20 | English and French. |
| 21 | |
| 22 | \item |
| 23 | DST is Daylight Saving Time, an adjustment of the timezone by |
| 24 | (usually) one hour during part of the year. DST rules are magic |
| 25 | (determined by local law) and can change from year to year. The C |
| 26 | library has a table containing the local rules (often it is read from |
| 27 | a system file for flexibility) and is the only source of True Wisdom |
| 28 | in this respect. |
| 29 | |
| 30 | \item |
| 31 | The precision of the various real-time functions may be less than |
| 32 | suggested by the units in which their value or argument is expressed. |
Fred Drake | 094579e | 1996-12-13 22:09:52 +0000 | [diff] [blame] | 33 | E.g.\ on most \UNIX{} systems, the clock ``ticks'' only 50 or 100 times a |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 34 | second, and on the Mac, times are only accurate to whole seconds. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 35 | |
Guido van Rossum | 8cf2db4 | 1996-07-30 18:32:04 +0000 | [diff] [blame] | 36 | \item |
Guido van Rossum | 21be147 | 1996-12-12 17:59:37 +0000 | [diff] [blame] | 37 | On the other hand, the precision of \code{time()} and \code{sleep()} |
Fred Drake | 094579e | 1996-12-13 22:09:52 +0000 | [diff] [blame] | 38 | is better than their \UNIX{} equivalents: times are expressed as floating |
Guido van Rossum | 21be147 | 1996-12-12 17:59:37 +0000 | [diff] [blame] | 39 | point numbers, \code{time()} returns the most accurate time available |
Fred Drake | 094579e | 1996-12-13 22:09:52 +0000 | [diff] [blame] | 40 | (using \UNIX{} \code{gettimeofday()} where available), and \code{sleep()} |
| 41 | will accept a time with a nonzero fraction (\UNIX{} \code{select()} is |
Guido van Rossum | 21be147 | 1996-12-12 17:59:37 +0000 | [diff] [blame] | 42 | used to implement this, where available). |
| 43 | |
| 44 | \item |
Guido van Rossum | 8cf2db4 | 1996-07-30 18:32:04 +0000 | [diff] [blame] | 45 | The time tuple as returned by \code{gmtime()} and \code{localtime()}, |
| 46 | or as accpted by \code{mktime()} is a tuple of 9 |
| 47 | integers: year (e.g.\ 1993), month (1--12), day (1--31), hour |
| 48 | (0--23), minute (0--59), second (0--59), weekday (0--6, monday is 0), |
| 49 | Julian day (1--366) and daylight savings flag (-1, 0 or 1). |
| 50 | Note that unlike the C structure, the month value is a range of 1-12, not |
| 51 | 0-11. A year value of $<$ 100 will typically be silently converted to |
| 52 | 1900 $+$ year value. A -1 argument as daylight savings flag, passed to |
| 53 | \code{mktime()} will usually result in the correct daylight savings |
| 54 | state to be filled in. |
| 55 | |
| 56 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 57 | \end{itemize} |
| 58 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 59 | The module defines the following functions and data items: |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 60 | |
| 61 | \renewcommand{\indexsubitem}{(in module time)} |
| 62 | |
| 63 | \begin{datadesc}{altzone} |
| 64 | The offset of the local DST timezone, in seconds west of the 0th |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 65 | meridian, if one is defined. Negative if the local DST timezone is |
| 66 | east of the 0th meridian (as in Western Europe, including the UK). |
| 67 | Only use this if \code{daylight} is nonzero. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 68 | \end{datadesc} |
| 69 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 70 | \begin{funcdesc}{asctime}{tuple} |
| 71 | Convert a tuple representing a time as returned by \code{gmtime()} or |
| 72 | \code{localtime()} to a 24-character string of the following form: |
| 73 | \code{'Sun Jun 20 23:21:05 1993'}. Note: unlike the C function of |
| 74 | the same name, there is no trailing newline. |
| 75 | \end{funcdesc} |
| 76 | |
Guido van Rossum | bd851cd | 1994-08-23 13:26:22 +0000 | [diff] [blame] | 77 | \begin{funcdesc}{clock}{} |
| 78 | Return the current CPU time as a floating point number expressed in |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 79 | seconds. The precision, and in fact the very definiton of the meaning |
Guido van Rossum | 21be147 | 1996-12-12 17:59:37 +0000 | [diff] [blame] | 80 | of ``CPU time'', depends on that of the C function of the same name, |
| 81 | but in any case, this is the function to use for benchmarking Python |
| 82 | or timing algorithms. |
Guido van Rossum | bd851cd | 1994-08-23 13:26:22 +0000 | [diff] [blame] | 83 | \end{funcdesc} |
| 84 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 85 | \begin{funcdesc}{ctime}{secs} |
| 86 | Convert a time expressed in seconds since the epoch to a string |
| 87 | representing local time. \code{ctime(t)} is equivalent to |
| 88 | \code{asctime(localtime(t))}. |
| 89 | \end{funcdesc} |
| 90 | |
| 91 | \begin{datadesc}{daylight} |
| 92 | Nonzero if a DST timezone is defined. |
| 93 | \end{datadesc} |
| 94 | |
| 95 | \begin{funcdesc}{gmtime}{secs} |
Guido van Rossum | 8cf2db4 | 1996-07-30 18:32:04 +0000 | [diff] [blame] | 96 | Convert a time expressed in seconds since the epoch to a time tuple |
| 97 | in UTC in which the dst flag is always zero. Fractions of a second are |
| 98 | ignored. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 99 | \end{funcdesc} |
| 100 | |
| 101 | \begin{funcdesc}{localtime}{secs} |
| 102 | Like \code{gmtime} but converts to local time. The dst flag is set |
| 103 | to 1 when DST applies to the given time. |
| 104 | \end{funcdesc} |
| 105 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 106 | \begin{funcdesc}{mktime}{tuple} |
| 107 | This is the inverse function of \code{localtime}. Its argument is the |
Guido van Rossum | 8cf2db4 | 1996-07-30 18:32:04 +0000 | [diff] [blame] | 108 | full 9-tuple (since the dst flag is needed --- pass -1 as the dst flag if |
| 109 | it is unknown) which expresses the time |
Fred Drake | 094579e | 1996-12-13 22:09:52 +0000 | [diff] [blame] | 110 | in \emph{local} time, not UTC. It returns a floating |
Guido van Rossum | 036eae6 | 1996-06-26 19:25:12 +0000 | [diff] [blame] | 111 | point number, for compatibility with \code{time.time()}. If the input |
| 112 | value can't be represented as a valid time, OverflowError is raised. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 113 | \end{funcdesc} |
| 114 | |
| 115 | \begin{funcdesc}{sleep}{secs} |
| 116 | Suspend execution for the given number of seconds. The argument may |
| 117 | be a floating point number to indicate a more precise sleep time. |
| 118 | \end{funcdesc} |
| 119 | |
Guido van Rossum | 26ee809 | 1995-09-13 17:37:49 +0000 | [diff] [blame] | 120 | \begin{funcdesc}{strftime}{format, tuple} |
| 121 | Convert a tuple representing a time as returned by \code{gmtime()} or |
| 122 | \code{localtime()} to a string as specified by the format argument. |
Guido van Rossum | 8cf2db4 | 1996-07-30 18:32:04 +0000 | [diff] [blame] | 123 | |
Fred Drake | 094579e | 1996-12-13 22:09:52 +0000 | [diff] [blame] | 124 | The following directives, shown without the optional field width and |
| 125 | precision specification, are replaced by the indicated characters: |
Guido van Rossum | 8cf2db4 | 1996-07-30 18:32:04 +0000 | [diff] [blame] | 126 | |
Fred Drake | 094579e | 1996-12-13 22:09:52 +0000 | [diff] [blame] | 127 | \begin{tableii}{|c|p{24em}|}{code}{Directive}{Meaning} |
| 128 | \lineii{\%a}{Locale's abbreviated weekday name.} |
| 129 | \lineii{\%A}{Locale's full weekday name.} |
| 130 | \lineii{\%b}{Locale's abbreviated month name.} |
| 131 | \lineii{\%B}{Locale's full month name.} |
| 132 | \lineii{\%c}{Locale's appropriate date and time representation.} |
| 133 | \lineii{\%d}{Day of the month as a decimal number [01,31].} |
| 134 | \lineii{\%H}{Hour (24-hour clock) as a decimal number [00,23].} |
| 135 | \lineii{\%I}{Hour (12-hour clock) as a decimal number [01,12].} |
| 136 | \lineii{\%j}{Day of the year as a decimal number [001,366].} |
| 137 | \lineii{\%m}{Month as a decimal number [01,12].} |
| 138 | \lineii{\%M}{Minute as a decimal number [00,59].} |
| 139 | \lineii{\%p}{Locale's equivalent of either AM or PM.} |
| 140 | \lineii{\%S}{Second as a decimal number [00,61].} |
| 141 | \lineii{\%U}{Week number of the year (Sunday as the first day of the |
| 142 | week) as a decimal number [00,53]. All days in a new year |
| 143 | preceding the first Sunday are considered to be in week 0.} |
| 144 | \lineii{\%w}{Weekday as a decimal number [0(Sunday),6].} |
| 145 | \lineii{\%W}{Week number of the year (Monday as the first day of the |
| 146 | week) as a decimal number [00,53]. All days in a new year |
| 147 | preceding the first Sunday are considered to be in week 0.} |
| 148 | \lineii{\%x}{Locale's appropriate date representation.} |
| 149 | \lineii{\%X}{Locale's appropriate time representation.} |
| 150 | \lineii{\%y}{Year without century as a decimal number [00,99].} |
| 151 | \lineii{\%Y}{Year with century as a decimal number.} |
| 152 | \lineii{\%Z}{Time zone name (or by no characters if no time zone exists).} |
| 153 | \lineii{\%\%}{\%} |
| 154 | \end{tableii} |
Guido van Rossum | 8cf2db4 | 1996-07-30 18:32:04 +0000 | [diff] [blame] | 155 | |
Fred Drake | 094579e | 1996-12-13 22:09:52 +0000 | [diff] [blame] | 156 | Additional directives may be supported on certain platforms, but |
| 157 | only the ones listed here have a meaning standardized by ANSI C. |
Guido van Rossum | 8cf2db4 | 1996-07-30 18:32:04 +0000 | [diff] [blame] | 158 | |
Fred Drake | 094579e | 1996-12-13 22:09:52 +0000 | [diff] [blame] | 159 | On some platforms, an optional field width and precision |
| 160 | specification can immediately follow the initial \% of a |
| 161 | directive in the following order; this is also not portable. |
| 162 | The field width is normally 2 except for \%j where it is 3. |
Guido van Rossum | 8cf2db4 | 1996-07-30 18:32:04 +0000 | [diff] [blame] | 163 | |
Guido van Rossum | 26ee809 | 1995-09-13 17:37:49 +0000 | [diff] [blame] | 164 | \end{funcdesc} |
| 165 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 166 | \begin{funcdesc}{time}{} |
| 167 | Return the time as a floating point number expressed in seconds since |
| 168 | the epoch, in UTC. Note that even though the time is always returned |
| 169 | as a floating point number, not all systems provide time with a better |
Guido van Rossum | bd851cd | 1994-08-23 13:26:22 +0000 | [diff] [blame] | 170 | precision than 1 second. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 171 | \end{funcdesc} |
| 172 | |
| 173 | \begin{datadesc}{timezone} |
| 174 | The offset of the local (non-DST) timezone, in seconds west of the 0th |
| 175 | meridian (i.e. negative in most of Western Europe, positive in the US, |
| 176 | zero in the UK). |
| 177 | \end{datadesc} |
| 178 | |
| 179 | \begin{datadesc}{tzname} |
| 180 | A tuple of two strings: the first is the name of the local non-DST |
| 181 | timezone, the second is the name of the local DST timezone. If no DST |
| 182 | timezone is defined, the second string should not be used. |
| 183 | \end{datadesc} |
Guido van Rossum | 8cf2db4 | 1996-07-30 18:32:04 +0000 | [diff] [blame] | 184 | |