Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libtime.tex @ 27998:e27f58a50737 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
SF bug #690377: Dud footnote reference in distutils docs
author Raymond Hettinger <python@rcn.com>
date Fri, 21 Feb 2003 02:47:09 +0000
parents 20330e13211e
children cfcc45f18515
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8918
acfffe14628e New section header style.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
1 \section{\module{time} ---
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
2 Time access and conversions}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
3
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8478
diff changeset
4 \declaremodule{builtin}{time}
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8478
diff changeset
5 \modulesynopsis{Time access and conversions.}
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8478
diff changeset
6
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
7
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
8 This module provides various time-related functions.
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
9 It is always available, but not all functions are available
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
10 on all platforms.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
11
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
12 An explanation of some terminology and conventions is in order.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
13
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
14 \begin{itemize}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
15
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
16 \item
8000
bdf57c84df6a Shift index entries around a little so the HTML doesn't have weird spacing.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
17 The \dfn{epoch}\index{epoch} is the point where the time starts. On
bdf57c84df6a Shift index entries around a little so the HTML doesn't have weird spacing.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
18 January 1st of that year, at 0 hours, the ``time since the epoch'' is
21062
bc02c3b09626 Clean up some markup cruft. A number of the macros that take no
Fred Drake <fdrake@acm.org>
parents: 20744
diff changeset
19 zero. For \UNIX, the epoch is 1970. To find out what the epoch is,
10881
838cb34abb79 Move some \index entries around so we can avoid using empty comments;
Fred Drake <fdrake@acm.org>
parents: 10243
diff changeset
20 look at \code{gmtime(0)}.
8478
4ba587aa8a98 Added notes about epochs, the year 2038, and a small Y2K disclaimer
Guido van Rossum <guido@python.org>
parents: 8471
diff changeset
21
4ba587aa8a98 Added notes about epochs, the year 2038, and a small Y2K disclaimer
Guido van Rossum <guido@python.org>
parents: 8471
diff changeset
22 \item
9611
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
23 The functions in this module do not handle dates and times before the
8478
4ba587aa8a98 Added notes about epochs, the year 2038, and a small Y2K disclaimer
Guido van Rossum <guido@python.org>
parents: 8471
diff changeset
24 epoch or far in the future. The cut-off point in the future is
21062
bc02c3b09626 Clean up some markup cruft. A number of the macros that take no
Fred Drake <fdrake@acm.org>
parents: 20744
diff changeset
25 determined by the C library; for \UNIX, it is typically in
10881
838cb34abb79 Move some \index entries around so we can avoid using empty comments;
Fred Drake <fdrake@acm.org>
parents: 10243
diff changeset
26 2038\index{Year 2038}.
8478
4ba587aa8a98 Added notes about epochs, the year 2038, and a small Y2K disclaimer
Guido van Rossum <guido@python.org>
parents: 8471
diff changeset
27
4ba587aa8a98 Added notes about epochs, the year 2038, and a small Y2K disclaimer
Guido van Rossum <guido@python.org>
parents: 8471
diff changeset
28 \item
10881
838cb34abb79 Move some \index entries around so we can avoid using empty comments;
Fred Drake <fdrake@acm.org>
parents: 10243
diff changeset
29 \strong{Year 2000 (Y2K) issues}:\index{Year 2000}\index{Y2K} Python
838cb34abb79 Move some \index entries around so we can avoid using empty comments;
Fred Drake <fdrake@acm.org>
parents: 10243
diff changeset
30 depends on the platform's C library, which generally doesn't have year
838cb34abb79 Move some \index entries around so we can avoid using empty comments;
Fred Drake <fdrake@acm.org>
parents: 10243
diff changeset
31 2000 issues, since all dates and times are represented internally as
27670
20330e13211e Update to better reflect the usage of struct_time instances throughout;
Fred Drake <fdrake@acm.org>
parents: 26925
diff changeset
32 seconds since the epoch. Functions accepting a \class{struct_time}
20330e13211e Update to better reflect the usage of struct_time instances throughout;
Fred Drake <fdrake@acm.org>
parents: 26925
diff changeset
33 (see below) generally require a 4-digit year. For backward
20330e13211e Update to better reflect the usage of struct_time instances throughout;
Fred Drake <fdrake@acm.org>
parents: 26925
diff changeset
34 compatibility, 2-digit years are supported if the module variable
20330e13211e Update to better reflect the usage of struct_time instances throughout;
Fred Drake <fdrake@acm.org>
parents: 26925
diff changeset
35 \code{accept2dyear} is a non-zero integer; this variable is
20330e13211e Update to better reflect the usage of struct_time instances throughout;
Fred Drake <fdrake@acm.org>
parents: 26925
diff changeset
36 initialized to \code{1} unless the environment variable
20330e13211e Update to better reflect the usage of struct_time instances throughout;
Fred Drake <fdrake@acm.org>
parents: 26925
diff changeset
37 \envvar{PYTHONY2K} is set to a non-empty string, in which case it is
20330e13211e Update to better reflect the usage of struct_time instances throughout;
Fred Drake <fdrake@acm.org>
parents: 26925
diff changeset
38 initialized to \code{0}. Thus, you can set
10243
575c4ea2542b Fix an amazing number of typos & malformed sentences reported by Detlef
Fred Drake <fdrake@acm.org>
parents: 9911
diff changeset
39 \envvar{PYTHONY2K} to a non-empty string in the environment to require 4-digit
9611
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
40 years for all year input. When 2-digit years are accepted, they are
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
41 converted according to the \POSIX{} or X/Open standard: values 69-99
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
42 are mapped to 1969-1999, and values 0--68 are mapped to 2000--2068.
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
43 Values 100--1899 are always illegal. Note that this is new as of
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
44 Python 1.5.2(a2); earlier versions, up to Python 1.5.1 and 1.5.2a1,
10881
838cb34abb79 Move some \index entries around so we can avoid using empty comments;
Fred Drake <fdrake@acm.org>
parents: 10243
diff changeset
45 would add 1900 to year values below 1900.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
46
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
47 \item
10881
838cb34abb79 Move some \index entries around so we can avoid using empty comments;
Fred Drake <fdrake@acm.org>
parents: 10243
diff changeset
48 UTC\index{UTC} is Coordinated Universal Time\index{Coordinated
838cb34abb79 Move some \index entries around so we can avoid using empty comments;
Fred Drake <fdrake@acm.org>
parents: 10243
diff changeset
49 Universal Time} (formerly known as Greenwich Mean
838cb34abb79 Move some \index entries around so we can avoid using empty comments;
Fred Drake <fdrake@acm.org>
parents: 10243
diff changeset
50 Time,\index{Greenwich Mean Time} or GMT). The acronym UTC is not a
838cb34abb79 Move some \index entries around so we can avoid using empty comments;
Fred Drake <fdrake@acm.org>
parents: 10243
diff changeset
51 mistake but a compromise between English and French.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
52
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
53 \item
10881
838cb34abb79 Move some \index entries around so we can avoid using empty comments;
Fred Drake <fdrake@acm.org>
parents: 10243
diff changeset
54 DST is Daylight Saving Time,\index{Daylight Saving Time} an adjustment
838cb34abb79 Move some \index entries around so we can avoid using empty comments;
Fred Drake <fdrake@acm.org>
parents: 10243
diff changeset
55 of the timezone by (usually) one hour during part of the year. DST
838cb34abb79 Move some \index entries around so we can avoid using empty comments;
Fred Drake <fdrake@acm.org>
parents: 10243
diff changeset
56 rules are magic (determined by local law) and can change from year to
838cb34abb79 Move some \index entries around so we can avoid using empty comments;
Fred Drake <fdrake@acm.org>
parents: 10243
diff changeset
57 year. The C library has a table containing the local rules (often it
838cb34abb79 Move some \index entries around so we can avoid using empty comments;
Fred Drake <fdrake@acm.org>
parents: 10243
diff changeset
58 is read from a system file for flexibility) and is the only source of
838cb34abb79 Move some \index entries around so we can avoid using empty comments;
Fred Drake <fdrake@acm.org>
parents: 10243
diff changeset
59 True Wisdom in this respect.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
60
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
61 \item
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
62 The precision of the various real-time functions may be less than
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
63 suggested by the units in which their value or argument is expressed.
4729
e27fa2a3f526 (libtime.tex): Merged in changes from Tamito Kajiyama.
Fred Drake <fdrake@acm.org>
parents: 4695
diff changeset
64 E.g.\ on most \UNIX{} systems, the clock ``ticks'' only 50 or 100 times a
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
65 second, and on the Mac, times are only accurate to whole seconds.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
66
3859
0853166f0d69 Moved description of mktime 9-tuple to top.
Guido van Rossum <guido@python.org>
parents: 3714
diff changeset
67 \item
7814
a727ae6bfe50 Minor nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
68 On the other hand, the precision of \function{time()} and
a727ae6bfe50 Minor nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
69 \function{sleep()} is better than their \UNIX{} equivalents: times are
a727ae6bfe50 Minor nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
70 expressed as floating point numbers, \function{time()} returns the
a727ae6bfe50 Minor nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
71 most accurate time available (using \UNIX{} \cfunction{gettimeofday()}
a727ae6bfe50 Minor nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
72 where available), and \function{sleep()} will accept a time with a
a727ae6bfe50 Minor nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
73 nonzero fraction (\UNIX{} \cfunction{select()} is used to implement
a727ae6bfe50 Minor nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
74 this, where available).
4695
f12b1d4d6a9b Added remark about time() and sleep()'s subsecond precision.
Guido van Rossum <guido@python.org>
parents: 3859
diff changeset
75
f12b1d4d6a9b Added remark about time() and sleep()'s subsecond precision.
Guido van Rossum <guido@python.org>
parents: 3859
diff changeset
76 \item
26193
d5633e93f707 Document struct_time and the field names.
Fred Drake <fdrake@acm.org>
parents: 25963
diff changeset
77 The time value as returned by \function{gmtime()},
8478
4ba587aa8a98 Added notes about epochs, the year 2038, and a small Y2K disclaimer
Guido van Rossum <guido@python.org>
parents: 8471
diff changeset
78 \function{localtime()}, and \function{strptime()}, and accepted by
9911
20d98ca3d32f Fix second description of handling 2-digit years (last item in
Fred Drake <fdrake@acm.org>
parents: 9611
diff changeset
79 \function{asctime()}, \function{mktime()} and \function{strftime()},
26193
d5633e93f707 Document struct_time and the field names.
Fred Drake <fdrake@acm.org>
parents: 25963
diff changeset
80 is a sequence of 9 integers. The return values of \function{gmtime()},
d5633e93f707 Document struct_time and the field names.
Fred Drake <fdrake@acm.org>
parents: 25963
diff changeset
81 \function{localtime()}, and \function{strptime()} also offer attribute
d5633e93f707 Document struct_time and the field names.
Fred Drake <fdrake@acm.org>
parents: 25963
diff changeset
82 names for individual fields.
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
83
26193
d5633e93f707 Document struct_time and the field names.
Fred Drake <fdrake@acm.org>
parents: 25963
diff changeset
84 \begin{tableiii}{c|l|l}{textrm}{Index}{Attribute}{Values}
d5633e93f707 Document struct_time and the field names.
Fred Drake <fdrake@acm.org>
parents: 25963
diff changeset
85 \lineiii{0}{\member{tm_year}}{(for example, 1993)}
d5633e93f707 Document struct_time and the field names.
Fred Drake <fdrake@acm.org>
parents: 25963
diff changeset
86 \lineiii{1}{\member{tm_mon}}{range [1,12]}
d5633e93f707 Document struct_time and the field names.
Fred Drake <fdrake@acm.org>
parents: 25963
diff changeset
87 \lineiii{2}{\member{tm_mday}}{range [1,31]}
d5633e93f707 Document struct_time and the field names.
Fred Drake <fdrake@acm.org>
parents: 25963
diff changeset
88 \lineiii{3}{\member{tm_hour}}{range [0,23]}
d5633e93f707 Document struct_time and the field names.
Fred Drake <fdrake@acm.org>
parents: 25963
diff changeset
89 \lineiii{4}{\member{tm_min}}{range [0,59]}
d5633e93f707 Document struct_time and the field names.
Fred Drake <fdrake@acm.org>
parents: 25963
diff changeset
90 \lineiii{5}{\member{tm_sec}}{range [0,61]; see \strong{(1)} in \function{strftime()} description}
d5633e93f707 Document struct_time and the field names.
Fred Drake <fdrake@acm.org>
parents: 25963
diff changeset
91 \lineiii{6}{\member{tm_wday}}{range [0,6], Monday is 0}
d5633e93f707 Document struct_time and the field names.
Fred Drake <fdrake@acm.org>
parents: 25963
diff changeset
92 \lineiii{7}{\member{tm_yday}}{range [1,366]}
d5633e93f707 Document struct_time and the field names.
Fred Drake <fdrake@acm.org>
parents: 25963
diff changeset
93 \lineiii{8}{\member{tm_isdst}}{0, 1 or -1; see below}
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
94 \end{tableiii}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
95
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
96 Note that unlike the C structure, the month value is a
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
97 range of 1-12, not 0-11. A year value will be handled as described
26193
d5633e93f707 Document struct_time and the field names.
Fred Drake <fdrake@acm.org>
parents: 25963
diff changeset
98 under ``Year 2000 (Y2K) issues'' above. A \code{-1} argument as the
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
99 daylight savings flag, passed to \function{mktime()} will usually
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
100 result in the correct daylight savings state to be filled in.
3859
0853166f0d69 Moved description of mktime 9-tuple to top.
Guido van Rossum <guido@python.org>
parents: 3714
diff changeset
101
20744
23d230ef415b Add additional information on exceptions from time.mktime() and related to
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
102 When a tuple with an incorrect length is passed to a function
27670
20330e13211e Update to better reflect the usage of struct_time instances throughout;
Fred Drake <fdrake@acm.org>
parents: 26925
diff changeset
103 expecting a \class{struct_time}, or having elements of the wrong type, a
20744
23d230ef415b Add additional information on exceptions from time.mktime() and related to
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
104 \exception{TypeError} is raised.
23d230ef415b Add additional information on exceptions from time.mktime() and related to
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
105
26193
d5633e93f707 Document struct_time and the field names.
Fred Drake <fdrake@acm.org>
parents: 25963
diff changeset
106 \versionchanged[The time value sequence was changed from a tuple to a
27670
20330e13211e Update to better reflect the usage of struct_time instances throughout;
Fred Drake <fdrake@acm.org>
parents: 26925
diff changeset
107 \class{struct_time}, with the addition of attribute names
26193
d5633e93f707 Document struct_time and the field names.
Fred Drake <fdrake@acm.org>
parents: 25963
diff changeset
108 for the fields]{2.2}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
109 \end{itemize}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
110
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
111 The module defines the following functions and data items:
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
112
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
113
9911
20d98ca3d32f Fix second description of handling 2-digit years (last item in
Fred Drake <fdrake@acm.org>
parents: 9611
diff changeset
114 \begin{datadesc}{accept2dyear}
20d98ca3d32f Fix second description of handling 2-digit years (last item in
Fred Drake <fdrake@acm.org>
parents: 9611
diff changeset
115 Boolean value indicating whether two-digit year values will be
20d98ca3d32f Fix second description of handling 2-digit years (last item in
Fred Drake <fdrake@acm.org>
parents: 9611
diff changeset
116 accepted. This is true by default, but will be set to false if the
20d98ca3d32f Fix second description of handling 2-digit years (last item in
Fred Drake <fdrake@acm.org>
parents: 9611
diff changeset
117 environment variable \envvar{PYTHONY2K} has been set to a non-empty
20d98ca3d32f Fix second description of handling 2-digit years (last item in
Fred Drake <fdrake@acm.org>
parents: 9611
diff changeset
118 string. It may also be modified at run time.
20d98ca3d32f Fix second description of handling 2-digit years (last item in
Fred Drake <fdrake@acm.org>
parents: 9611
diff changeset
119 \end{datadesc}
20d98ca3d32f Fix second description of handling 2-digit years (last item in
Fred Drake <fdrake@acm.org>
parents: 9611
diff changeset
120
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
121 \begin{datadesc}{altzone}
12245
612be1bb65ff Noted by Guido:
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
122 The offset of the local DST timezone, in seconds west of UTC, if one
13179
915d985918e2 Change description of altzone to not refer to the "0th meridian".
Fred Drake <fdrake@acm.org>
parents: 12245
diff changeset
123 is defined. This is negative if the local DST timezone is east of UTC
915d985918e2 Change description of altzone to not refer to the "0th meridian".
Fred Drake <fdrake@acm.org>
parents: 12245
diff changeset
124 (as in Western Europe, including the UK). Only use this if
12245
612be1bb65ff Noted by Guido:
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
125 \code{daylight} is nonzero.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
126 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
127
27670
20330e13211e Update to better reflect the usage of struct_time instances throughout;
Fred Drake <fdrake@acm.org>
parents: 26925
diff changeset
128 \begin{funcdesc}{asctime}{\optional{t}}
20330e13211e Update to better reflect the usage of struct_time instances throughout;
Fred Drake <fdrake@acm.org>
parents: 26925
diff changeset
129 Convert a tuple or \class{struct_time} representing a time as returned
20330e13211e Update to better reflect the usage of struct_time instances throughout;
Fred Drake <fdrake@acm.org>
parents: 26925
diff changeset
130 by \function{gmtime()}
9611
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
131 or \function{localtime()} to a 24-character string of the following form:
27670
20330e13211e Update to better reflect the usage of struct_time instances throughout;
Fred Drake <fdrake@acm.org>
parents: 26925
diff changeset
132 \code{'Sun Jun 20 23:21:05 1993'}. If \var{t} is not provided, the
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 19428
diff changeset
133 current time as returned by \function{localtime()} is used.
25963
323e4c1146d0 Add notes to the asctime() and ctime() descriptions to make it
Fred Drake <fdrake@acm.org>
parents: 24324
diff changeset
134 Locale information is not used by \function{asctime()}.
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 19428
diff changeset
135 \note{Unlike the C function of the same name, there is no trailing
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 19428
diff changeset
136 newline.}
27670
20330e13211e Update to better reflect the usage of struct_time instances throughout;
Fred Drake <fdrake@acm.org>
parents: 26925
diff changeset
137 \versionchanged[Allowed \var{t} to be omitted]{2.1}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
138 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
139
1807
782509813d57 * Doc/libtime.tex: get rid of references to millitime() and
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
140 \begin{funcdesc}{clock}{}
18623
35fec487bcef Revise the description of time.clock() so that it correctly describes the
Fred Drake <fdrake@acm.org>
parents: 18574
diff changeset
141 On \UNIX, return
35fec487bcef Revise the description of time.clock() so that it correctly describes the
Fred Drake <fdrake@acm.org>
parents: 18574
diff changeset
142 the current processor time as a floating point number expressed in
13625
fdfd1049f36e Rob W. W. Hooft's spelling fixes for the Library Reference. I hope
Thomas Wouters <thomas@python.org>
parents: 13384
diff changeset
143 seconds. The precision, and in fact the very definition of the meaning
18623
35fec487bcef Revise the description of time.clock() so that it correctly describes the
Fred Drake <fdrake@acm.org>
parents: 18574
diff changeset
144 of ``processor time''\index{CPU time}\index{processor time}, depends
35fec487bcef Revise the description of time.clock() so that it correctly describes the
Fred Drake <fdrake@acm.org>
parents: 18574
diff changeset
145 on that of the C function of the same name, but in any case, this is
35fec487bcef Revise the description of time.clock() so that it correctly describes the
Fred Drake <fdrake@acm.org>
parents: 18574
diff changeset
146 the function to use for benchmarking\index{benchmarking} Python or
35fec487bcef Revise the description of time.clock() so that it correctly describes the
Fred Drake <fdrake@acm.org>
parents: 18574
diff changeset
147 timing algorithms.
35fec487bcef Revise the description of time.clock() so that it correctly describes the
Fred Drake <fdrake@acm.org>
parents: 18574
diff changeset
148
19376
9e4f739e9a84 Improve Windows time.clock() blurb; was missing return type and unit.
Tim Peters <tim.peters@gmail.com>
parents: 19005
diff changeset
149 On Windows, this function returns wall-clock seconds elapsed since the
9e4f739e9a84 Improve Windows time.clock() blurb; was missing return type and unit.
Tim Peters <tim.peters@gmail.com>
parents: 19005
diff changeset
150 first call to this function, as a floating point number,
9e4f739e9a84 Improve Windows time.clock() blurb; was missing return type and unit.
Tim Peters <tim.peters@gmail.com>
parents: 19005
diff changeset
151 based on the Win32 function \cfunction{QueryPerformanceCounter()}.
9e4f739e9a84 Improve Windows time.clock() blurb; was missing return type and unit.
Tim Peters <tim.peters@gmail.com>
parents: 19005
diff changeset
152 The resolution is typically better than one microsecond.
1807
782509813d57 * Doc/libtime.tex: get rid of references to millitime() and
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
153 \end{funcdesc}
782509813d57 * Doc/libtime.tex: get rid of references to millitime() and
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
154
16054
4cc9a1ebea62 Make the 'time' argument to the timemodule functions strftime, asctime,
Thomas Wouters <thomas@python.org>
parents: 14784
diff changeset
155 \begin{funcdesc}{ctime}{\optional{secs}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
156 Convert a time expressed in seconds since the epoch to a string
16054
4cc9a1ebea62 Make the 'time' argument to the timemodule functions strftime, asctime,
Thomas Wouters <thomas@python.org>
parents: 14784
diff changeset
157 representing local time. If \var{secs} is not provided, the current time
4cc9a1ebea62 Make the 'time' argument to the timemodule functions strftime, asctime,
Thomas Wouters <thomas@python.org>
parents: 14784
diff changeset
158 as returned by \function{time()} is used. \code{ctime(\var{secs})}
4cc9a1ebea62 Make the 'time' argument to the timemodule functions strftime, asctime,
Thomas Wouters <thomas@python.org>
parents: 14784
diff changeset
159 is equivalent to \code{asctime(localtime(\var{secs}))}.
25963
323e4c1146d0 Add notes to the asctime() and ctime() descriptions to make it
Fred Drake <fdrake@acm.org>
parents: 24324
diff changeset
160 Locale information is not used by \function{ctime()}.
17589
96f9b86b7b3d Add versioning notes: many of the signatures changed to allow the time
Fred Drake <fdrake@acm.org>
parents: 16443
diff changeset
161 \versionchanged[Allowed \var{secs} to be omitted]{2.1}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
162 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
163
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
164 \begin{datadesc}{daylight}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
165 Nonzero if a DST timezone is defined.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
166 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
167
16054
4cc9a1ebea62 Make the 'time' argument to the timemodule functions strftime, asctime,
Thomas Wouters <thomas@python.org>
parents: 14784
diff changeset
168 \begin{funcdesc}{gmtime}{\optional{secs}}
27670
20330e13211e Update to better reflect the usage of struct_time instances throughout;
Fred Drake <fdrake@acm.org>
parents: 26925
diff changeset
169 Convert a time expressed in seconds since the epoch to a \class{struct_time}
16054
4cc9a1ebea62 Make the 'time' argument to the timemodule functions strftime, asctime,
Thomas Wouters <thomas@python.org>
parents: 14784
diff changeset
170 in UTC in which the dst flag is always zero. If \var{secs} is not
4cc9a1ebea62 Make the 'time' argument to the timemodule functions strftime, asctime,
Thomas Wouters <thomas@python.org>
parents: 14784
diff changeset
171 provided, the current time as returned by \function{time()} is used.
4cc9a1ebea62 Make the 'time' argument to the timemodule functions strftime, asctime,
Thomas Wouters <thomas@python.org>
parents: 14784
diff changeset
172 Fractions of a second are ignored. See above for a description of the
27670
20330e13211e Update to better reflect the usage of struct_time instances throughout;
Fred Drake <fdrake@acm.org>
parents: 26925
diff changeset
173 \class{struct_time} object.
17589
96f9b86b7b3d Add versioning notes: many of the signatures changed to allow the time
Fred Drake <fdrake@acm.org>
parents: 16443
diff changeset
174 \versionchanged[Allowed \var{secs} to be omitted]{2.1}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
175 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
176
16054
4cc9a1ebea62 Make the 'time' argument to the timemodule functions strftime, asctime,
Thomas Wouters <thomas@python.org>
parents: 14784
diff changeset
177 \begin{funcdesc}{localtime}{\optional{secs}}
7814
a727ae6bfe50 Minor nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
178 Like \function{gmtime()} but converts to local time. The dst flag is
a727ae6bfe50 Minor nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
179 set to \code{1} when DST applies to the given time.
17589
96f9b86b7b3d Add versioning notes: many of the signatures changed to allow the time
Fred Drake <fdrake@acm.org>
parents: 16443
diff changeset
180 \versionchanged[Allowed \var{secs} to be omitted]{2.1}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
181 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
182
27670
20330e13211e Update to better reflect the usage of struct_time instances throughout;
Fred Drake <fdrake@acm.org>
parents: 26925
diff changeset
183 \begin{funcdesc}{mktime}{t}
9611
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
184 This is the inverse function of \function{localtime()}. Its argument
27670
20330e13211e Update to better reflect the usage of struct_time instances throughout;
Fred Drake <fdrake@acm.org>
parents: 26925
diff changeset
185 is the \class{struct_time} or full 9-tuple (since the dst flag is
20330e13211e Update to better reflect the usage of struct_time instances throughout;
Fred Drake <fdrake@acm.org>
parents: 26925
diff changeset
186 needed; use \code{-1} as the dst flag if it is unknown) which
20330e13211e Update to better reflect the usage of struct_time instances throughout;
Fred Drake <fdrake@acm.org>
parents: 26925
diff changeset
187 expresses the time in
9611
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
188 \emph{local} time, not UTC. It returns a floating point number, for
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
189 compatibility with \function{time()}. If the input value cannot be
20744
23d230ef415b Add additional information on exceptions from time.mktime() and related to
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
190 represented as a valid time, either \exception{OverflowError} or
23d230ef415b Add additional information on exceptions from time.mktime() and related to
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
191 \exception{ValueError} will be raised (which depends on whether the
23d230ef415b Add additional information on exceptions from time.mktime() and related to
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
192 invalid value is caught by Python or the underlying C libraries). The
19428
c72616d6143c indicate that mktime is platform-dependent. See SF bug 434143.
Skip Montanaro <skip@pobox.com>
parents: 19376
diff changeset
193 earliest date for which it can generate a time is platform-dependent.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
194 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
195
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
196 \begin{funcdesc}{sleep}{secs}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
197 Suspend execution for the given number of seconds. The argument may
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
198 be a floating point number to indicate a more precise sleep time.
11207
c388f00affe7 Added disclaimer to the sleep() function.
Guido van Rossum <guido@python.org>
parents: 10881
diff changeset
199 The actual suspension time may be less than that requested because any
c388f00affe7 Added disclaimer to the sleep() function.
Guido van Rossum <guido@python.org>
parents: 10881
diff changeset
200 caught signal will terminate the \function{sleep()} following
c388f00affe7 Added disclaimer to the sleep() function.
Guido van Rossum <guido@python.org>
parents: 10881
diff changeset
201 execution of that signal's catching routine. Also, the suspension
c388f00affe7 Added disclaimer to the sleep() function.
Guido van Rossum <guido@python.org>
parents: 10881
diff changeset
202 time may be longer than requested by an arbitrary amount because of
c388f00affe7 Added disclaimer to the sleep() function.
Guido van Rossum <guido@python.org>
parents: 10881
diff changeset
203 the scheduling of other activity in the system.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
204 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
205
27670
20330e13211e Update to better reflect the usage of struct_time instances throughout;
Fred Drake <fdrake@acm.org>
parents: 26925
diff changeset
206 \begin{funcdesc}{strftime}{format\optional{, t}}
20330e13211e Update to better reflect the usage of struct_time instances throughout;
Fred Drake <fdrake@acm.org>
parents: 26925
diff changeset
207 Convert a tuple or \class{struct_time} representing a time as returned
20330e13211e Update to better reflect the usage of struct_time instances throughout;
Fred Drake <fdrake@acm.org>
parents: 26925
diff changeset
208 by \function{gmtime()} or \function{localtime()} to a string as
20330e13211e Update to better reflect the usage of struct_time instances throughout;
Fred Drake <fdrake@acm.org>
parents: 26925
diff changeset
209 specified by the \var{format} argument. If \var{t} is not
20330e13211e Update to better reflect the usage of struct_time instances throughout;
Fred Drake <fdrake@acm.org>
parents: 26925
diff changeset
210 provided, the current time as returned by \function{localtime()} is
20330e13211e Update to better reflect the usage of struct_time instances throughout;
Fred Drake <fdrake@acm.org>
parents: 26925
diff changeset
211 used. \var{format} must be a string.
20330e13211e Update to better reflect the usage of struct_time instances throughout;
Fred Drake <fdrake@acm.org>
parents: 26925
diff changeset
212 \versionchanged[Allowed \var{t} to be omitted]{2.1}
3859
0853166f0d69 Moved description of mktime 9-tuple to top.
Guido van Rossum <guido@python.org>
parents: 3714
diff changeset
213
9611
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
214 The following directives can be embedded in the \var{format} string.
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
215 They are shown without the optional field width and precision
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
216 specification, and are replaced by the indicated characters in the
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
217 \function{strftime()} result:
3859
0853166f0d69 Moved description of mktime 9-tuple to top.
Guido van Rossum <guido@python.org>
parents: 3714
diff changeset
218
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
219 \begin{tableiii}{c|p{24em}|c}{code}{Directive}{Meaning}{Notes}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
220 \lineiii{\%a}{Locale's abbreviated weekday name.}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
221 \lineiii{\%A}{Locale's full weekday name.}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
222 \lineiii{\%b}{Locale's abbreviated month name.}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
223 \lineiii{\%B}{Locale's full month name.}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
224 \lineiii{\%c}{Locale's appropriate date and time representation.}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
225 \lineiii{\%d}{Day of the month as a decimal number [01,31].}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
226 \lineiii{\%H}{Hour (24-hour clock) as a decimal number [00,23].}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
227 \lineiii{\%I}{Hour (12-hour clock) as a decimal number [01,12].}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
228 \lineiii{\%j}{Day of the year as a decimal number [001,366].}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
229 \lineiii{\%m}{Month as a decimal number [01,12].}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
230 \lineiii{\%M}{Minute as a decimal number [00,59].}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
231 \lineiii{\%p}{Locale's equivalent of either AM or PM.}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
232 \lineiii{\%S}{Second as a decimal number [00,61].}{(1)}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
233 \lineiii{\%U}{Week number of the year (Sunday as the first day of the
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
234 week) as a decimal number [00,53]. All days in a new year
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
235 preceding the first Sunday are considered to be in week 0.}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
236 \lineiii{\%w}{Weekday as a decimal number [0(Sunday),6].}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
237 \lineiii{\%W}{Week number of the year (Monday as the first day of the
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
238 week) as a decimal number [00,53]. All days in a new year
26732
a03ce5d8f297 Fixed longstanding bug in the description of strftime's %W code.
Tim Peters <tim.peters@gmail.com>
parents: 26255
diff changeset
239 preceding the first Monday are considered to be in week 0.}{}
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
240 \lineiii{\%x}{Locale's appropriate date representation.}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
241 \lineiii{\%X}{Locale's appropriate time representation.}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
242 \lineiii{\%y}{Year without century as a decimal number [00,99].}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
243 \lineiii{\%Y}{Year with century as a decimal number.}{}
26925
96468870d206 Phrase repair.
Guido van Rossum <guido@python.org>
parents: 26732
diff changeset
244 \lineiii{\%Z}{Time zone name (no characters if no time zone exists).}{}
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
245 \lineiii{\%\%}{A literal \character{\%} character.}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
246 \end{tableiii}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
247
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
248 \noindent
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
249 Notes:
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
250
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
251 \begin{description}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
252 \item[(1)]
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
253 The range really is \code{0} to \code{61}; this accounts for leap
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
254 seconds and the (very rare) double leap seconds.
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
255 \end{description}
3859
0853166f0d69 Moved description of mktime 9-tuple to top.
Guido van Rossum <guido@python.org>
parents: 3714
diff changeset
256
16312
b8018145e2a5 Instructive example for strftime(); how to generate RFC822 dates.
Eric S. Raymond <esr@thyrsus.com>
parents: 16054
diff changeset
257 Here is an example, a format for dates compatible with that specified
18341
f70b2d63f309 SourceForge bug #437041:
Fred Drake <fdrake@acm.org>
parents: 17589
diff changeset
258 in the \rfc{2822} Internet email standard.
f70b2d63f309 SourceForge bug #437041:
Fred Drake <fdrake@acm.org>
parents: 17589
diff changeset
259 \footnote{The use of \code{\%Z} is now
f70b2d63f309 SourceForge bug #437041:
Fred Drake <fdrake@acm.org>
parents: 17589
diff changeset
260 deprecated, but the \code{\%z} escape that expands to the preferred
16312
b8018145e2a5 Instructive example for strftime(); how to generate RFC822 dates.
Eric S. Raymond <esr@thyrsus.com>
parents: 16054
diff changeset
261 hour/minute offset is not supported by all ANSI C libraries. Also,
b8018145e2a5 Instructive example for strftime(); how to generate RFC822 dates.
Eric S. Raymond <esr@thyrsus.com>
parents: 16054
diff changeset
262 a strict reading of the original 1982 \rfc{822} standard calls for
b8018145e2a5 Instructive example for strftime(); how to generate RFC822 dates.
Eric S. Raymond <esr@thyrsus.com>
parents: 16054
diff changeset
263 a two-digit year (\%y rather than \%Y), but practice moved to
18341
f70b2d63f309 SourceForge bug #437041:
Fred Drake <fdrake@acm.org>
parents: 17589
diff changeset
264 4-digit years long before the year 2000. The 4-digit year has
f70b2d63f309 SourceForge bug #437041:
Fred Drake <fdrake@acm.org>
parents: 17589
diff changeset
265 been mandated by \rfc{2822}, which obsoletes \rfc{822}.}
16312
b8018145e2a5 Instructive example for strftime(); how to generate RFC822 dates.
Eric S. Raymond <esr@thyrsus.com>
parents: 16054
diff changeset
266
b8018145e2a5 Instructive example for strftime(); how to generate RFC822 dates.
Eric S. Raymond <esr@thyrsus.com>
parents: 16054
diff changeset
267 \begin{verbatim}
18341
f70b2d63f309 SourceForge bug #437041:
Fred Drake <fdrake@acm.org>
parents: 17589
diff changeset
268 >>> from time import gmtime, strftime
f70b2d63f309 SourceForge bug #437041:
Fred Drake <fdrake@acm.org>
parents: 17589
diff changeset
269 >>> strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime())
f70b2d63f309 SourceForge bug #437041:
Fred Drake <fdrake@acm.org>
parents: 17589
diff changeset
270 'Thu, 28 Jun 2001 14:17:15 +0000'
16312
b8018145e2a5 Instructive example for strftime(); how to generate RFC822 dates.
Eric S. Raymond <esr@thyrsus.com>
parents: 16054
diff changeset
271 \end{verbatim}
b8018145e2a5 Instructive example for strftime(); how to generate RFC822 dates.
Eric S. Raymond <esr@thyrsus.com>
parents: 16054
diff changeset
272
4729
e27fa2a3f526 (libtime.tex): Merged in changes from Tamito Kajiyama.
Fred Drake <fdrake@acm.org>
parents: 4695
diff changeset
273 Additional directives may be supported on certain platforms, but
10881
838cb34abb79 Move some \index entries around so we can avoid using empty comments;
Fred Drake <fdrake@acm.org>
parents: 10243
diff changeset
274 only the ones listed here have a meaning standardized by ANSI C.
3859
0853166f0d69 Moved description of mktime 9-tuple to top.
Guido van Rossum <guido@python.org>
parents: 3714
diff changeset
275
4729
e27fa2a3f526 (libtime.tex): Merged in changes from Tamito Kajiyama.
Fred Drake <fdrake@acm.org>
parents: 4695
diff changeset
276 On some platforms, an optional field width and precision
9611
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
277 specification can immediately follow the initial \character{\%} of a
4729
e27fa2a3f526 (libtime.tex): Merged in changes from Tamito Kajiyama.
Fred Drake <fdrake@acm.org>
parents: 4695
diff changeset
278 directive in the following order; this is also not portable.
7814
a727ae6bfe50 Minor nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
279 The field width is normally 2 except for \code{\%j} where it is 3.
3085
a7c97c437191 added strftime
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
280 \end{funcdesc}
a7c97c437191 added strftime
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
281
8471
c89189b0236e Added docs for strptime().
Guido van Rossum <guido@python.org>
parents: 8018
diff changeset
282 \begin{funcdesc}{strptime}{string\optional{, format}}
c89189b0236e Added docs for strptime().
Guido van Rossum <guido@python.org>
parents: 8018
diff changeset
283 Parse a string representing a time according to a format. The return
27670
20330e13211e Update to better reflect the usage of struct_time instances throughout;
Fred Drake <fdrake@acm.org>
parents: 26925
diff changeset
284 value is a \class{struct_time} as returned by \function{gmtime()} or
9611
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
285 \function{localtime()}. The \var{format} parameter uses the same
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
286 directives as those used by \function{strftime()}; it defaults to
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
287 \code{"\%a \%b \%d \%H:\%M:\%S \%Y"} which matches the formatting
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
288 returned by \function{ctime()}. The same platform caveats apply; see
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
289 the local \UNIX{} documentation for restrictions or additional
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
290 supported directives. If \var{string} cannot be parsed according to
14784
0985ddfd442b Added warnings about platform vagaries to the strptime() documentation.
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
291 \var{format}, \exception{ValueError} is raised. Values which are not
0985ddfd442b Added warnings about platform vagaries to the strptime() documentation.
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
292 provided as part of the input string are filled in with default
0985ddfd442b Added warnings about platform vagaries to the strptime() documentation.
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
293 values; the specific values are platform-dependent as the XPG standard
0985ddfd442b Added warnings about platform vagaries to the strptime() documentation.
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
294 does not provide sufficient information to constrain the result.
8471
c89189b0236e Added docs for strptime().
Guido van Rossum <guido@python.org>
parents: 8018
diff changeset
295 \end{funcdesc}
c89189b0236e Added docs for strptime().
Guido van Rossum <guido@python.org>
parents: 8018
diff changeset
296
26193
d5633e93f707 Document struct_time and the field names.
Fred Drake <fdrake@acm.org>
parents: 25963
diff changeset
297 \begin{datadesc}{struct_time}
d5633e93f707 Document struct_time and the field names.
Fred Drake <fdrake@acm.org>
parents: 25963
diff changeset
298 The type of the time value sequence returned by \function{gmtime()},
d5633e93f707 Document struct_time and the field names.
Fred Drake <fdrake@acm.org>
parents: 25963
diff changeset
299 \function{localtime()}, and \function{strptime()}.
d5633e93f707 Document struct_time and the field names.
Fred Drake <fdrake@acm.org>
parents: 25963
diff changeset
300 \versionadded{2.2}
d5633e93f707 Document struct_time and the field names.
Fred Drake <fdrake@acm.org>
parents: 25963
diff changeset
301 \end{datadesc}
d5633e93f707 Document struct_time and the field names.
Fred Drake <fdrake@acm.org>
parents: 25963
diff changeset
302
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
303 \begin{funcdesc}{time}{}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
304 Return the time as a floating point number expressed in seconds since
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
305 the epoch, in UTC. Note that even though the time is always returned
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
306 as a floating point number, not all systems provide time with a better
19005
c942a9821d09 Add a comment on time.time() returning non-decreasing values except when
Fred Drake <fdrake@acm.org>
parents: 18623
diff changeset
307 precision than 1 second. While this function normally returns
c942a9821d09 Add a comment on time.time() returning non-decreasing values except when
Fred Drake <fdrake@acm.org>
parents: 18623
diff changeset
308 non-decreasing values, it can return a lower value than a previous
c942a9821d09 Add a comment on time.time() returning non-decreasing values except when
Fred Drake <fdrake@acm.org>
parents: 18623
diff changeset
309 call if the system clock has been set back between the two calls.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
310 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
311
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
312 \begin{datadesc}{timezone}
12245
612be1bb65ff Noted by Guido:
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
313 The offset of the local (non-DST) timezone, in seconds west of UTC
18416
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18341
diff changeset
314 (negative in most of Western Europe, positive in the US, zero in the
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18341
diff changeset
315 UK).
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
316 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
317
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
318 \begin{datadesc}{tzname}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
319 A tuple of two strings: the first is the name of the local non-DST
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
320 timezone, the second is the name of the local DST timezone. If no DST
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
321 timezone is defined, the second string should not be used.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
322 \end{datadesc}
3859
0853166f0d69 Moved description of mktime 9-tuple to top.
Guido van Rossum <guido@python.org>
parents: 3714
diff changeset
323
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
324
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
325 \begin{seealso}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
326 \seemodule{locale}{Internationalization services. The locale
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
327 settings can affect the return values for some of
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
328 the functions in the \module{time} module.}
26255
22d7325ba7ac SF 639138, Ref. calendar module in time docs by John J Lee
Neal Norwitz <nnorwitz@gmail.com>
parents: 26193
diff changeset
329 \seemodule{calendar}{General calendar-related functions.
22d7325ba7ac SF 639138, Ref. calendar module in time docs by John J Lee
Neal Norwitz <nnorwitz@gmail.com>
parents: 26193
diff changeset
330 \function{timegm()} is the inverse of
22d7325ba7ac SF 639138, Ref. calendar module in time docs by John J Lee
Neal Norwitz <nnorwitz@gmail.com>
parents: 26193
diff changeset
331 \function{gmtime()} from this module.}
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
332 \end{seealso}