This module provides various time-related functions. It is always available, but not all functions are available on all platforms. Most of the functions defined in this module call platform C library functions with the same name. It may sometimes be helpful to consult the platform documentation, because the semantics of these functions varies among 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 | Attribute | Values |
---|---|---|
0 |
tm_year | (for example, 1993) |
1 |
tm_mon | range [1,12] |
2 |
tm_mday | range [1,31] |
3 |
tm_hour | range [0,23] |
4 |
tm_min | range [0,59] |
5 |
tm_sec | range [0,61]; see (1) in strftime() description |
6 |
tm_wday | range [0,6], Monday is 0 |
7 |
tm_yday | range [1,366] |
8 |
tm_isdst | 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 the
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 struct_time, or having elements of the wrong type, a TypeError is raised.
Changed in version 2.2: The time value sequence was changed from a tuple to a struct_time, with the addition of attribute names for the fields.
The module defines the following functions and data items:
daylight
is nonzero.
[t]) |
'Sun Jun 20 23:21:05 1993'
. If t is not provided, the
current time as returned by localtime() is used.
Locale information is not used by asctime().
Note:
Unlike the C function of the same name, there is no trailing
newline.
Changed in version 2.1:
Allowed t 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.
[secs]) |
ctime(secs)
is equivalent to
asctime(localtime(secs))
.
Locale information is not used by ctime().
Changed in version 2.1:
Allowed secs to be omitted.
Changed in version 2.4:
If secs is None, the current time is
used.
[secs]) |
[secs]) |
1
when DST
applies to the given time.
Changed in version 2.1:
Allowed secs to be omitted.
Changed in version 2.4:
If secs is None, the current time is
used.
t) |
-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.
secs) |
format[, t]) |
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. | (1) |
%S |
Second as a decimal number [00,61]. | (2) |
%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. | (3) |
%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 Monday are considered to be in week 0. | (3) |
%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 (no characters if no time zone exists). | |
%% |
A literal "%" character. |
Notes:
%p
directive only affects the output hour field if the %I
directive
is used to parse the hour.
0
to 61
; this accounts for leap
seconds and the (very rare) double leap seconds.
%U
and %W
are only used in calculations when the day of the week and the year are
specified.
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.
string[, format]) |
"%a %b %d %H:%M:%S %Y"
which matches the formatting
returned by ctime(). If string cannot be parsed
according to format, ValueError is raised. If the
string to be parsed has excess data after parsing,
ValueError is raised. The default values used to fill in
any missing data are (1900, 1, 1, 0, 0, 0, 0, 1, -1)
.
Support for the %Z
directive is based on the values contained in
tzname
and whether daylight
is true. Because of this,
it is platform-specific except for recognizing UTC and GMT which are
always known (and are considered to be non-daylight savings
timezones).
) |
) |
Availability: Unix.
The TZ environment variable should contain no whitespace.
The standard format of the TZ environment variable is: (whitespace added for clarity)
Where:
time has the same format as offset except that no leading sign ('-' or '+') is allowed. The default, if time is not given, is 02:00:00.
>>> os.environ['TZ'] = 'EST+05EDT,M4.1.0,M10.5.0' >>> time.tzset() >>> time.strftime('%X %x %Z') '02:07:36 05/08/03 EDT' >>> os.environ['TZ'] = 'AEST-10AEDT-11,M10.5.0,M3.5.0' >>> time.tzset() >>> time.strftime('%X %x %Z') '16:08:12 05/08/03 AEST'
On many Unix systems (including *BSD, Linux, Solaris, and Darwin), it
is more convenient to use the system's zoneinfo (tzfile(5))
database to specify the timezone rules. To do this, set the
TZ environment variable to the path of the required timezone
datafile, relative to the root of the systems 'zoneinfo' timezone database,
usually located at /usr/share/zoneinfo. For example,
'US/Eastern'
, 'Australia/Melbourne'
, 'Egypt'
or
'Europe/Amsterdam'
.
>>> os.environ['TZ'] = 'US/Eastern' >>> time.tzset() >>> time.tzname ('EST', 'EDT') >>> os.environ['TZ'] = 'Egypt' >>> time.tzset() >>> time.tzname ('EET', 'EEST')
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.