Move the 3k reST doc tree in place.
diff --git a/Doc/library/time.rst b/Doc/library/time.rst
new file mode 100644
index 0000000..04c8f66
--- /dev/null
+++ b/Doc/library/time.rst
@@ -0,0 +1,540 @@
+
+:mod:`time` --- Time access and conversions
+===========================================
+
+.. module:: time
+ :synopsis: Time access and conversions.
+
+
+This module provides various time-related functions. For related
+functionality, see also the :mod:`datetime` and :mod:`calendar` modules.
+
+Although this module is always available,
+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.
+
+ .. index:: single: epoch
+
+* The :dfn:`epoch` is the point where the time starts. On January 1st of that
+ year, at 0 hours, the "time since the epoch" is zero. For Unix, the epoch is
+ 1970. To find out what the epoch is, look at ``gmtime(0)``.
+
+ .. index:: single: Year 2038
+
+* The functions in this module do not handle dates and times before the epoch or
+ far in the future. The cut-off point in the future is determined by the C
+ library; for Unix, it is typically in 2038.
+
+ .. index::
+ single: Year 2000
+ single: Y2K
+
+* **Year 2000 (Y2K) issues**: Python depends on the platform's C library, which
+ generally doesn't have year 2000 issues, since all dates and times are
+ represented internally as seconds since the epoch. Functions accepting a
+ :class:`struct_time` (see below) generally require a 4-digit year. For backward
+ compatibility, 2-digit years are supported if the module variable
+ ``accept2dyear`` is a non-zero integer; this variable is initialized to ``1``
+ unless the environment variable :envvar:`PYTHONY2K` is set to a non-empty
+ string, in which case it is initialized to ``0``. Thus, you can set
+ :envvar:`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::
+ single: UTC
+ single: Coordinated Universal Time
+ single: Greenwich Mean Time
+
+* UTC is Coordinated Universal Time (formerly known as Greenwich Mean Time, or
+ GMT). The acronym UTC is not a mistake but a compromise between English and
+ French.
+
+ .. index:: single: Daylight Saving Time
+
+* 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
+ systems, the clock "ticks" only 50 or 100 times a second, and on the Mac, times
+ 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
+ :func:`strftime`, is a sequence of 9 integers. The return values of
+ :func:`gmtime`, :func:`localtime`, and :func:`strptime` also offer attribute
+ names for individual fields.
+
+ +-------+------------------+------------------------------+
+ | Index | Attribute | Values |
+ +=======+==================+==============================+
+ | 0 | :attr:`tm_year` | (for example, 1993) |
+ +-------+------------------+------------------------------+
+ | 1 | :attr:`tm_mon` | range [1,12] |
+ +-------+------------------+------------------------------+
+ | 2 | :attr:`tm_mday` | range [1,31] |
+ +-------+------------------+------------------------------+
+ | 3 | :attr:`tm_hour` | range [0,23] |
+ +-------+------------------+------------------------------+
+ | 4 | :attr:`tm_min` | range [0,59] |
+ +-------+------------------+------------------------------+
+ | 5 | :attr:`tm_sec` | range [0,61]; see **(1)** in |
+ | | | :func:`strftime` description |
+ +-------+------------------+------------------------------+
+ | 6 | :attr:`tm_wday` | range [0,6], Monday is 0 |
+ +-------+------------------+------------------------------+
+ | 7 | :attr:`tm_yday` | range [1,366] |
+ +-------+------------------+------------------------------+
+ | 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.
+
+The module defines the following functions and data items:
+
+
+.. 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.
+
+
+.. data:: altzone
+
+ The offset of the local DST timezone, in seconds west of UTC, if one is defined.
+ This is negative if the local DST timezone is east of UTC (as in Western Europe,
+ including the UK). Only use this if ``daylight`` is nonzero.
+
+
+.. function:: asctime([t])
+
+ Convert a tuple or :class:`struct_time` representing a time as returned by
+ :func:`gmtime` or :func:`localtime` to a 24-character string of the following
+ form: ``'Sun Jun 20 23:21:05 1993'``. If *t* is not provided, the current time
+ as returned by :func:`localtime` is used. Locale information is not used by
+ :func:`asctime`.
+
+ .. note::
+
+ Unlike the C function of the same name, there is no trailing newline.
+
+ .. versionchanged:: 2.1
+ Allowed *t* to be omitted.
+
+
+.. function:: clock()
+
+ .. index::
+ single: CPU time
+ single: processor time
+ single: benchmarking
+
+ On Unix, return the current processor time as a floating point number expressed
+ in seconds. The precision, and in fact the very definition of the meaning of
+ "processor time", depends on that of the C function of the same name, but in any
+ case, this is the function to use for benchmarking Python or timing algorithms.
+
+ 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
+ :cfunc:`QueryPerformanceCounter`. The resolution is typically better than one
+ microsecond.
+
+
+.. function:: ctime([secs])
+
+ Convert a time expressed in seconds since the epoch to a string representing
+ local time. If *secs* is not provided or :const:`None`, the current time as
+ returned by :func:`time` is used. ``ctime(secs)`` is equivalent to
+ ``asctime(localtime(secs))``. Locale information is not used by :func:`ctime`.
+
+ .. versionchanged:: 2.1
+ Allowed *secs* to be omitted.
+
+ .. versionchanged:: 2.4
+ If *secs* is :const:`None`, the current time is used.
+
+
+.. data:: daylight
+
+ Nonzero if a DST timezone is defined.
+
+
+.. function:: gmtime([secs])
+
+ Convert a time expressed in seconds since the epoch to a :class:`struct_time` in
+ UTC in which the dst flag is always zero. If *secs* is not provided or
+ :const:`None`, the current time as returned by :func:`time` is used. Fractions
+ of a second are ignored. See above for a description of the
+ :class:`struct_time` object. See :func:`calendar.timegm` for the inverse of this
+ function.
+
+ .. versionchanged:: 2.1
+ Allowed *secs* to be omitted.
+
+ .. versionchanged:: 2.4
+ If *secs* is :const:`None`, the current time is used.
+
+
+.. function:: localtime([secs])
+
+ Like :func:`gmtime` but converts to local time. If *secs* is not provided or
+ :const:`None`, the current time as returned by :func:`time` is used. The dst
+ flag is set to ``1`` when DST applies to the given time.
+
+ .. versionchanged:: 2.1
+ Allowed *secs* to be omitted.
+
+ .. versionchanged:: 2.4
+ If *secs* is :const:`None`, the current time is used.
+
+
+.. function:: mktime(t)
+
+ This is the inverse function of :func:`localtime`. Its argument is the
+ :class:`struct_time` or full 9-tuple (since the dst flag is needed; use ``-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 :func:`time`.
+ If the input value cannot be represented as a valid time, either
+ :exc:`OverflowError` or :exc:`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.
+
+
+.. function:: sleep(secs)
+
+ Suspend execution for the given number of seconds. The argument may be a
+ floating point number to indicate a more precise sleep time. The actual
+ suspension time may be less than that requested because any caught signal will
+ terminate the :func:`sleep` following execution of that signal's catching
+ routine. Also, the suspension time may be longer than requested by an arbitrary
+ amount because of the scheduling of other activity in the system.
+
+
+.. function:: strftime(format[, t])
+
+ Convert a tuple or :class:`struct_time` representing a time as returned by
+ :func:`gmtime` or :func:`localtime` to a string as specified by the *format*
+ argument. If *t* is not provided, the current time as returned by
+ :func:`localtime` is used. *format* must be a string. :exc:`ValueError` is
+ raised if any field in *t* is outside of the allowed range.
+
+ .. versionchanged:: 2.1
+ Allowed *t* to be omitted.
+
+ .. versionchanged:: 2.4
+ :exc:`ValueError` raised if a field in *t* is out of range.
+
+ .. versionchanged:: 2.5
+ 0 is now a legal argument for any position in the time tuple; if it is normally
+ illegal the value is forced to a correct one..
+
+ 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 :func:`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 | \(1) |
+ | | AM or PM. | |
+ +-----------+--------------------------------+-------+
+ | ``%S`` | Second as a decimal number | \(2) |
+ | | [00,61]. | |
+ +-----------+--------------------------------+-------+
+ | ``%U`` | Week number of the year | \(3) |
+ | | (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 | \(3) |
+ | | (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. | |
+ +-----------+--------------------------------+-------+
+ | ``%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:
+
+ (1)
+ When used with the :func:`strptime` function, the ``%p`` directive only affects
+ the output hour field if the ``%I`` directive is used to parse the hour.
+
+ (2)
+ The range really is ``0`` to ``61``; this accounts for leap seconds and the
+ (very rare) double leap seconds.
+
+ (3)
+ When used with the :func:`strptime` function, ``%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. [#]_ ::
+
+ >>> 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.
+
+
+.. function:: strptime(string[, format])
+
+ Parse a string representing a time according to a format. The return value is
+ a :class:`struct_time` as returned by :func:`gmtime` or :func:`localtime`.
+
+ The *format* parameter uses the same directives as those used by
+ :func:`strftime`; it defaults to ``"%a %b %d %H:%M:%S %Y"`` which matches the
+ formatting returned by :func:`ctime`. If *string* cannot be parsed according to
+ *format*, or if it has excess data after parsing, :exc:`ValueError` is raised.
+ The default values used to fill in any missing data when more accurate values
+ cannot be inferred are ``(1900, 1, 1, 0, 0, 0, 0, 1, -1)``.
+
+ For example::
+
+ >>> import time
+ >>> time.strptime("30 Nov 00", "%d %b %y")
+ (2000, 11, 30, 0, 0, 0, 3, 335, -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).
+
+ 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
+
+
+.. function:: time()
+
+ Return the time as a floating point number expressed in seconds since the epoch,
+ in UTC. Note that even though the time is always returned as a floating point
+ number, not all systems provide time with a better precision than 1 second.
+ While this function normally returns non-decreasing values, it can return a
+ lower value than a previous call if the system clock has been set back between
+ the two calls.
+
+
+.. data:: timezone
+
+ The offset of the local (non-DST) timezone, in seconds west of UTC (negative in
+ most of Western Europe, positive in the US, zero in the UK).
+
+
+.. data:: tzname
+
+ A tuple of two strings: the first is the name of the local non-DST timezone, the
+ second is the name of the local DST timezone. If no DST timezone is defined,
+ the second string should not be used.
+
+
+.. function:: tzset()
+
+ Resets the time conversion rules used by the library routines. The environment
+ variable :envvar:`TZ` specifies how this is done.
+
+ .. versionadded:: 2.3
+
+ Availability: Unix.
+
+ .. 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.
+
+ The standard format of the :envvar:`TZ` environment variable is (whitespace
+ added for clarity)::
+
+ std offset [dst [offset [,start[/time], end[/time]]]]
+
+ Where the components are:
+
+ ``std`` and ``dst``
+ Three or more alphanumerics giving the timezone abbreviations. These will be
+ propagated into time.tzname
+
+ ``offset``
+ The offset has the form: ``± hh[:mm[:ss]]``. This indicates the value
+ added the local time to arrive at UTC. If preceded by a '-', the timezone
+ is east of the Prime Meridian; otherwise, it is west. If no offset follows
+ dst, summer time is assumed to be one hour ahead of standard time.
+
+ ``start[/time], end[/time]``
+ Indicates when to change to and back from DST. The format of the
+ start and end dates are one of the following:
+
+ :samp:`J{n}`
+ The Julian day *n* (1 <= *n* <= 365). Leap days are not counted, so in
+ all years February 28 is day 59 and March 1 is day 60.
+
+ :samp:`{n}`
+ The zero-based Julian day (0 <= *n* <= 365). Leap days are counted, and
+ it is possible to refer to February 29.
+
+ :samp:`M{m}.{n}.{d}`
+ The *d*'th day (0 <= *d* <= 6) or week *n* of month *m* of the year (1
+ <= *n* <= 5, 1 <= *m* <= 12, where week 5 means "the last *d* day in
+ month *m*" which may occur in either the fourth or the fifth
+ week). Week 1 is the first week in which the *d*'th day occurs. Day
+ zero is Sunday.
+
+ ``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 (:manpage:`tzfile(5)`) database to
+ specify the timezone rules. To do this, set the :envvar:`TZ` environment
+ variable to the path of the required timezone datafile, relative to the root of
+ the systems 'zoneinfo' timezone database, usually located at
+ :file:`/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')
+
+
+.. seealso::
+
+ Module :mod:`datetime`
+ More object-oriented interface to dates and times.
+
+ Module :mod:`locale`
+ Internationalization services. The locale settings can affect the return values
+ for some of the functions in the :mod:`time` module.
+
+ Module :mod:`calendar`
+ General calendar-related functions. :func:`timegm` is the inverse of
+ :func:`gmtime` from this module.
+
+.. rubric:: Footnotes
+
+.. [#] The use of ``%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`.
+