Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 1 | \section{Built-in Module \sectcode{time}} |
| 2 | |
| 3 | \bimodindex{time} |
| 4 | This module provides various time-related functions. |
Guido van Rossum | bd851cd | 1994-08-23 13:26:22 +0000 | [diff] [blame] | 5 | It is always available. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 6 | |
| 7 | An explanation of some terminology and conventions is in order. |
| 8 | |
| 9 | \begin{itemize} |
| 10 | |
| 11 | \item |
Guido van Rossum | 16d6e71 | 1994-08-08 12:30:22 +0000 | [diff] [blame] | 12 | The ``epoch'' is the point where the time starts. On January 1st of that |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 13 | year, at 0 hours, the ``time since the epoch'' is zero. For UNIX, the |
| 14 | epoch is 1970. To find out what the epoch is, look at the first |
| 15 | element of \code{gmtime(0)}. |
| 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. |
| 33 | E.g. on most UNIX systems, the clock ``ticks'' only every 1/50th or |
| 34 | 1/100th of a second, and on the Mac, it ticks 60 times a second. |
| 35 | |
| 36 | \end{itemize} |
| 37 | |
| 38 | Functions and data items are: |
| 39 | |
| 40 | \renewcommand{\indexsubitem}{(in module time)} |
| 41 | |
| 42 | \begin{datadesc}{altzone} |
| 43 | The offset of the local DST timezone, in seconds west of the 0th |
| 44 | meridian, if one is defined. Only use this if \code{daylight} is |
| 45 | nonzero. |
| 46 | \end{datadesc} |
| 47 | |
| 48 | |
| 49 | \begin{funcdesc}{asctime}{tuple} |
| 50 | Convert a tuple representing a time as returned by \code{gmtime()} or |
| 51 | \code{localtime()} to a 24-character string of the following form: |
| 52 | \code{'Sun Jun 20 23:21:05 1993'}. Note: unlike the C function of |
| 53 | the same name, there is no trailing newline. |
| 54 | \end{funcdesc} |
| 55 | |
| 56 | |
Guido van Rossum | bd851cd | 1994-08-23 13:26:22 +0000 | [diff] [blame] | 57 | \begin{funcdesc}{clock}{} |
| 58 | Return the current CPU time as a floating point number expressed in |
| 59 | seconds. The precision depends on that of the C function by the same |
| 60 | name. |
| 61 | \end{funcdesc} |
| 62 | |
| 63 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 64 | \begin{funcdesc}{ctime}{secs} |
| 65 | Convert a time expressed in seconds since the epoch to a string |
| 66 | representing local time. \code{ctime(t)} is equivalent to |
| 67 | \code{asctime(localtime(t))}. |
| 68 | \end{funcdesc} |
| 69 | |
| 70 | \begin{datadesc}{daylight} |
| 71 | Nonzero if a DST timezone is defined. |
| 72 | \end{datadesc} |
| 73 | |
| 74 | \begin{funcdesc}{gmtime}{secs} |
| 75 | Convert a time expressed in seconds since the epoch to a tuple of 9 |
| 76 | integers, in UTC: year (e.g. 1993), month (1-12), day (1-31), hour |
| 77 | (0-23), minute (0-59), second (0-59), weekday (0-6, monday is 0), |
| 78 | julian day (1-366), dst flag (always zero). Fractions of a second are |
| 79 | ignored. Note subtle differences with the C function of this name. |
| 80 | \end{funcdesc} |
| 81 | |
| 82 | \begin{funcdesc}{localtime}{secs} |
| 83 | Like \code{gmtime} but converts to local time. The dst flag is set |
| 84 | to 1 when DST applies to the given time. |
| 85 | \end{funcdesc} |
| 86 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 87 | \begin{funcdesc}{mktime}{tuple} |
| 88 | This is the inverse function of \code{localtime}. Its argument is the |
| 89 | full 9-tuple (since the dst flag is needed). It returns an integer. |
| 90 | \end{funcdesc} |
| 91 | |
| 92 | \begin{funcdesc}{sleep}{secs} |
| 93 | Suspend execution for the given number of seconds. The argument may |
| 94 | be a floating point number to indicate a more precise sleep time. |
| 95 | \end{funcdesc} |
| 96 | |
| 97 | \begin{funcdesc}{time}{} |
| 98 | Return the time as a floating point number expressed in seconds since |
| 99 | the epoch, in UTC. Note that even though the time is always returned |
| 100 | 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] | 101 | precision than 1 second. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 102 | \end{funcdesc} |
| 103 | |
| 104 | \begin{datadesc}{timezone} |
| 105 | The offset of the local (non-DST) timezone, in seconds west of the 0th |
| 106 | meridian (i.e. negative in most of Western Europe, positive in the US, |
| 107 | zero in the UK). |
| 108 | \end{datadesc} |
| 109 | |
| 110 | \begin{datadesc}{tzname} |
| 111 | A tuple of two strings: the first is the name of the local non-DST |
| 112 | timezone, the second is the name of the local DST timezone. If no DST |
| 113 | timezone is defined, the second string should not be used. |
| 114 | \end{datadesc} |