| * DST is Daylight Saving Time, an adjustment of the timezone by (usually) one |
| hour during part of the year. DST rules are magic (determined by local law) and |
| can change from year to year. The C library has a table containing the local |
| rules (often it is read from a system file for flexibility) and is the only |
| source of True Wisdom in this respect. |
| |
| * The precision of the various real-time functions may be less than suggested by |
| the units in which their value or argument is expressed. E.g. on most Unix |
n | systems, the clock "ticks" only 50 or 100 times a second, and on the Mac, times |
n | systems, the clock "ticks" only 50 or 100 times a second. |
| are only accurate to whole seconds. |
| |
| * On the other hand, the precision of :func:`time` and :func:`sleep` is better |
| than their Unix equivalents: times are expressed as floating point numbers, |
| :func:`time` returns the most accurate time available (using Unix |
| :cfunc:`gettimeofday` where available), and :func:`sleep` will accept a time |
| with a nonzero fraction (Unix :cfunc:`select` is used to implement this, where |
| available). |
| |
| * The time value as returned by :func:`gmtime`, :func:`localtime`, and |
| :func:`strptime`, and accepted by :func:`asctime`, :func:`mktime` and |
n | :func:`strftime`, is a sequence of 9 integers. The return values of |
n | :func:`strftime`, may be considered as a sequence of 9 integers. The return |
| :func:`gmtime`, :func:`localtime`, and :func:`strptime` also offer attribute |
| values of :func:`gmtime`, :func:`localtime`, and :func:`strptime` also offer |
| names for individual fields. |
| attribute names for individual fields. |
| |
n | +-------+------------------+------------------------------+ |
n | +-------+-------------------+---------------------------------+ |
| | Index | Attribute | Values | |
| | Index | Attribute | Values | |
| +=======+==================+==============================+ |
| +=======+===================+=================================+ |
| | 0 | :attr:`tm_year` | (for example, 1993) | |
| | 0 | :attr:`tm_year` | (for example, 1993) | |
| +-------+------------------+------------------------------+ |
| +-------+-------------------+---------------------------------+ |
| | 1 | :attr:`tm_mon` | range [1,12] | |
| | 1 | :attr:`tm_mon` | range [1,12] | |
| +-------+------------------+------------------------------+ |
| +-------+-------------------+---------------------------------+ |
| | 2 | :attr:`tm_mday` | range [1,31] | |
| | 2 | :attr:`tm_mday` | range [1,31] | |
| +-------+------------------+------------------------------+ |
| +-------+-------------------+---------------------------------+ |
| | 3 | :attr:`tm_hour` | range [0,23] | |
| | 3 | :attr:`tm_hour` | range [0,23] | |
| +-------+------------------+------------------------------+ |
| +-------+-------------------+---------------------------------+ |
| | 4 | :attr:`tm_min` | range [0,59] | |
| | 4 | :attr:`tm_min` | range [0,59] | |
| +-------+------------------+------------------------------+ |
| +-------+-------------------+---------------------------------+ |
| | 5 | :attr:`tm_sec` | range [0,61]; see **(1)** in | |
| | 5 | :attr:`tm_sec` | range [0,61]; see **(1)** in | |
| | | | :func:`strftime` description | |
| | | | :func:`strftime` description | |
| +-------+------------------+------------------------------+ |
| +-------+-------------------+---------------------------------+ |
| | 6 | :attr:`tm_wday` | range [0,6], Monday is 0 | |
| | 6 | :attr:`tm_wday` | range [0,6], Monday is 0 | |
| +-------+------------------+------------------------------+ |
| +-------+-------------------+---------------------------------+ |
| | 7 | :attr:`tm_yday` | range [1,366] | |
| | 7 | :attr:`tm_yday` | range [1,366] | |
| +-------+------------------+------------------------------+ |
| +-------+-------------------+---------------------------------+ |
| | 8 | :attr:`tm_isdst` | 0, 1 or -1; see below | |
| | 8 | :attr:`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 :func:`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 |
| :class:`struct_time`, or having elements of the wrong type, a :exc:`TypeError` |
| is raised. |
| |
| .. versionchanged:: 2.2 |
| The time value sequence was changed from a tuple to a :class:`struct_time`, with |
| the addition of attribute names for the fields. |
| |
n | * Use the following functions to convert between time representations: |
| |
| +-------------------------+-------------------------+-------------------------+ |
| | From | To | Use | |
| +=========================+=========================+=========================+ |
| | seconds since the epoch | :class:`struct_time` in | :func:`gmtime` | |
| | | UTC | | |
| +-------------------------+-------------------------+-------------------------+ |
| | seconds since the epoch | :class:`struct_time` in | :func:`localtime` | |
| | | local time | | |
| +-------------------------+-------------------------+-------------------------+ |
| | :class:`struct_time` in | seconds since the epoch | :func:`calendar.timegm` | |
| | UTC | | | |
| +-------------------------+-------------------------+-------------------------+ |
| | :class:`struct_time` in | seconds since the epoch | :func:`mktime` | |
| | local time | | | |
| +-------------------------+-------------------------+-------------------------+ |
| |
| |
| The module defines the following functions and data items: |
n | |
| |
| .. data:: accept2dyear |
| |
| Boolean value indicating whether two-digit year values will be accepted. This |
| is true by default, but will be set to false if the environment variable |
| :envvar:`PYTHONY2K` has been set to a non-empty string. It may also be modified |
| at run time. |
| |
| 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. |
| |
| |
| .. function:: strptime(string[, format]) |
| |
| Parse a string representing a time according to a format. The return value is |
n | a :class:`struct_time` as returned by :func:`gmtime` or :func:`localtime`. The |
n | a :class:`struct_time` as returned by :func:`gmtime` or :func:`localtime`. |
| |
| *format* parameter uses the same directives as those used by :func:`strftime`; |
| The *format* parameter uses the same directives as those used by |
| it defaults to ``"%a %b %d %H:%M:%S %Y"`` which matches the formatting returned |
| :func:`strftime`; it defaults to ``"%a %b %d %H:%M:%S %Y"`` which matches the |
| by :func:`ctime`. If *string* cannot be parsed according to *format*, |
| formatting returned by :func:`ctime`. If *string* cannot be parsed according to |
| :exc:`ValueError` is raised. If the string to be parsed has excess data after |
| *format*, or if it has excess data after parsing, :exc:`ValueError` is raised. |
| parsing, :exc:`ValueError` is raised. The default values used to fill in any |
| The default values used to fill in any missing data when more accurate values |
| missing data when more accurate values cannot be inferred are ``(1900, 1, 1, 0, |
| cannot be inferred are ``(1900, 1, 1, 0, 0, 0, 0, 1, -1)``. |
| 0, 0, 0, 1, -1)`` . |
| |
| For example: |
| |
| >>> import time |
| >>> time.strptime("30 Nov 00", "%d %b %y") # doctest: +NORMALIZE_WHITESPACE |
| time.struct_time(tm_year=2000, tm_mon=11, tm_mday=30, tm_hour=0, tm_min=0, |
| tm_sec=0, tm_wday=3, tm_yday=335, tm_isdst=-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). |
n | |
| Only the directives specified in the documentation are supported. Because |
| ``strftime()`` is implemented per platform it can sometimes offer more |
| directives than those listed. But ``strptime()`` is independent of any platform |
| and thus does not necessarily support all directives available that are not |
| documented as supported. |
| |
| |
| .. data:: struct_time |
| |
| The type of the time value sequence returned by :func:`gmtime`, |
| :func:`localtime`, and :func:`strptime`. |
| |
| .. versionadded:: 2.2 |
| .. note:: |
| |
| Although in many cases, changing the :envvar:`TZ` environment variable may |
| affect the output of functions like :func:`localtime` without calling |
| :func:`tzset`, this behavior should not be relied on. |
| |
| The :envvar:`TZ` environment variable should contain no whitespace. |
| |
n | The standard format of the :envvar:`TZ` environment variable is: (whitespace |
n | The standard format of the :envvar:`TZ` environment variable is (whitespace |
| added for clarity) |
| added for clarity):: |
| |
n | std offset [dst [offset |
n | std offset [dst [offset [,start[/time], end[/time]]]] |
| [,start[/time], end[/time]]]] |
| |
n | Where: |
n | Where the components are: |
| |
n | std and dst |
n | ``std`` and ``dst`` |
| Three or more alphanumerics giving the timezone abbreviations. These will be |
| propagated into time.tzname |
| |
n | offset |
n | ``offset`` |
| The offset has the form: ± hh[:mm[:ss]]. This indicates the value added the |
| The offset has the form: ``± hh[:mm[:ss]]``. This indicates the value |
| local time to arrive at UTC. If preceded by a '-', the timezone is east of the |
| added the local time to arrive at UTC. If preceded by a '-', the timezone |
| Prime Meridian; otherwise, it is west. If no offset follows dst, summer time is |
| is east of the Prime Meridian; otherwise, it is west. If no offset follows |
| assumed to be one hour ahead of standard time. |
| dst, summer time is assumed to be one hour ahead of standard time. |
| |
n | start[/time |
n | ``start[/time], end[/time]`` |
| ,end[/time]] Indicates when to change to and back from DST. The format of the |
| Indicates when to change to and back from DST. The format of the |
| start and end dates are one of the following: |
| |
n | J*n* |
n | :samp:`J{n}` |
| The Julian day *n* (1 <= *n* <= 365). Leap days are not counted, so in all |
| The Julian day *n* (1 <= *n* <= 365). Leap days are not counted, so in |
| years February 28 is day 59 and March 1 is day 60. |
| all years February 28 is day 59 and March 1 is day 60. |
| |
n | *n* |
n | :samp:`{n}` |
| The zero-based Julian day (0 <= *n* <= 365). Leap days are counted, and it is |
| The zero-based Julian day (0 <= *n* <= 365). Leap days are counted, and |
| possible to refer to February 29. |
| it is possible to refer to February 29. |
| |
n | M*m*.*n*.*d* |
n | :samp:`M{m}.{n}.{d}` |
| The *d*'th day (0 <= *d* <= 6) or week *n* of month *m* of the year (1 <= *n* |
| The *d*'th day (0 <= *d* <= 6) or week *n* of month *m* of the year (1 |
| <= 5, 1 <= *m* <= 12, where week 5 means "the last *d* day in month *m*" which |
| <= *n* <= 5, 1 <= *m* <= 12, where week 5 means "the last *d* day in |
| may occur in either the fourth or the fifth week). Week 1 is the first week in |
| month *m*" which may occur in either the fourth or the fifth |
| which the *d*'th day occurs. Day zero is Sunday. |
| week). Week 1 is the first week in which the *d*'th day occurs. Day |
| zero is Sunday. |
| |
t | time has the same format as offset except that no leading sign ('-' or '+') is |
t | ``time`` has the same format as ``offset`` except that no leading sign |
| allowed. The default, if time is not given, is 02:00:00. |
| ('-' 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' |