Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

#14766: Add correct algorithm for when a 'time' object is naive. 

This patch also clarifies the definition of Naive and Aware.

Original patch by Greg Weller, I modified the first hunk
somewhat to make the exposition even clearer (I hope).
This commit is contained in:
R David Murray 2012-05-14 22:14:46 -04:00
parent 1f24548e1f
commit 9075d8b771
1 changed files with 26 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
Doc/library/datetime.rst
View File

@ -15,16 +15,23 @@ focus of the implementation is on efficient attribute extraction for output
formatting and manipulation. For related formatting and manipulation. For related
functionality, see also the :mod:`time` and :mod:`calendar` modules. functionality, see also the :mod:`time` and :mod:`calendar` modules.
There are two kinds of date and time objects: "naive" and "aware". This There are two kinds of date and time objects: "naive" and "aware".
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 An aware object has sufficient knowledge of applicable algorithmic and
a naive :class:`.datetime` object represents Coordinated Universal Time (UTC), political time adjustments, such as time zone and daylight saving time
information, to locate itself relative to other aware objects. An aware object
is used to represent a specific moment in time that is not open to
interpretation [#]_.
A naive object does not contain enough information to unambiguously locate
itself relative to other date/time objects. Whether a naive object represents
Coordinated Universal Time (UTC),
local time, or time in some other timezone is purely up to the program, just 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, 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 objects are easy to understand and to
work with, at the cost of ignoring some aspects of reality. work with, at the cost of ignoring some aspects of reality.
For applications requiring more, :class:`.datetime` and :class:`.time` objects For applications requiring aware objects, :class:`.datetime` and :class:`.time` objects
have an optional time zone information attribute, :attr:`tzinfo`, that can be 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 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 :class:`tzinfo` objects capture information about the offset from UTC time, the
@ -32,8 +39,8 @@ time zone name, and whether Daylight Saving Time is in effect. Note that only
one concrete :class:`tzinfo` class, the :class:`timezone` class, is supplied by the one concrete :class:`tzinfo` class, the :class:`timezone` class, is supplied by the
:mod:`datetime` module. The :class:`timezone` class can represent simple :mod:`datetime` module. The :class:`timezone` class can represent simple
timezones with fixed offset from UTC such as UTC itself or North American EST and timezones with fixed offset from UTC such as UTC itself or North American EST and
EDT timezones. Supporting timezones at whatever level of detail is EDT timezones. Supporting timezones at deeper levels of detail is
required is up to the application. The rules for time adjustment across the up to the application. The rules for time adjustment across the
world are more political than rational, change frequently, and there is no world are more political than rational, change frequently, and there is no
standard suitable for every application aside from UTC. standard suitable for every application aside from UTC.
@ -114,10 +121,13 @@ Objects of these types are immutable.
Objects of the :class:`date` type are always naive. 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 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 A :class:`.datetime` object *d* is aware if ``d.tzinfo`` is not ``None`` and
not return ``None``. If ``d.tzinfo`` is ``None``, or if ``d.tzinfo`` is not ``d.tzinfo.utcoffset(d)`` does not return ``None``. If ``d.tzinfo`` is
``None`` but ``d.tzinfo.utcoffset(d)`` returns ``None``, *d* is naive. ``None``, or if ``d.tzinfo`` is not ``None`` but ``d.tzinfo.utcoffset(d)``
returns ``None``, *d* is naive. A :class:`.time` object *t* is aware
if ``t.tzinfo`` is not ``None`` and ``t.tzinfo.utcoffset(None)`` does not return
``None``. Otherwise, *t* is naive.
The distinction between naive and aware doesn't apply to :class:`timedelta` The distinction between naive and aware doesn't apply to :class:`timedelta`
objects. objects.
@ -1806,3 +1816,7 @@ Notes:
When the ``%z`` directive is provided to the :meth:`strptime` method, an 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. result will be set to a :class:`timezone` instance.
.. rubric:: Footnotes
.. [#] If, that is, we ignore the effects of Relativity