From 9075d8b7719ed66a025bdc11cd0b2923f3cbf58d Mon Sep 17 00:00:00 2001 From: R David Murray Date: Mon, 14 May 2012 22:14:46 -0400 Subject: [PATCH] #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). --- Doc/library/datetime.rst | 38 ++++++++++++++++++++++++++------------ 1 file changed, 26 insertions(+), 12 deletions(-) diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index 1c4e9b92c1f..112a62c70b1 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -15,16 +15,23 @@ focus of the implementation is on efficient attribute extraction for output formatting and manipulation. For related 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), +There are two kinds of date and time objects: "naive" and "aware". + +An aware object has sufficient knowledge of applicable algorithmic and +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 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. -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 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 @@ -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 :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 -EDT timezones. Supporting timezones at whatever level of detail is -required is up to the application. The rules for time adjustment across the +EDT timezones. Supporting timezones at deeper levels of detail is +up to the application. The rules for time adjustment across the world are more political than rational, change frequently, and there is no 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. -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. +An object of type :class:`.time` or :class:`.datetime` may be naive or aware. +A :class:`.datetime` object *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. 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` objects. @@ -1806,3 +1816,7 @@ Notes: When the ``%z`` directive is provided to the :meth:`strptime` method, an aware :class:`.datetime` object will be produced. The ``tzinfo`` of the result will be set to a :class:`timezone` instance. + +.. rubric:: Footnotes + +.. [#] If, that is, we ignore the effects of Relativity