#13076: merge with 3.2.

Doc/library/datetime.rst

@@ -18,13 +18,13 @@ functionality, see also the :mod:`time` and :mod:`calendar` modules.
 There are two kinds of date and time objects: "naive" and "aware". This
 distinction refers to whether the object has any notion of time zone, daylight
 saving time, or other kind of algorithmic or political time adjustment.  Whether
-a naive :class:`datetime` object represents Coordinated Universal Time (UTC),
+a naive :class:`.datetime` object represents Coordinated Universal Time (UTC),
 local time, or time in some other timezone is purely up to the program, just
 like it's up to the program whether a particular number represents metres,
-miles, or mass.  Naive :class:`datetime` objects are easy to understand and to
+miles, or mass.  Naive :class:`.datetime` objects are easy to understand and to
 work with, at the cost of ignoring some aspects of reality.
 
-For applications requiring more, :class:`datetime` and :class:`time` objects
+For applications requiring more, :class:`.datetime` and :class:`.time` objects
 have an optional time zone information attribute, :attr:`tzinfo`, that can be
 set to an instance of a subclass of the abstract :class:`tzinfo` class.  These
 :class:`tzinfo` objects capture information about the offset from UTC time, the
@@ -41,13 +41,13 @@ The :mod:`datetime` module exports the following constants:
 
 .. data:: MINYEAR
 
-   The smallest year number allowed in a :class:`date` or :class:`datetime` object.
+   The smallest year number allowed in a :class:`date` or :class:`.datetime` object.
    :const:`MINYEAR` is ``1``.
 
 
 .. data:: MAXYEAR
 
-   The largest year number allowed in a :class:`date` or :class:`datetime` object.
+   The largest year number allowed in a :class:`date` or :class:`.datetime` object.
    :const:`MAXYEAR` is ``9999``.
 
 
@@ -91,14 +91,14 @@ Available Types
 .. class:: timedelta
    :noindex:
 
-   A duration expressing the difference between two :class:`date`, :class:`time`,
+   A duration expressing the difference between two :class:`date`, :class:`.time`,
-   or :class:`datetime` instances to microsecond resolution.
+   or :class:`.datetime` instances to microsecond resolution.
 
 
 .. class:: tzinfo
 
    An abstract base class for time zone information objects.  These are used by the
-   :class:`datetime` and :class:`time` classes to provide a customizable notion of
+   :class:`.datetime` and :class:`.time` classes to provide a customizable notion of
    time adjustment (for example, to account for time zone and/or daylight saving
    time).
 
@@ -114,7 +114,7 @@ Objects of these types are immutable.
 
 Objects of the :class:`date` type are always naive.
 
-An object *d* of type :class:`time` or :class:`datetime` may be naive or aware.
+An object *d* of type :class:`.time` or :class:`.datetime` may be naive or aware.
 *d* is aware if ``d.tzinfo`` is not ``None`` and ``d.tzinfo.utcoffset(d)`` does
 not return ``None``.  If ``d.tzinfo`` is ``None``, or if ``d.tzinfo`` is not
 ``None`` but ``d.tzinfo.utcoffset(d)`` returns ``None``, *d* is naive.
@@ -299,7 +299,7 @@ Notes:
   -1 day, 19:00:00
 
 In addition to the operations listed above :class:`timedelta` objects support
-certain additions and subtractions with :class:`date` and :class:`datetime`
+certain additions and subtractions with :class:`date` and :class:`.datetime`
 objects (see below).
 
 .. versionchanged:: 3.2
@@ -638,10 +638,10 @@ Example of working with :class:`date`:
 :class:`datetime` Objects
 -------------------------
 
-A :class:`datetime` object is a single object containing all the information
+A :class:`.datetime` object is a single object containing all the information
-from a :class:`date` object and a :class:`time` object.  Like a :class:`date`
+from a :class:`date` object and a :class:`.time` object.  Like a :class:`date`
-object, :class:`datetime` assumes the current Gregorian calendar extended in
+object, :class:`.datetime` assumes the current Gregorian calendar extended in
-both directions; like a time object, :class:`datetime` assumes there are exactly
+both directions; like a time object, :class:`.datetime` assumes there are exactly
 3600\*24 seconds in every day.
 
 Constructor:
@@ -689,7 +689,7 @@ Other constructors, all class methods:
 
    Return the current UTC date and time, with :attr:`tzinfo` ``None``. This is like
    :meth:`now`, but returns the current UTC date and time, as a naive
