Ignore:
Timestamp:
Mar 19, 2014, 11:31:01 PM (11 years ago)
Author:
dmik
Message:

python: Merge vendor 2.7.6 to trunk.

Location:
python/trunk
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • python/trunk

  • python/trunk/Doc/library/time.rst

    r2 r391  
    1818An explanation of some terminology and conventions is in order.
    1919
    20   .. index:: single: epoch
     20.. index:: single: epoch
    2121
    2222* The :dfn:`epoch` is the point where the time starts.  On January 1st of that
    … …  
    2424  1970.  To find out what the epoch is, look at ``gmtime(0)``.
    2525
    26   .. index:: single: Year 2038
     26.. index:: single: Year 2038
    2727
    2828* The functions in this module do not handle dates and times before the epoch or
    … …  
    3030  library; for Unix, it is typically in 2038.
    3131
    32   .. index::
    33      single: Year 2000
    34      single: Y2K
     32.. index::
     33   single: Year 2000
     34   single: Y2K
     35
     36.. _time-y2kissues:
    3537
    3638* **Year 2000 (Y2K) issues**:  Python depends on the platform's C library, which
    … …  
    4951  1.5.1 and 1.5.2a1, would add 1900 to year values below 1900.
    5052
    51   .. index::
    52      single: UTC
    53      single: Coordinated Universal Time
    54      single: Greenwich Mean Time
     53.. index::
     54   single: UTC
     55   single: Coordinated Universal Time
     56   single: Greenwich Mean Time
    5557
    5658* UTC is Coordinated Universal Time (formerly known as Greenwich Mean Time, or
    … …  
    5860  French.
    5961
    60   .. index:: single: Daylight Saving Time
     62.. index:: single: Daylight Saving Time
    6163
    6264* DST is Daylight Saving Time, an adjustment of the timezone by (usually) one
    … …  
    7072  systems, the clock "ticks" only 50 or 100 times a second.
    7173
    72 * On the other hand, the precision of :func:`time` and :func:`sleep` is better
     74* On the other hand, the precision of :func:`.time` and :func:`sleep` is better
    7375  than their Unix equivalents: times are expressed as floating point numbers,
    74   :func:`time` returns the most accurate time available (using Unix
    75   :cfunc:`gettimeofday` where available), and :func:`sleep` will accept a time
    76   with a nonzero fraction (Unix :cfunc:`select` is used to implement this, where
     76  :func:`.time` returns the most accurate time available (using Unix
     77  :c:func:`gettimeofday` where available), and :func:`sleep` will accept a time
     78  with a nonzero fraction (Unix :c:func:`select` is used to implement this, where
    7779  available).
    7880
    … …  
    8385  attribute names for individual fields.
    8486
    85   +-------+-------------------+---------------------------------+
    86   | Index | Attribute         | Values                          |
    87   +=======+===================+=================================+
    88   | 0     | :attr:`tm_year`   | (for example, 1993)             |
    89   +-------+-------------------+---------------------------------+
    90   | 1     | :attr:`tm_mon`    | range [1,12]                    |
    91   +-------+-------------------+---------------------------------+
    92   | 2     | :attr:`tm_mday`   | range [1,31]                    |
    93   +-------+-------------------+---------------------------------+
    94   | 3     | :attr:`tm_hour`   | range [0,23]                    |
    95   +-------+-------------------+---------------------------------+
    96   | 4     | :attr:`tm_min`    | range [0,59]                    |
    97   +-------+-------------------+---------------------------------+
    98   | 5     | :attr:`tm_sec`    | range [0,61]; see **(1)** in    |
    99   |       |                   | :func:`strftime` description    |
    100   +-------+-------------------+---------------------------------+
    101   | 6     | :attr:`tm_wday`   | range [0,6], Monday is 0        |
    102   +-------+-------------------+---------------------------------+
    103   | 7     | :attr:`tm_yday`   | range [1,366]                   |
    104   +-------+-------------------+---------------------------------+
    105   | 8     | :attr:`tm_isdst`  | 0, 1 or -1; see below           |
    106   +-------+-------------------+---------------------------------+
    107 
    108   Note that unlike the C structure, the month value is a range of 1-12, not 0-11.
    109   A year value will be handled as described under "Year 2000 (Y2K) issues" above.
    110   A ``-1`` argument as the daylight savings flag, passed to :func:`mktime` will
    111   usually result in the correct daylight savings state to be filled in.
    112 
    113   When a tuple with an incorrect length is passed to a function expecting a
    114   :class:`struct_time`, or having elements of the wrong type, a :exc:`TypeError`
    115   is raised.
     87  See :class:`struct_time` for a description of these objects.
    11688
    11789  .. versionchanged:: 2.2
    … …  
    185157   On Windows, this function returns wall-clock seconds elapsed since the first
    186158   call to this function, as a floating point number, based on the Win32 function
    187    :cfunc:`QueryPerformanceCounter`. The resolution is typically better than one
     159   :c:func:`QueryPerformanceCounter`. The resolution is typically better than one
    188160   microsecond.
    189161
    … …  
    193165   Convert a time expressed in seconds since the epoch to a string representing
    194166   local time. If *secs* is not provided or :const:`None`, the current time as
    195    returned by :func:`time` is used.  ``ctime(secs)`` is equivalent to
     167   returned by :func:`.time` is used.  ``ctime(secs)`` is equivalent to
    196168   ``asctime(localtime(secs))``. Locale information is not used by :func:`ctime`.
    197169
    … …  
    212184   Convert a time expressed in seconds since the epoch to a :class:`struct_time` in
    213185   UTC in which the dst flag is always zero.  If *secs* is not provided or
    214    :const:`None`, the current time as returned by :func:`time` is used.  Fractions
     186   :const:`None`, the current time as returned by :func:`.time` is used.  Fractions
    215187   of a second are ignored.  See above for a description of the
    216188   :class:`struct_time` object. See :func:`calendar.timegm` for the inverse of this
    … …  
    227199
    228200   Like :func:`gmtime` but converts to local time.  If *secs* is not provided or
    229    :const:`None`, the current time as returned by :func:`time` is used.  The dst
     201   :const:`None`, the current time as returned by :func:`.time` is used.  The dst
    230202   flag is set to ``1`` when DST applies to the given time.
    231203
    … …  
    242214   :class:`struct_time` or full 9-tuple (since the dst flag is needed; use ``-1``
    243215   as the dst flag if it is unknown) which expresses the time in *local* time, not
    244    UTC.  It returns a floating point number, for compatibility with :func:`time`.
     216   UTC.  It returns a floating point number, for compatibility with :func:`.time`.
    245217   If the input value cannot be represented as a valid time, either
    246218   :exc:`OverflowError` or :exc:`ValueError` will be raised (which depends on
    … …  
    379351      'Thu, 28 Jun 2001 14:17:15 +0000'
    380352
    381    Additional directives may be supported on certain platforms, but only the ones
    382    listed here have a meaning standardized by ANSI C.
     353   Additional directives may be supported on certain platforms, but only the
     354   ones listed here have a meaning standardized by ANSI C.  To see the full set
     355   of format codes supported on your platform, consult the :manpage:`strftime(3)`
     356   documentation.
    383357
    384358   On some platforms, an optional field width and precision specification can
    … …  
    419393
    420394
    421 .. data:: struct_time
     395.. class:: struct_time
    422396
    423397   The type of the time value sequence returned by :func:`gmtime`,
    424    :func:`localtime`, and :func:`strptime`.
     398   :func:`localtime`, and :func:`strptime`.  It is an object with a :term:`named
     399   tuple` interface: values can be accessed by index and by attribute name.  The
     400   following values are present:
     401
     402   +-------+-------------------+---------------------------------+
     403   | Index | Attribute         | Values                          |
     404   +=======+===================+=================================+
     405   | 0     | :attr:`tm_year`   | (for example, 1993)             |
     406   +-------+-------------------+---------------------------------+
     407   | 1     | :attr:`tm_mon`    | range [1, 12]                   |
     408   +-------+-------------------+---------------------------------+
     409   | 2     | :attr:`tm_mday`   | range [1, 31]                   |
     410   +-------+-------------------+---------------------------------+
     411   | 3     | :attr:`tm_hour`   | range [0, 23]                   |
     412   +-------+-------------------+---------------------------------+
     413   | 4     | :attr:`tm_min`    | range [0, 59]                   |
     414   +-------+-------------------+---------------------------------+
     415   | 5     | :attr:`tm_sec`    | range [0, 61]; see **(2)** in   |
     416   |       |                   | :func:`strftime` description    |
     417   +-------+-------------------+---------------------------------+
     418   | 6     | :attr:`tm_wday`   | range [0, 6], Monday is 0       |
     419   +-------+-------------------+---------------------------------+
     420   | 7     | :attr:`tm_yday`   | range [1, 366]                  |
     421   +-------+-------------------+---------------------------------+
     422   | 8     | :attr:`tm_isdst`  | 0, 1 or -1; see below           |
     423   +-------+-------------------+---------------------------------+
    425424
    426425   .. versionadded:: 2.2
    427426
     427   Note that unlike the C structure, the month value is a range of [1, 12], not
     428   [0, 11].  A year value will be handled as described under :ref:`Year 2000
     429   (Y2K) issues <time-y2kissues>` above.  A ``-1`` argument as the daylight
     430   savings flag, passed to :func:`mktime` will usually result in the correct
     431   daylight savings state to be filled in.
     432
     433   When a tuple with an incorrect length is passed to a function expecting a
     434   :class:`struct_time`, or having elements of the wrong type, a
     435   :exc:`TypeError` is raised.
     436
    428437
    429438.. function:: time()
    430439
    431    Return the time as a floating point number expressed in seconds since the epoch,
    432    in UTC.  Note that even though the time is always returned as a floating point
     440   Return the time in seconds since the epoch as a floating point number.
     441   Note that even though the time is always returned as a floating point
    433442   number, not all systems provide time with a better precision than 1 second.
    434443   While this function normally returns non-decreasing values, it can return a
    … …  
    541550
    542551   Module :mod:`locale`
    543       Internationalization services.  The locale settings can affect the return values
    544       for some of  the functions in the :mod:`time` module.
     552      Internationalization services.  The locale setting affects the interpretation
     553      of many format specifiers in :func:`strftime` and :func:`strptime`.
    545554
    546555   Module :mod:`calendar`
    547       General calendar-related functions.   :func:`timegm` is the inverse of
    548       :func:`gmtime` from this module.
     556      General calendar-related functions.   :func:`~calendar.timegm` is the
     557      inverse of :func:`gmtime` from this module.
    549558
    550559.. rubric:: Footnotes
    … …  
    554563   strict reading of the original 1982 :rfc:`822` standard calls for a two-digit
    555564   year (%y rather than %Y), but practice moved to 4-digit years long before the
    556    year 2000.  The 4-digit year has been mandated by :rfc:`2822`, which obsoletes
    557    :rfc:`822`.
    558 
     565   year 2000.  After that, :rfc:`822` became obsolete and the 4-digit year has
     566   been first recommended by :rfc:`1123` and then mandated by :rfc:`2822`.
     567
Note: See TracChangeset for help on using the changeset viewer.