Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libtime.tex @ 21467:4e35fa5d5708 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add documentation for the help() built-in; contributed by Ka-Ping Yee. This is part of SF patch #494622.
author Fred Drake <fdrake@acm.org>
date Tue, 18 Dec 2001 16:31:08 +0000
parents bc02c3b09626
children 5517c36ac497 d9add40f92ff
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
838cb34abb79 Move some \index entries around so we can avoid using empty comments;
Fred Drake <fdrake@acm.org>
parents: 10243
diff changeset
32 seconds since the epoch. Functions accepting a time tuple (see below)
838cb34abb79 Move some \index entries around so we can avoid using empty comments;
Fred Drake <fdrake@acm.org>
parents: 10243
diff changeset
33 generally require a 4-digit year. For backward compatibility, 2-digit
838cb34abb79 Move some \index entries around so we can avoid using empty comments;
Fred Drake <fdrake@acm.org>
parents: 10243
diff changeset
34 years are supported if the module variable \code{accept2dyear} is a
838cb34abb79 Move some \index entries around so we can avoid using empty comments;
Fred Drake <fdrake@acm.org>
parents: 10243
diff changeset
35 non-zero integer; this variable is initialized to \code{1} unless the
9611
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
36 environment variable \envvar{PYTHONY2K} is set to a non-empty string,
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
37 in which case it is 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
38 \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
39 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
40 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
41 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
42 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
43 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
44 would add 1900 to year values below 1900.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
45
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
46 \item
10881
838cb34abb79 Move some \index entries around so we can avoid using empty comments;
Fred Drake <fdrake@acm.org>
parents: 10243
diff changeset
47 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
48 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
49 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
50 mistake but a compromise between English and French.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
51
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
52 \item
10881
838cb34abb79 Move some \index entries around so we can avoid using empty comments;
Fred Drake <fdrake@acm.org>
parents: 10243
diff changeset
53 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
54 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
55 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
56 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
57 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
58 True Wisdom in this respect.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
59
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
60 \item
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
61 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
62 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
63 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
64 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
65
3859
0853166f0d69 Moved description of mktime 9-tuple to top.
Guido van Rossum <guido@python.org>
parents: 3714
diff changeset
66 \item
7814
a727ae6bfe50 Minor nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
67 On the other hand, the precision of \function{time()} and
a727ae6bfe50 Minor nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
68 \function{sleep()} is better than their \UNIX{} equivalents: times are
a727ae6bfe50 Minor nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
69 expressed as floating point numbers, \function{time()} returns the
a727ae6bfe50 Minor nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
70 most accurate time available (using \UNIX{} \cfunction{gettimeofday()}
a727ae6bfe50 Minor nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
71 where available), and \function{sleep()} will accept a time with a
a727ae6bfe50 Minor nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
72 nonzero fraction (\UNIX{} \cfunction{select()} is used to implement
a727ae6bfe50 Minor nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
73 this, where available).
4695
f12b1d4d6a9b Added remark about time() and sleep()'s subsecond precision.
Guido van Rossum <guido@python.org>
parents: 3859
diff changeset
74
f12b1d4d6a9b Added remark about time() and sleep()'s subsecond precision.
Guido van Rossum <guido@python.org>
parents: 3859
diff changeset
75 \item
8478
4ba587aa8a98 Added notes about epochs, the year 2038, and a small Y2K disclaimer
Guido van Rossum <guido@python.org>
parents: 8471
diff changeset
76 The time tuple as returned by \function{gmtime()},
4ba587aa8a98 Added notes about epochs, the year 2038, and a small Y2K disclaimer
Guido van Rossum <guido@python.org>
parents: 8471
diff changeset
77 \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
78 \function{asctime()}, \function{mktime()} and \function{strftime()},
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
79 is a tuple of 9 integers:
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
80
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
81 \begin{tableiii}{r|l|l}{textrm}{Index}{Field}{Values}
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
82 \lineiii{0}{year}{(for example, 1993)}
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
83 \lineiii{1}{month}{range [1,12]}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
84 \lineiii{2}{day}{range [1,31]}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
85 \lineiii{3}{hour}{range [0,23]}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
86 \lineiii{4}{minute}{range [0,59]}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
87 \lineiii{5}{second}{range [0,61]; see \strong{(1)} in \function{strftime()} description}
13625
fdfd1049f36e Rob W. W. Hooft's spelling fixes for the Library Reference. I hope
Thomas Wouters <thomas@python.org>
parents: 13384
diff changeset
88 \lineiii{6}{weekday}{range [0,6], Monday is 0}
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
89 \lineiii{7}{Julian day}{range [1,366]}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
90 \lineiii{8}{daylight savings flag}{0, 1 or -1; see below}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
91 \end{tableiii}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
92
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
93 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
94 range of 1-12, not 0-11. A year value will be handled as described
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
95 under ``Year 2000 (Y2K) issues'' above. A \code{-1} argument as
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
96 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
97 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
98
20744
23d230ef415b Add additional information on exceptions from time.mktime() and related to
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
99 When a tuple with an incorrect length is passed to a function
23d230ef415b Add additional information on exceptions from time.mktime() and related to
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
100 expecting a time tuple, or having elements of the wrong type, a
23d230ef415b Add additional information on exceptions from time.mktime() and related to
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
101 \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
102
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
103 \end{itemize}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
104
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
105 The module defines the following functions and data items:
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
106
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
107
9911
20d98ca3d32f Fix second description of handling 2-digit years (last item in
Fred Drake <fdrake@acm.org>
parents: 9611
diff changeset
108 \begin{datadesc}{accept2dyear}
20d98ca3d32f Fix second description of handling 2-digit years (last item in
Fred Drake <fdrake@acm.org>
parents: 9611
diff changeset
109 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
110 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
111 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
112 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
113 \end{datadesc}
20d98ca3d32f Fix second description of handling 2-digit years (last item in
Fred Drake <fdrake@acm.org>
parents: 9611
diff changeset
114
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
115 \begin{datadesc}{altzone}
12245
612be1bb65ff Noted by Guido:
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
116 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
117 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
118 (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
119 \code{daylight} is nonzero.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
120 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
121
16054
4cc9a1ebea62 Make the 'time' argument to the timemodule functions strftime, asctime,
Thomas Wouters <thomas@python.org>
parents: 14784
diff changeset
122 \begin{funcdesc}{asctime}{\optional{tuple}}
9611
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
123 Convert a tuple representing a time as returned by \function{gmtime()}
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
124 or \function{localtime()} to a 24-character string of the following form:
16054
4cc9a1ebea62 Make the 'time' argument to the timemodule functions strftime, asctime,
Thomas Wouters <thomas@python.org>
parents: 14784
diff changeset
125 \code{'Sun Jun 20 23:21:05 1993'}. If \var{tuple} is not provided, the
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 19428
diff changeset
126 current time as returned by \function{localtime()} is used.
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 19428
diff changeset
127 \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
128 newline.}
17589
96f9b86b7b3d Add versioning notes: many of the signatures changed to allow the time
Fred Drake <fdrake@acm.org>
parents: 16443
diff changeset
129 \versionchanged[Allowed \var{tuple} to be omitted]{2.1}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
130 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
131
1807
782509813d57 * Doc/libtime.tex: get rid of references to millitime() and
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
132 \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
133 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
134 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
135 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
136 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
137 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
138 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
139 timing algorithms.
35fec487bcef Revise the description of time.clock() so that it correctly describes the
Fred Drake <fdrake@acm.org>
parents: 18574
diff changeset
140
19376
9e4f739e9a84 Improve Windows time.clock() blurb; was missing return type and unit.
Tim Peters <tim.peters@gmail.com>
parents: 19005
diff changeset
141 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
142 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
143 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
144 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
145 \end{funcdesc}
782509813d57 * Doc/libtime.tex: get rid of references to millitime() and
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
146
16054
4cc9a1ebea62 Make the 'time' argument to the timemodule functions strftime, asctime,
Thomas Wouters <thomas@python.org>
parents: 14784
diff changeset
147 \begin{funcdesc}{ctime}{\optional{secs}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
148 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
149 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
150 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
151 is equivalent to \code{asctime(localtime(\var{secs}))}.
17589
96f9b86b7b3d Add versioning notes: many of the signatures changed to allow the time
Fred Drake <fdrake@acm.org>
parents: 16443
diff changeset
152 \versionchanged[Allowed \var{secs} to be omitted]{2.1}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
153 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
154
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
155 \begin{datadesc}{daylight}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
156 Nonzero if a DST timezone is defined.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
157 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
158
16054
4cc9a1ebea62 Make the 'time' argument to the timemodule functions strftime, asctime,
Thomas Wouters <thomas@python.org>
parents: 14784
diff changeset
159 \begin{funcdesc}{gmtime}{\optional{secs}}
3859
0853166f0d69 Moved description of mktime 9-tuple to top.
Guido van Rossum <guido@python.org>
parents: 3714
diff changeset
160 Convert a time expressed in seconds since the epoch to a time tuple
16054
4cc9a1ebea62 Make the 'time' argument to the timemodule functions strftime, asctime,
Thomas Wouters <thomas@python.org>
parents: 14784
diff changeset
161 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
162 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
163 Fractions of a second are ignored. See above for a description of the
4cc9a1ebea62 Make the 'time' argument to the timemodule functions strftime, asctime,
Thomas Wouters <thomas@python.org>
parents: 14784
diff changeset
164 tuple lay-out.
17589
96f9b86b7b3d Add versioning notes: many of the signatures changed to allow the time
Fred Drake <fdrake@acm.org>
parents: 16443
diff changeset
165 \versionchanged[Allowed \var{secs} to be omitted]{2.1}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
166 \end{funcdesc}
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}{localtime}{\optional{secs}}
7814
a727ae6bfe50 Minor nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
169 Like \function{gmtime()} but converts to local time. The dst flag is
a727ae6bfe50 Minor nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
170 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
171 \versionchanged[Allowed \var{secs} to be omitted]{2.1}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
172 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
173
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
174 \begin{funcdesc}{mktime}{tuple}
9611
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
175 This is the inverse function of \function{localtime()}. Its argument
13384
eacb2e51e169 Correct a markup nit that caused a space to be dropped from the HTML
Fred Drake <fdrake@acm.org>
parents: 13179
diff changeset
176 is the full 9-tuple (since the dst flag is needed; use \code{-1} as
eacb2e51e169 Correct a markup nit that caused a space to be dropped from the HTML
Fred Drake <fdrake@acm.org>
parents: 13179
diff changeset
177 the dst flag if it is unknown) which expresses the time in
9611
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
178 \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
179 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
180 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
181 \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
182 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
183 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
184 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
185
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
186 \begin{funcdesc}{sleep}{secs}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
187 Suspend execution for the given number of seconds. The argument may
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
188 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
189 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
190 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
191 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
192 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
193 the scheduling of other activity in the system.
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
16054
4cc9a1ebea62 Make the 'time' argument to the timemodule functions strftime, asctime,
Thomas Wouters <thomas@python.org>
parents: 14784
diff changeset
196 \begin{funcdesc}{strftime}{format\optional{, tuple}}
9611
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
197 Convert a tuple representing a time as returned by \function{gmtime()}
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
198 or \function{localtime()} to a string as specified by the \var{format}
16054
4cc9a1ebea62 Make the 'time' argument to the timemodule functions strftime, asctime,
Thomas Wouters <thomas@python.org>
parents: 14784
diff changeset
199 argument. If \var{tuple} is not provided, the current time as returned by
4cc9a1ebea62 Make the 'time' argument to the timemodule functions strftime, asctime,
Thomas Wouters <thomas@python.org>
parents: 14784
diff changeset
200 \function{localtime()} is used. \var{format} must be a string.
17589
96f9b86b7b3d Add versioning notes: many of the signatures changed to allow the time
Fred Drake <fdrake@acm.org>
parents: 16443
diff changeset
201 \versionchanged[Allowed \var{tuple} 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
202
9611
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
203 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
204 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
205 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
206 \function{strftime()} result:
3859
0853166f0d69 Moved description of mktime 9-tuple to top.
Guido van Rossum <guido@python.org>
parents: 3714
diff changeset
207
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
208 \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
209 \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
210 \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
211 \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
212 \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
213 \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
214 \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
215 \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
216 \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
217 \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
218 \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
219 \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
220 \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
221 \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
222 \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
223 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
224 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
225 \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
226 \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
227 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
228 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
229 \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
230 \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
231 \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
232 \lineiii{\%Y}{Year with century as a decimal number.}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
233 \lineiii{\%Z}{Time zone name (or by no characters if no time zone exists).}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
234 \lineiii{\%\%}{A literal \character{\%} character.}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
235 \end{tableiii}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
236
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
237 \noindent
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
238 Notes:
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
239
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
240 \begin{description}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
241 \item[(1)]
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
242 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
243 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
244 \end{description}
3859
0853166f0d69 Moved description of mktime 9-tuple to top.
Guido van Rossum <guido@python.org>
parents: 3714
diff changeset
245
16312
b8018145e2a5 Instructive example for strftime(); how to generate RFC822 dates.
Eric S. Raymond <esr@thyrsus.com>
parents: 16054
diff changeset
246 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
247 in the \rfc{2822} Internet email standard.
f70b2d63f309 SourceForge bug #437041:
Fred Drake <fdrake@acm.org>
parents: 17589
diff changeset
248 \footnote{The use of \code{\%Z} is now
f70b2d63f309 SourceForge bug #437041:
Fred Drake <fdrake@acm.org>
parents: 17589
diff changeset
249 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
250 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
251 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
252 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
253 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
254 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
255
b8018145e2a5 Instructive example for strftime(); how to generate RFC822 dates.
Eric S. Raymond <esr@thyrsus.com>
parents: 16054
diff changeset
256 \begin{verbatim}
18341
f70b2d63f309 SourceForge bug #437041:
Fred Drake <fdrake@acm.org>
parents: 17589
diff changeset
257 >>> from time import gmtime, strftime
f70b2d63f309 SourceForge bug #437041:
Fred Drake <fdrake@acm.org>
parents: 17589
diff changeset
258 >>> strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime())
f70b2d63f309 SourceForge bug #437041:
Fred Drake <fdrake@acm.org>
parents: 17589
diff changeset
259 '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
260 \end{verbatim}
b8018145e2a5 Instructive example for strftime(); how to generate RFC822 dates.
Eric S. Raymond <esr@thyrsus.com>
parents: 16054
diff changeset
261
4729
e27fa2a3f526 (libtime.tex): Merged in changes from Tamito Kajiyama.
Fred Drake <fdrake@acm.org>
parents: 4695
diff changeset
262 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
263 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
264
4729
e27fa2a3f526 (libtime.tex): Merged in changes from Tamito Kajiyama.
Fred Drake <fdrake@acm.org>
parents: 4695
diff changeset
265 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
266 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
267 directive in the following order; this is also not portable.
7814
a727ae6bfe50 Minor nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
268 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
269 \end{funcdesc}
a7c97c437191 added strftime
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
270
8471
c89189b0236e Added docs for strptime().
Guido van Rossum <guido@python.org>
parents: 8018
diff changeset
271 \begin{funcdesc}{strptime}{string\optional{, format}}
c89189b0236e Added docs for strptime().
Guido van Rossum <guido@python.org>
parents: 8018
diff changeset
272 Parse a string representing a time according to a format. The return
9611
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
273 value is a tuple as returned by \function{gmtime()} or
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
274 \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
275 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
276 \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
277 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
278 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
279 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
280 \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
281 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
282 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
283 does not provide sufficient information to constrain the result.
0985ddfd442b Added warnings about platform vagaries to the strptime() documentation.
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
284
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 19428
diff changeset
285 \note{This function relies entirely on the underlying
14784
0985ddfd442b Added warnings about platform vagaries to the strptime() documentation.
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
286 platform's C library for the date parsing, and some of these libraries
0985ddfd442b Added warnings about platform vagaries to the strptime() documentation.
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
287 are buggy. There's nothing to be done about this short of a new,
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 19428
diff changeset
288 portable implementation of \cfunction{strptime()}.}
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
289
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
290 Availability: Most modern \UNIX{} systems.
8471
c89189b0236e Added docs for strptime().
Guido van Rossum <guido@python.org>
parents: 8018
diff changeset
291 \end{funcdesc}
c89189b0236e Added docs for strptime().
Guido van Rossum <guido@python.org>
parents: 8018
diff changeset
292
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
293 \begin{funcdesc}{time}{}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
294 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
295 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
296 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
297 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
298 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
299 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
300 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
301
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
302 \begin{datadesc}{timezone}
12245
612be1bb65ff Noted by Guido:
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
303 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
304 (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
305 UK).
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
306 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
307
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
308 \begin{datadesc}{tzname}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
309 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
310 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
311 timezone is defined, the second string should not be used.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
312 \end{datadesc}
3859
0853166f0d69 Moved description of mktime 9-tuple to top.
Guido van Rossum <guido@python.org>
parents: 3714
diff changeset
313
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
314
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
315 \begin{seealso}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
316 \seemodule{locale}{Internationalization services. The locale
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
317 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
318 the functions in the \module{time} module.}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
319 \end{seealso}