-   :class:`datetime` object.  An aware current UTC datetime can be obtained by
+   :class:`.datetime` object.  An aware current UTC datetime can be obtained by
    calling ``datetime.now(timezone.utc)``.  See also :meth:`now`.
 
 .. classmethod:: datetime.fromtimestamp(timestamp, tz=None)
@@ -697,7 +697,7 @@ Other constructors, all class methods:
    Return the local date and time corresponding to the POSIX timestamp, such as is
    returned by :func:`time.time`. If optional argument *tz* is ``None`` or not
    specified, the timestamp is converted to the platform's local date and time, and
-   the returned :class:`datetime` object is naive.
+   the returned :class:`.datetime` object is naive.
 
    Else *tz* must be an instance of a class :class:`tzinfo` subclass, and the
    timestamp is converted to *tz*'s time zone.  In this case the result is
@@ -710,12 +710,12 @@ Other constructors, all class methods:
    1970 through 2038. Note that on non-POSIX systems that include leap seconds in
    their notion of a timestamp, leap seconds are ignored by :meth:`fromtimestamp`,
    and then it's possible to have two timestamps differing by a second that yield
-   identical :class:`datetime` objects. See also :meth:`utcfromtimestamp`.
+   identical :class:`.datetime` objects. See also :meth:`utcfromtimestamp`.
 
 
 .. classmethod:: datetime.utcfromtimestamp(timestamp)
 
-   Return the UTC :class:`datetime` corresponding to the POSIX timestamp, with
+   Return the UTC :class:`.datetime` corresponding to the POSIX timestamp, with
    :attr:`tzinfo` ``None``. This may raise :exc:`ValueError`, if the timestamp is
    out of the range of values supported by the platform C :c:func:`gmtime` function.
    It's common for this to be restricted to years in 1970 through 2038. See also
@@ -740,7 +740,7 @@ Other constructors, all class methods:
 
 .. classmethod:: datetime.fromordinal(ordinal)
 
-   Return the :class:`datetime` corresponding to the proleptic Gregorian ordinal,
+   Return the :class:`.datetime` corresponding to the proleptic Gregorian ordinal,
    where January 1 of year 1 has ordinal 1. :exc:`ValueError` is raised unless ``1
    <= ordinal <= datetime.max.toordinal()``.  The hour, minute, second and
    microsecond of the result are all 0, and :attr:`tzinfo` is ``None``.
@@ -748,18 +748,18 @@ Other constructors, all class methods:
 
 .. classmethod:: datetime.combine(date, time)
 
-   Return a new :class:`datetime` object whose date components are equal to the
+   Return a new :class:`.datetime` object whose date components are equal to the
    given :class:`date` object's, and whose time components and :attr:`tzinfo`
-   attributes are equal to the given :class:`time` object's. For any
+   attributes are equal to the given :class:`.time` object's. For any
-   :class:`datetime` object *d*,
+   :class:`.datetime` object *d*,
    ``d == datetime.combine(d.date(), d.timetz())``.  If date is a
-   :class:`datetime` object, its time components and :attr:`tzinfo` attributes
+   :class:`.datetime` object, its time components and :attr:`tzinfo` attributes
    are ignored.
 
 
 .. classmethod:: datetime.strptime(date_string, format)
 
-   Return a :class:`datetime` corresponding to *date_string*, parsed according to
+   Return a :class:`.datetime` corresponding to *date_string*, parsed according to
    *format*.  This is equivalent to ``datetime(*(time.strptime(date_string,
    format)[0:6]))``. :exc:`ValueError` is raised if the date_string and format
    can't be parsed by :func:`time.strptime` or if it returns a value which isn't a
@@ -771,19 +771,19 @@ Class attributes:
 
 .. attribute:: datetime.min
 
