Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libtime.tex @ 16413:8819867f14ef legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Patch derived from Trent's 101162: a Python/C API testing framework. STILL NEEDS UNIX BUILD CHANGES.
author Tim Peters <tim.peters@gmail.com>
date Fri, 02 Feb 2001 05:57:15 +0000
parents b8018145e2a5
children ce9850051120
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
bdf57c84df6a Shift index entries around a little so the HTML doesn't have weird spacing.
Fred Drake <fdrake@acm.org>
parents: 7877
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
10881
838cb34abb79 Move some \index entries around so we can avoid using empty comments;
Fred Drake <fdrake@acm.org>
parents: 10243
diff changeset
25 determined by the C library; for \UNIX{}, it is typically in
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
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
76
8478
4ba587aa8a98 Added notes about epochs, the year 2038, and a small Y2K disclaimer
Guido van Rossum <guido@python.org>
parents: 8471
diff changeset
77 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
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()},
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
80 is a tuple of 9 integers:
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
81
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
82 \begin{tableiii}{r|l|l}{textrm}{Index}{Field}{Values}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
83 \lineiii{0}{year}{(e.g.\ 1993)}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
84 \lineiii{1}{month}{range [1,12]}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
85 \lineiii{2}{day}{range [1,31]}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
86 \lineiii{3}{hour}{range [0,23]}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
87 \lineiii{4}{minute}{range [0,59]}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
88 \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
89 \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
90 \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
91 \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
92 \end{tableiii}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
93
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
94 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
95 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
96 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
97 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
98 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
99
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
100 \end{itemize}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
101
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
102 The module defines the following functions and data items:
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
103
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
104
9911
20d98ca3d32f Fix second description of handling 2-digit years (last item in
Fred Drake <fdrake@acm.org>
parents: 9611
diff changeset
105 \begin{datadesc}{accept2dyear}
20d98ca3d32f Fix second description of handling 2-digit years (last item in
Fred Drake <fdrake@acm.org>
parents: 9611
diff changeset
106 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
107 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
108 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
109 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
110 \end{datadesc}
20d98ca3d32f Fix second description of handling 2-digit years (last item in
Fred Drake <fdrake@acm.org>
parents: 9611
diff changeset
111
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
112 \begin{datadesc}{altzone}
12245
612be1bb65ff Noted by Guido:
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
113 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
114 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
115 (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
116 \code{daylight} is nonzero.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
117 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
118
16054
4cc9a1ebea62 Make the 'time' argument to the timemodule functions strftime, asctime,
Thomas Wouters <thomas@python.org>
parents: 14784
diff changeset
119 \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
120 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
121 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
122 \code{'Sun Jun 20 23:21:05 1993'}. If \var{tuple} is not provided, the
4cc9a1ebea62 Make the 'time' argument to the timemodule functions strftime, asctime,
Thomas Wouters <thomas@python.org>
parents: 14784
diff changeset
123 current time as returned by \function{localtime()} is used. Note: unlike
4cc9a1ebea62 Make the 'time' argument to the timemodule functions strftime, asctime,
Thomas Wouters <thomas@python.org>
parents: 14784
diff changeset
124 the C function of the same name, there is no trailing newline.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
125 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
126
1807
782509813d57 * Doc/libtime.tex: get rid of references to millitime() and
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
127 \begin{funcdesc}{clock}{}
782509813d57 * Doc/libtime.tex: get rid of references to millitime() and
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
128 Return the current CPU 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
129 seconds. The precision, and in fact the very definition of the meaning
10881
838cb34abb79 Move some \index entries around so we can avoid using empty comments;
Fred Drake <fdrake@acm.org>
parents: 10243
diff changeset
130 of ``CPU time''\index{CPU time}, depends on that of the C function
7814
a727ae6bfe50 Minor nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
131 of the same name, but in any case, this is the function to use for
a727ae6bfe50 Minor nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
132 benchmarking\index{benchmarking} Python or timing algorithms.
1807
782509813d57 * Doc/libtime.tex: get rid of references to millitime() and
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
133 \end{funcdesc}
782509813d57 * Doc/libtime.tex: get rid of references to millitime() and
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
134
16054
4cc9a1ebea62 Make the 'time' argument to the timemodule functions strftime, asctime,
Thomas Wouters <thomas@python.org>
parents: 14784
diff changeset
135 \begin{funcdesc}{ctime}{\optional{secs}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
136 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
137 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
138 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
139 is equivalent to \code{asctime(localtime(\var{secs}))}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
140 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
141
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
142 \begin{datadesc}{daylight}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
143 Nonzero if a DST timezone is defined.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
144 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
145
16054
4cc9a1ebea62 Make the 'time' argument to the timemodule functions strftime, asctime,
Thomas Wouters <thomas@python.org>
parents: 14784
diff changeset
146 \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
147 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
148 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
149 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
150 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
151 tuple lay-out.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
152 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
153
16054
4cc9a1ebea62 Make the 'time' argument to the timemodule functions strftime, asctime,
Thomas Wouters <thomas@python.org>
parents: 14784
diff changeset
154 \begin{funcdesc}{localtime}{\optional{secs}}
7814
a727ae6bfe50 Minor nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
155 Like \function{gmtime()} but converts to local time. The dst flag is
a727ae6bfe50 Minor nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
156 set to \code{1} when DST applies to the given time.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
157 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
158
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
159 \begin{funcdesc}{mktime}{tuple}
9611
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
160 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
161 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
162 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
163 \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
164 compatibility with \function{time()}. If the input value cannot be
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
165 represented as a valid time, \exception{OverflowError} is raised.
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
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
168 \begin{funcdesc}{sleep}{secs}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
169 Suspend execution for the given number of seconds. The argument may
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
170 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
171 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
172 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
173 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
174 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
175 the scheduling of other activity in the system.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
176 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
177
16054
4cc9a1ebea62 Make the 'time' argument to the timemodule functions strftime, asctime,
Thomas Wouters <thomas@python.org>
parents: 14784
diff changeset
178 \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
179 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
180 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
181 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
182 \function{localtime()} is used. \var{format} must be a string.
3859
0853166f0d69 Moved description of mktime 9-tuple to top.
Guido van Rossum <guido@python.org>
parents: 3714
diff changeset
183
9611
570fed4ab8da Update the descriptions of strftime() and strptime() to avoid
Fred Drake <fdrake@acm.org>
parents: 9040
diff changeset
184 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
185 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
186 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
187 \function{strftime()} result:
3859
0853166f0d69 Moved description of mktime 9-tuple to top.
Guido van Rossum <guido@python.org>
parents: 3714
diff changeset
188
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
189 \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
190 \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
191 \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
192 \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
193 \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
194 \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
195 \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
196 \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
197 \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
198 \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
199 \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
200 \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
201 \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
202 \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
203 \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
204 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
205 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
206 \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
207 \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
208 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
209 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
210 \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
211 \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
212 \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
213 \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
214 \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
215 \lineiii{\%\%}{A literal \character{\%} character.}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
216 \end{tableiii}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
217
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
218 \noindent
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
219 Notes:
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
220
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
221 \begin{description}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
222 \item[(1)]
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
223 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
224 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
225 \end{description}
3859
0853166f0d69 Moved description of mktime 9-tuple to top.
Guido van Rossum <guido@python.org>
parents: 3714
diff changeset
226
16312
b8018145e2a5 Instructive example for strftime(); how to generate RFC822 dates.
Eric S. Raymond <esr@thyrsus.com>
parents: 16054
diff changeset
227 Here is an example, a format for dates compatible with that specified
b8018145e2a5 Instructive example for strftime(); how to generate RFC822 dates.
Eric S. Raymond <esr@thyrsus.com>
parents: 16054
diff changeset
228 in the \rfc{822} Internet email standard.
b8018145e2a5 Instructive example for strftime(); how to generate RFC822 dates.
Eric S. Raymond <esr@thyrsus.com>
parents: 16054
diff changeset
229 \footnote{The use of \%Z is now
b8018145e2a5 Instructive example for strftime(); how to generate RFC822 dates.
Eric S. Raymond <esr@thyrsus.com>
parents: 16054
diff changeset
230 deprecated, but the \%z escape that expands to the preferred
b8018145e2a5 Instructive example for strftime(); how to generate RFC822 dates.
Eric S. Raymond <esr@thyrsus.com>
parents: 16054
diff changeset
231 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
232 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
233 a two-digit year (\%y rather than \%Y), but practice moved to
b8018145e2a5 Instructive example for strftime(); how to generate RFC822 dates.
Eric S. Raymond <esr@thyrsus.com>
parents: 16054
diff changeset
234 4-digit years long before the year 2000.}
b8018145e2a5 Instructive example for strftime(); how to generate RFC822 dates.
Eric S. Raymond <esr@thyrsus.com>
parents: 16054
diff changeset
235
b8018145e2a5 Instructive example for strftime(); how to generate RFC822 dates.
Eric S. Raymond <esr@thyrsus.com>
parents: 16054
diff changeset
236 \begin{verbatim}
b8018145e2a5 Instructive example for strftime(); how to generate RFC822 dates.
Eric S. Raymond <esr@thyrsus.com>
parents: 16054
diff changeset
237 >>> from time import *
b8018145e2a5 Instructive example for strftime(); how to generate RFC822 dates.
Eric S. Raymond <esr@thyrsus.com>
parents: 16054
diff changeset
238 >>> strftime("\%a, \%d \%b \%Y \%H:\%M:\%S \%Z", localtime())
b8018145e2a5 Instructive example for strftime(); how to generate RFC822 dates.
Eric S. Raymond <esr@thyrsus.com>
parents: 16054
diff changeset
239 'Sat, 27 Jan 2001 05:15:05 EST'
b8018145e2a5 Instructive example for strftime(); how to generate RFC822 dates.
Eric S. Raymond <esr@thyrsus.com>
parents: 16054
diff changeset
240 >>>
b8018145e2a5 Instructive example for strftime(); how to generate RFC822 dates.
Eric S. Raymond <esr@thyrsus.com>
parents: 16054
diff changeset
241 \end{verbatim}
b8018145e2a5 Instructive example for strftime(); how to generate RFC822 dates.
Eric S. Raymond <esr@thyrsus.com>
parents: 16054
diff changeset
242
4729
e27fa2a3f526 (libtime.tex): Merged in changes from Tamito Kajiyama.
Fred Drake <fdrake@acm.org>
parents: 4695
diff changeset
243 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
244 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
245
4729
e27fa2a3f526 (libtime.tex): Merged in changes from Tamito Kajiyama.
Fred Drake <fdrake@acm.org>
parents: 4695
diff changeset
246 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
247 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
248 directive in the following order; this is also not portable.
7814
a727ae6bfe50 Minor nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
249 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
250 \end{funcdesc}
a7c97c437191 added strftime
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
251
8471
c89189b0236e Added docs for strptime().
Guido van Rossum <guido@python.org>
parents: 8018
diff changeset
252 \begin{funcdesc}{strptime}{string\optional{, format}}
c89189b0236e Added docs for strptime().
Guido van Rossum <guido@python.org>
parents: 8018
diff changeset
253 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
254 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
255 \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
256 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
257 \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
258 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
259 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
260 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
261 \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
262 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
263 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
264 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
265
0985ddfd442b Added warnings about platform vagaries to the strptime() documentation.
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
266 \strong{Note:} This function relies entirely on the underlying
0985ddfd442b Added warnings about platform vagaries to the strptime() documentation.
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
267 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
268 are buggy. There's nothing to be done about this short of a new,
0985ddfd442b Added warnings about platform vagaries to the strptime() documentation.
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
269 portable implementation of \cfunction{strptime()}.
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
270
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
271 Availability: Most modern \UNIX{} systems.
8471
c89189b0236e Added docs for strptime().
Guido van Rossum <guido@python.org>
parents: 8018
diff changeset
272 \end{funcdesc}
c89189b0236e Added docs for strptime().
Guido van Rossum <guido@python.org>
parents: 8018
diff changeset
273
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
274 \begin{funcdesc}{time}{}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
275 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
276 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
277 as a floating point number, not all systems provide time with a better
1807
782509813d57 * Doc/libtime.tex: get rid of references to millitime() and
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
278 precision than 1 second.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
279 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
280
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
281 \begin{datadesc}{timezone}
12245
612be1bb65ff Noted by Guido:
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
282 The offset of the local (non-DST) timezone, in seconds west of UTC
612be1bb65ff Noted by Guido:
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
283 (i.e. negative in most of Western Europe, positive in the US, zero in
612be1bb65ff Noted by Guido:
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
284 the UK).
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
285 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
286
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
287 \begin{datadesc}{tzname}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
288 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
289 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
290 timezone is defined, the second string should not be used.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
291 \end{datadesc}
3859
0853166f0d69 Moved description of mktime 9-tuple to top.
Guido van Rossum <guido@python.org>
parents: 3714
diff changeset
292
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
293
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
294 \begin{seealso}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
295 \seemodule{locale}{Internationalization services. The locale
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11207
diff changeset
296 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
297 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
298 \end{seealso}