This module provides various time-related functions. It is always available, but not all functions are available on all platforms.
An explanation of some terminology and conventions is in order.
gmtime(0)
.
accept2dyear
is a
non-zero integer; this variable is initialized to 1
unless the
environment variable PYTHONY2K is set to a non-empty string,
in which case it is initialized to 0
. Thus, you can set
PYTHONY2K to a non-empty string in the environment to require 4-digit
years for all year input. When 2-digit years are accepted, they are
converted according to the POSIX or X/Open standard: values 69-99
are mapped to 1969-1999, and values 0-68 are mapped to 2000-2068.
Values 100-1899 are always illegal. Note that this is new as of
Python 1.5.2(a2); earlier versions, up to Python 1.5.1 and 1.5.2a1,
would add 1900 to year values below 1900.
Index | Field | Values |
---|---|---|
0 |
year | (for example, 1993) |
1 |
month | range [1,12] |
2 |
day | range [1,31] |
3 |
hour | range [0,23] |
4 |
minute | range [0,59] |
5 |
second | range [0,61]; see (1) in strftime() description |
6 |
weekday | range [0,6], Monday is 0 |
7 |
Julian day | range [1,366] |
8 |
daylight savings flag | 0, 1 or -1; see below |
Note that unlike the C structure, the month value is a
range of 1-12, not 0-11. A year value will be handled as described
under ``Year 2000 (Y2K) issues'' above. A -1
argument as
daylight savings flag, passed to mktime() will usually
result in the correct daylight savings state to be filled in.
When a tuple with an incorrect length is passed to a function expecting a time tuple, or having elements of the wrong type, a TypeError is raised.
The module defines the following functions and data items:
daylight
is nonzero.
'Sun Jun 20 23:21:05 1993'
. If tuple is not provided, the
current time as returned by localtime() is used.
Note:
Unlike the C function of the same name, there is no trailing
newline.
Changed in version 2.1:
Allowed tuple to be omitted.
On Windows, this function returns wall-clock seconds elapsed since the first call to this function, as a floating point number, based on the Win32 function QueryPerformanceCounter(). The resolution is typically better than one microsecond.
ctime(secs)
is equivalent to asctime(localtime(secs))
.
Changed in version 2.1:
Allowed secs to be omitted.
1
when DST applies to the given time.
Changed in version 2.1:
Allowed secs to be omitted.
-1
as
the dst flag if it is unknown) which expresses the time in
local time, not UTC. It returns a floating point number, for
compatibility with time(). If the input value cannot be
represented as a valid time, either OverflowError or
ValueError will be raised (which depends on whether the
invalid value is caught by Python or the underlying C libraries). The
earliest date for which it can generate a time is platform-dependent.
The following directives can be embedded in the format string. They are shown without the optional field width and precision specification, and are replaced by the indicated characters in the strftime() result:
Directive | Meaning | Notes |
---|---|---|
%a |
Locale's abbreviated weekday name. | |
%A |
Locale's full weekday name. | |
%b |
Locale's abbreviated month name. | |
%B |
Locale's full month name. | |
%c |
Locale's appropriate date and time representation. | |
%d |
Day of the month as a decimal number [01,31]. | |
%H |
Hour (24-hour clock) as a decimal number [00,23]. | |
%I |
Hour (12-hour clock) as a decimal number [01,12]. | |
%j |
Day of the year as a decimal number [001,366]. | |
%m |
Month as a decimal number [01,12]. | |
%M |
Minute as a decimal number [00,59]. | |
%p |
Locale's equivalent of either AM or PM. | |
%S |
Second as a decimal number [00,61]. | (1) |
%U |
Week number of the year (Sunday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Sunday are considered to be in week 0. | |
%w |
Weekday as a decimal number [0(Sunday),6]. | |
%W |
Week number of the year (Monday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Sunday are considered to be in week 0. | |
%x |
Locale's appropriate date representation. | |
%X |
Locale's appropriate time representation. | |
%y |
Year without century as a decimal number [00,99]. | |
%Y |
Year with century as a decimal number. | |
%Z |
Time zone name (or by no characters if no time zone exists). | |
%% |
A literal "%" character. |
Notes:
0
to 61
; this accounts for leap
seconds and the (very rare) double leap seconds.
Here is an example, a format for dates compatible with that specified in the RFC 2822 Internet email standard. 6.1
>>> from time import gmtime, strftime >>> strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime()) 'Thu, 28 Jun 2001 14:17:15 +0000'
Additional directives may be supported on certain platforms, but only the ones listed here have a meaning standardized by ANSI C.
On some platforms, an optional field width and precision
specification can immediately follow the initial "%" of a
directive in the following order; this is also not portable.
The field width is normally 2 except for %j
where it is 3.
"%a %b %d %H:%M:%S %Y"
which matches the formatting
returned by ctime(). The same platform caveats apply; see
the local Unix documentation for restrictions or additional
supported directives. If string cannot be parsed according to
format, ValueError is raised. Values which are not
provided as part of the input string are filled in with default
values; the specific values are platform-dependent as the XPG standard
does not provide sufficient information to constrain the result.
Note: This function relies entirely on the underlying platform's C library for the date parsing, and some of these libraries are buggy. There's nothing to be done about this short of a new, portable implementation of strptime().
Availability: Most modern Unix systems.
See Also:
%Z
is now
deprecated, but the %z
escape that expands to the preferred
hour/minute offset is not supported by all ANSI C libraries. Also,
a strict reading of the original 1982 RFC 822 standard calls for
a two-digit year (%y rather than %Y), but practice moved to
4-digit years long before the year 2000. The 4-digit year has
been mandated by RFC 2822, which obsoletes RFC 822.