-   The earliest representable :class:`datetime`, ``datetime(MINYEAR, 1, 1,
+   The earliest representable :class:`.datetime`, ``datetime(MINYEAR, 1, 1,
    tzinfo=None)``.
 
 
 .. attribute:: datetime.max
 
-   The latest representable :class:`datetime`, ``datetime(MAXYEAR, 12, 31, 23, 59,
+   The latest representable :class:`.datetime`, ``datetime(MAXYEAR, 12, 31, 23, 59,
    59, 999999, tzinfo=None)``.
 
 
 .. attribute:: datetime.resolution
 
-   The smallest possible difference between non-equal :class:`datetime` objects,
+   The smallest possible difference between non-equal :class:`.datetime` objects,
    ``timedelta(microseconds=1)``.
 
 
@@ -826,24 +826,24 @@ Instance attributes (read-only):
 
 .. attribute:: datetime.tzinfo
 
-   The object passed as the *tzinfo* argument to the :class:`datetime` constructor,
+   The object passed as the *tzinfo* argument to the :class:`.datetime` constructor,
    or ``None`` if none was passed.
 
 
 Supported operations:
 
-+---------------------------------------+-------------------------------+
++---------------------------------------+--------------------------------+
-| Operation                             | Result                        |
+| Operation                             | Result                         |
-+=======================================+===============================+
++=======================================+================================+
-| ``datetime2 = datetime1 + timedelta`` | \(1)                          |
+| ``datetime2 = datetime1 + timedelta`` | \(1)                           |
-+---------------------------------------+-------------------------------+
++---------------------------------------+--------------------------------+
-| ``datetime2 = datetime1 - timedelta`` | \(2)                          |
+| ``datetime2 = datetime1 - timedelta`` | \(2)                           |
-+---------------------------------------+-------------------------------+
++---------------------------------------+--------------------------------+
-| ``timedelta = datetime1 - datetime2`` | \(3)                          |
+| ``timedelta = datetime1 - datetime2`` | \(3)                           |
-+---------------------------------------+-------------------------------+
++---------------------------------------+--------------------------------+
-| ``datetime1 < datetime2``             | Compares :class:`datetime` to |
+| ``datetime1 < datetime2``             | Compares :class:`.datetime` to |
-|                                       | :class:`datetime`. (4)        |
+|                                       | :class:`.datetime`. (4)        |
-+---------------------------------------+-------------------------------+
++---------------------------------------+--------------------------------+
 
 (1)
    datetime2 is a duration of timedelta removed from datetime1, moving forward in
@@ -862,7 +862,7 @@ Supported operations:
    in isolation can overflow in cases where datetime1 - timedelta does not.
 
 (3)
-   Subtraction of a :class:`datetime` from a :class:`datetime` is defined only if
+   Subtraction of a :class:`.datetime` from a :class:`.datetime` is defined only if
    both operands are naive, or if both are aware.  If one is aware and the other is
    naive, :exc:`TypeError` is raised.
 
@@ -891,16 +891,16 @@ Supported operations:
 
       In order to stop comparison from falling back to the default scheme of comparing
       object addresses, datetime comparison normally raises :exc:`TypeError` if the
-      other comparand isn't also a :class:`datetime` object.  However,
+      other comparand isn't also a :class:`.datetime` object.  However,
       ``NotImplemented`` is returned instead if the other comparand has a
       :meth:`timetuple` attribute.  This hook gives other kinds of date objects a
-      chance at implementing mixed-type comparison.  If not, when a :class:`datetime`
+      chance at implementing mixed-type comparison.  If not, when a :class:`.datetime`
       object is compared to an object of a different type, :exc:`TypeError` is raised
       unless the comparison is ``==`` or ``!=``.  The latter cases return
       :const:`False` or :const:`True`, respectively.
 
-:class:`datetime` objects can be used as dictionary keys. In Boolean contexts,
+:class:`.datetime` objects can be used as dictionary keys. In Boolean contexts,
-all :class:`datetime` objects are considered to be true.
+all :class:`.datetime` objects are considered to be true.
 
 Instance methods:
 
@@ -911,13 +911,13 @@ Instance methods:
 
 .. method:: datetime.time()
 
-   Return :class:`time` object with same hour, minute, second and microsecond.
+   Return :class:`.time` object with same hour, minute, second and microsecond.
    :attr:`tzinfo` is ``None``.  See also method :meth:`timetz`.
 
 
 .. method:: datetime.timetz()
 
-   Return :class:`time` object with same hour, minute, second, microsecond, and
+   Return :class:`.time` object with same hour, minute, second, microsecond, and
    tzinfo attributes.  See also method :meth:`time`.
 
 
@@ -931,7 +931,7 @@ Instance methods:
 
 .. method:: datetime.astimezone(tz)
 
-   Return a :class:`datetime` object with new :attr:`tzinfo` attribute *tz*,
+   Return a :class:`.datetime` object with new :attr:`tzinfo` attribute *tz*,
    adjusting the date and time data so the result is the same UTC time as
    *self*, but in *tz*'s local time.
 
@@ -1005,7 +1005,7 @@ Instance methods:
 
 .. method:: datetime.utctimetuple()
 
-   If :class:`datetime` instance *d* is naive, this is the same as
+   If :class:`.datetime` instance *d* is naive, this is the same as
    ``d.timetuple()`` except that :attr:`tm_isdst` is forced to 0 regardless of what
    ``d.dst()`` returns.  DST is never in effect for a UTC time.
 
@@ -1066,7 +1066,7 @@ Instance methods:
 
 .. method:: datetime.__str__()
 
-   For a :class:`datetime` instance *d*, ``str(d)`` is equivalent to
+   For a :class:`.datetime` instance *d*, ``str(d)`` is equivalent to
    ``d.isoformat(' ')``.
 
 
@@ -1215,19 +1215,19 @@ Class attributes:
 
 .. attribute:: time.min
 
-   The earliest representable :class:`time`, ``time(0, 0, 0, 0)``.
+   The earliest representable :class:`.time`, ``time(0, 0, 0, 0)``.
 
 
 .. attribute:: time.max
 
-   The latest representable :class:`time`, ``time(23, 59, 59, 999999)``.
+   The latest representable :class:`.time`, ``time(23, 59, 59, 999999)``.
 
 
 .. attribute:: time.resolution
 
-   The smallest possible difference between non-equal :class:`time` objects,
+   The smallest possible difference between non-equal :class:`.time` objects,
-   ``timedelta(microseconds=1)``, although note that arithmetic on :class:`time`
+   ``timedelta(microseconds=1)``, although note that arithmetic on
-   objects is not supported.
+   :class:`.time` objects is not supported.
 
 
 Instance attributes (read-only):
@@ -1254,13 +1254,13 @@ Instance attributes (read-only):
 
 .. attribute:: time.tzinfo
 
-   The object passed as the tzinfo argument to the :class:`time` constructor, or
+   The object passed as the tzinfo argument to the :class:`.time` constructor, or
    ``None`` if none was passed.
 
 
 Supported operations:
 
-* comparison of :class:`time` to :class:`time`, where *a* is considered less
+* comparison of :class:`.time` to :class:`.time`, where *a* is considered less
   than *b* when *a* precedes *b* in time.  If one comparand is naive and the other
   is aware, :exc:`TypeError` is raised.  If both comparands are aware, and have
   the same :attr:`tzinfo` attribute, the common :attr:`tzinfo` attribute is
@@ -1268,7 +1268,7 @@ Supported operations:
   have different :attr:`tzinfo` attributes, the comparands are first adjusted by
   subtracting their UTC offsets (obtained from ``self.utcoffset()``). In order
   to stop mixed-type comparisons from falling back to the default comparison by
-  object address, when a :class:`time` object is compared to an object of a
+  object address, when a :class:`.time` object is compared to an object of a
   different type, :exc:`TypeError` is raised unless the comparison is ``==`` or
   ``!=``.  The latter cases return :const:`False` or :const:`True`, respectively.
 
@@ -1276,7 +1276,7 @@ Supported operations:
 
 * efficient pickling
 
-* in Boolean contexts, a :class:`time` object is considered to be true if and
+* in Boolean contexts, a :class:`.time` object is considered to be true if and
   only if, after converting it to minutes and subtracting :meth:`utcoffset` (or
   ``0`` if that's ``None``), the result is non-zero.
 
@@ -1285,10 +1285,10 @@ Instance methods:
 
 .. method:: time.replace([hour[, minute[, second[, microsecond[, tzinfo]]]]])
 
-   Return a :class:`time` with the same value, except for those attributes given
+   Return a :class:`.time` with the same value, except for those attributes given
    new values by whichever keyword arguments are specified.  Note that
-   ``tzinfo=None`` can be specified to create a naive :class:`time` from an
+   ``tzinfo=None`` can be specified to create a naive :class:`.time` from an
-   aware :class:`time`, without conversion of the time data.
+   aware :class:`.time`, without conversion of the time data.
 
 
 .. method:: time.isoformat()
@@ -1366,13 +1366,13 @@ Example:
 :class:`tzinfo` is an abstract base class, meaning that this class should not be
 instantiated directly.  You need to derive a concrete subclass, and (at least)
 supply implementations of the standard :class:`tzinfo` methods needed by the
-:class:`datetime` methods you use.  The :mod:`datetime` module supplies
+:class:`.datetime` methods you use.  The :mod:`datetime` module supplies
 a simple concrete subclass of :class:`tzinfo` :class:`timezone` which can reprsent
 timezones with fixed offset from UTC such as UTC itself or North American EST and
 EDT.
 
 An instance of (a concrete subclass of) :class:`tzinfo` can be passed to the
-constructors for :class:`datetime` and :class:`time` objects. The latter objects
+constructors for :class:`.datetime` and :class:`.time` objects. The latter objects
 view their attributes as being in local time, and the :class:`tzinfo` object
 supports methods revealing offset of local time from UTC, the name of the time
 zone, and DST offset, all relative to a date or time object passed to them.
@@ -1427,7 +1427,7 @@ methods.  Exactly which methods are needed depends on the uses made of aware
 
    ``tz.utcoffset(dt) - tz.dst(dt)``
 
-   must return the same result for every :class:`datetime` *dt* with ``dt.tzinfo ==
+   must return the same result for every :class:`.datetime` *dt* with ``dt.tzinfo ==
    tz``  For sane :class:`tzinfo` subclasses, this expression yields the time
    zone's "standard offset", which should not depend on the date or the time, but
    only on geographic location.  The implementation of :meth:`datetime.astimezone`
@@ -1459,7 +1459,7 @@ methods.  Exactly which methods are needed depends on the uses made of aware
 
 .. method:: tzinfo.tzname(dt)
 
-   Return the time zone name corresponding to the :class:`datetime` object *dt*, as
+   Return the time zone name corresponding to the :class:`.datetime` object *dt*, as
    a string. Nothing about string names is defined by the :mod:`datetime` module,
    and there's no requirement that it mean anything in particular.  For example,
    "GMT", "UTC", "-500", "-5:00", "EDT", "US/Eastern", "America/New York" are all
@@ -1472,11 +1472,11 @@ methods.  Exactly which methods are needed depends on the uses made of aware
    The default implementation of :meth:`tzname` raises :exc:`NotImplementedError`.
 
 
-These methods are called by a :class:`datetime` or :class:`time` object, in
+These methods are called by a :class:`.datetime` or :class:`.time` object, in
-response to their methods of the same names.  A :class:`datetime` object passes
+response to their methods of the same names.  A :class:`.datetime` object passes
-itself as the argument, and a :class:`time` object passes ``None`` as the
+itself as the argument, and a :class:`.time` object passes ``None`` as the
 argument.  A :class:`tzinfo` subclass's methods should therefore be prepared to
-accept a *dt* argument of ``None``, or of class :class:`datetime`.
+accept a *dt* argument of ``None``, or of class :class:`.datetime`.
 
 When ``None`` is passed, it's up to the class designer to decide the best
 response.  For example, returning ``None`` is appropriate if the class wishes to
@@ -1484,7 +1484,7 @@ say that time objects don't participate in the :class:`tzinfo` protocols.  It
 may be more useful for ``utcoffset(None)`` to return the standard UTC offset, as
 there is no other convention for discovering the standard offset.
 
-When a :class:`datetime` object is passed in response to a :class:`datetime`
+When a :class:`.datetime` object is passed in response to a :class:`.datetime`
 method, ``dt.tzinfo`` is the same object as *self*.  :class:`tzinfo` methods can
 rely on this, unless user code calls :class:`tzinfo` methods directly.  The
 intent is that the :class:`tzinfo` methods interpret *dt* as being in local
@@ -1623,7 +1623,7 @@ made to civil time.
 .. method:: timezone.fromutc(dt)
 
   Return ``dt + offset``.  The *dt* argument must be an aware
-  :class:`datetime` instance, with ``tzinfo`` set to ``self``.
+  :class:`.datetime` instance, with ``tzinfo`` set to ``self``.
 
 Class attributes:
 
@@ -1637,18 +1637,18 @@ Class attributes:
 :meth:`strftime` and :meth:`strptime` Behavior
 ----------------------------------------------
 
-:class:`date`, :class:`datetime`, and :class:`time` objects all support a
+:class:`date`, :class:`.datetime`, and :class:`.time` objects all support a
 ``strftime(format)`` method, to create a string representing the time under the
 control of an explicit format string.  Broadly speaking, ``d.strftime(fmt)``
 acts like the :mod:`time` module's ``time.strftime(fmt, d.timetuple())``
 although not all objects support a :meth:`timetuple` method.
 
 Conversely, the :meth:`datetime.strptime` class method creates a
-:class:`datetime` object from a string representing a date and time and a
+:class:`.datetime` object from a string representing a date and time and a
 corresponding format string. ``datetime.strptime(date_string, format)`` is
 equivalent to ``datetime(*(time.strptime(date_string, format)[0:6]))``.
 
-For :class:`time` objects, the format codes for year, month, and day should not
+For :class:`.time` objects, the format codes for year, month, and day should not
 be used, as time objects have no such values.  If they're used anyway, ``1900``
 is substituted for the year, and ``1`` for the month and day.
 
@@ -1806,5 +1806,5 @@ Notes:
 
 .. versionchanged:: 3.2
    When the ``%z`` directive is provided to the :meth:`strptime` method, an
-   aware :class:`datetime` object will be produced.  The ``tzinfo`` of the
+   aware :class:`.datetime` object will be produced.  The ``tzinfo`` of the
    result will be set to a :class:`timezone` instance.