[Python-checkins] cpython (2.7): Issue #26678: Fix datetime.tzinfo indexing and “tzinfo” attribute links
martin.panter
python-checkins at python.org
Fri Apr 1 20:03:30 EDT 2016
https://hg.python.org/cpython/rev/4cad272cec82
changeset: 100831:4cad272cec82
branch: 2.7
parent: 100826:a3a4155dfc1a
user: Martin Panter <vadmium+py at gmail.com>
date: Fri Apr 01 21:48:24 2016 +0000
summary:
Issue #26678: Fix datetime.tzinfo indexing and “tzinfo” attribute links
files:
Doc/library/datetime.rst | 103 +++++++++++++-------------
1 files changed, 53 insertions(+), 50 deletions(-)
diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
--- a/Doc/library/datetime.rst
+++ b/Doc/library/datetime.rst
@@ -33,7 +33,7 @@
and to work with, at the cost of ignoring some aspects of reality.
For applications requiring aware objects, :class:`.datetime` and :class:`.time`
-objects have an optional time zone information attribute, :attr:`tzinfo`, that
+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 time zone name, and whether Daylight Saving Time is in effect. Note
@@ -83,7 +83,7 @@
An idealized time, independent of any particular day, assuming that every day
has exactly 24\*60\*60 seconds (there is no notion of "leap seconds" here).
Attributes: :attr:`hour`, :attr:`minute`, :attr:`second`, :attr:`microsecond`,
- and :attr:`tzinfo`.
+ and :attr:`.tzinfo`.
.. class:: datetime
@@ -91,7 +91,7 @@
A combination of a date and a time. Attributes: :attr:`year`, :attr:`month`,
:attr:`day`, :attr:`hour`, :attr:`minute`, :attr:`second`, :attr:`microsecond`,
- and :attr:`tzinfo`.
+ and :attr:`.tzinfo`.
.. class:: timedelta
@@ -102,6 +102,7 @@
.. class:: tzinfo
+ :noindex:
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
@@ -650,7 +651,7 @@
.. classmethod:: datetime.today()
- Return the current local datetime, with :attr:`tzinfo` ``None``. This is
+ Return the current local datetime, with :attr:`.tzinfo` ``None``. This is
equivalent to ``datetime.fromtimestamp(time.time())``. See also :meth:`now`,
:meth:`fromtimestamp`.
@@ -663,15 +664,15 @@
(for example, this may be possible on platforms supplying the C
:c:func:`gettimeofday` function).
- Else *tz* must be an instance of a class :class:`tzinfo` subclass, and the
- current date and time are converted to *tz*'s time zone. In this case the
+ If *tz* is not ``None``, it must be an instance of a :class:`tzinfo` subclass, and the
+ current date and time are converted to *tz*’s time zone. In this case the
result is equivalent to ``tz.fromutc(datetime.utcnow().replace(tzinfo=tz))``.
See also :meth:`today`, :meth:`utcnow`.
.. classmethod:: datetime.utcnow()
- Return the current UTC date and time, with :attr:`tzinfo` ``None``. This is like
+ 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. See also :meth:`now`.
@@ -683,8 +684,8 @@
specified, the timestamp is converted to the platform's local date and time, and
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
+ If *tz* is not ``None``, it must be an instance of a :class:`tzinfo` subclass, and the
+ timestamp is converted to *tz*’s time zone. In this case the result is
equivalent to
``tz.fromutc(datetime.utcfromtimestamp(timestamp).replace(tzinfo=tz))``.
@@ -700,7 +701,7 @@
.. classmethod:: datetime.utcfromtimestamp(timestamp)
Return the UTC :class:`.datetime` corresponding to the POSIX timestamp, with
- :attr:`tzinfo` ``None``. This may raise :exc:`ValueError`, if the timestamp is
+ :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
:meth:`fromtimestamp`.
@@ -711,17 +712,17 @@
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``.
+ microsecond of the result are all 0, and :attr:`.tzinfo` is ``None``.
.. classmethod:: datetime.combine(date, time)
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`
+ given :class:`date` object's, and whose time components and :attr:`.tzinfo`
attributes are equal to the given :class:`.time` object's. For any
: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.
@@ -818,7 +819,7 @@
(1)
datetime2 is a duration of timedelta removed from datetime1, moving forward in
time if ``timedelta.days`` > 0, or backward if ``timedelta.days`` < 0. The
- result has the same :attr:`tzinfo` attribute as the input datetime, and
+ result has the same :attr:`~.datetime.tzinfo` attribute as the input datetime, and
datetime2 - datetime1 == timedelta after. :exc:`OverflowError` is raised if
datetime2.year would be smaller than :const:`MINYEAR` or larger than
:const:`MAXYEAR`. Note that no time zone adjustments are done even if the
@@ -826,7 +827,7 @@
(2)
Computes the datetime2 such that datetime2 + timedelta == datetime1. As for
- addition, the result has the same :attr:`tzinfo` attribute as the input
+ addition, the result has the same :attr:`~.datetime.tzinfo` attribute as the input
datetime, and no time zone adjustments are done even if the input is aware.
This isn't quite equivalent to datetime1 + (-timedelta), because -timedelta
in isolation can overflow in cases where datetime1 - timedelta does not.
@@ -836,12 +837,12 @@
both operands are naive, or if both are aware. If one is aware and the other is
naive, :exc:`TypeError` is raised.
- If both are naive, or both are aware and have the same :attr:`tzinfo` attribute,
- the :attr:`tzinfo` attributes are ignored, and the result is a :class:`timedelta`
+ If both are naive, or both are aware and have the same :attr:`~.datetime.tzinfo` attribute,
+ the :attr:`~.datetime.tzinfo` attributes are ignored, and the result is a :class:`timedelta`
object *t* such that ``datetime2 + t == datetime1``. No time zone adjustments
are done in this case.
- If both are aware and have different :attr:`tzinfo` attributes, ``a-b`` acts
+ If both are aware and have different :attr:`~.datetime.tzinfo` attributes, ``a-b`` acts
as if *a* and *b* were first converted to naive UTC datetimes first. The
result is ``(a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None)
- b.utcoffset())`` except that the implementation never overflows.
@@ -851,9 +852,9 @@
*datetime2* 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 ignored and the base datetimes are
- compared. If both comparands are aware and have different :attr:`tzinfo`
+ If both comparands are aware, and have the same :attr:`~.datetime.tzinfo` attribute, the
+ common :attr:`~.datetime.tzinfo` attribute is ignored and the base datetimes are
+ compared. If both comparands are aware and have different :attr:`~.datetime.tzinfo`
attributes, the comparands are first adjusted by subtracting their UTC
offsets (obtained from ``self.utcoffset()``).
@@ -882,7 +883,7 @@
.. method:: datetime.time()
Return :class:`.time` object with same hour, minute, second and microsecond.
- :attr:`tzinfo` is ``None``. See also method :meth:`timetz`.
+ :attr:`.tzinfo` is ``None``. See also method :meth:`timetz`.
.. method:: datetime.timetz()
@@ -901,7 +902,7 @@
.. 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.
@@ -939,7 +940,7 @@
.. method:: datetime.utcoffset()
- If :attr:`tzinfo` is ``None``, returns ``None``, else returns
+ If :attr:`.tzinfo` is ``None``, returns ``None``, else returns
``self.tzinfo.utcoffset(self)``, and raises an exception if the latter doesn't
return ``None``, or a :class:`timedelta` object representing a whole number of
minutes with magnitude less than one day.
@@ -947,7 +948,7 @@
.. method:: datetime.dst()
- If :attr:`tzinfo` is ``None``, returns ``None``, else returns
+ If :attr:`.tzinfo` is ``None``, returns ``None``, else returns
``self.tzinfo.dst(self)``, and raises an exception if the latter doesn't return
``None``, or a :class:`timedelta` object representing a whole number of minutes
with magnitude less than one day.
@@ -955,7 +956,7 @@
.. method:: datetime.tzname()
- If :attr:`tzinfo` is ``None``, returns ``None``, else returns
+ If :attr:`.tzinfo` is ``None``, returns ``None``, else returns
``self.tzinfo.tzname(self)``, raises an exception if the latter doesn't return
``None`` or a string object,
@@ -967,7 +968,7 @@
d.hour, d.minute, d.second, d.weekday(), yday, dst))``, where ``yday =
d.toordinal() - date(d.year, 1, 1).toordinal() + 1`` is the day number within
the current year starting with ``1`` for January 1st. The :attr:`tm_isdst` flag
- of the result is set according to the :meth:`dst` method: :attr:`tzinfo` is
+ of the result is set according to the :meth:`dst` method: :attr:`.tzinfo` is
``None`` or :meth:`dst` returns ``None``, :attr:`tm_isdst` is set to ``-1``;
else if :meth:`dst` returns a non-zero value, :attr:`tm_isdst` is set to ``1``;
else :attr:`tm_isdst` is set to ``0``.
@@ -1242,9 +1243,9 @@
* 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
+ the same :attr:`~time.tzinfo` attribute, the common :attr:`~time.tzinfo` attribute is
ignored and the base times are compared. If both comparands are aware and
- have different :attr:`tzinfo` attributes, the comparands are first adjusted by
+ have different :attr:`~time.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
@@ -1299,7 +1300,7 @@
.. method:: time.utcoffset()
- If :attr:`tzinfo` is ``None``, returns ``None``, else returns
+ If :attr:`.tzinfo` is ``None``, returns ``None``, else returns
``self.tzinfo.utcoffset(None)``, and raises an exception if the latter doesn't
return ``None`` or a :class:`timedelta` object representing a whole number of
minutes with magnitude less than one day.
@@ -1307,7 +1308,7 @@
.. method:: time.dst()
- If :attr:`tzinfo` is ``None``, returns ``None``, else returns
+ If :attr:`.tzinfo` is ``None``, returns ``None``, else returns
``self.tzinfo.dst(None)``, and raises an exception if the latter doesn't return
``None``, or a :class:`timedelta` object representing a whole number of minutes
with magnitude less than one day.
@@ -1315,7 +1316,7 @@
.. method:: time.tzname()
- If :attr:`tzinfo` is ``None``, returns ``None``, else returns
+ If :attr:`.tzinfo` is ``None``, returns ``None``, else returns
``self.tzinfo.tzname(None)``, or raises an exception if the latter doesn't
return ``None`` or a string object.
@@ -1352,26 +1353,28 @@
:class:`tzinfo` Objects
-----------------------
-: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 does not supply
-any concrete subclasses of :class:`tzinfo`.
+.. class:: tzinfo()
-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
-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.
+ This 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 does not supply
+ any concrete subclasses of :class:`tzinfo`.
-Special requirement for pickling: A :class:`tzinfo` subclass must have an
-:meth:`__init__` method that can be called with no arguments, else it can be
-pickled but possibly not unpickled again. This is a technical requirement that
-may be relaxed in the future.
+ 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
+ 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.
-A concrete subclass of :class:`tzinfo` may need to implement the following
-methods. Exactly which methods are needed depends on the uses made of aware
-:mod:`datetime` objects. If in doubt, simply implement all of them.
+ Special requirement for pickling: A :class:`tzinfo` subclass must have an
+ :meth:`__init__` method that can be called with no arguments, else it can be
+ pickled but possibly not unpickled again. This is a technical requirement that
+ may be relaxed in the future.
+
+ A concrete subclass of :class:`tzinfo` may need to implement the following
+ methods. Exactly which methods are needed depends on the uses made of aware
+ :mod:`datetime` objects. If in doubt, simply implement all of them.
.. method:: tzinfo.utcoffset(self, dt)
@@ -1404,7 +1407,7 @@
(see :meth:`utcoffset` for details). Note that DST offset, if applicable, has
already been added to the UTC offset returned by :meth:`utcoffset`, so there's
no need to consult :meth:`dst` unless you're interested in obtaining DST info
- separately. For example, :meth:`datetime.timetuple` calls its :attr:`tzinfo`
+ separately. For example, :meth:`datetime.timetuple` calls its :attr:`~.datetime.tzinfo`
attribute's :meth:`dst` method to determine how the :attr:`tm_isdst` flag
should be set, and :meth:`tzinfo.fromutc` calls :meth:`dst` to account for
DST changes when crossing time zones.
--
Repository URL: https://hg.python.org/cpython
More information about the Python-checkins
mailing list