From 9075d8b7719ed66a025bdc11cd0b2923f3cbf58d Mon Sep 17 00:00:00 2001 From: R David Murray Date: Mon, 14 May 2012 22:14:46 -0400 Subject: #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 1c4e9b9..112a62c 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 -- cgit v0.12 From 539f239e88cbcbdb11014c82ee5a5d8ee9536ec6 Mon Sep 17 00:00:00 2001 From: R David Murray Date: Mon, 14 May 2012 22:17:23 -0400 Subject: #14766: Reflow the altered paragraphs. --- Doc/library/datetime.rst | 35 +++++++++++++++++------------------ 1 file changed, 17 insertions(+), 18 deletions(-) diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index 112a62c..f7e8762 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -12,8 +12,8 @@ The :mod:`datetime` module supplies classes for manipulating dates and times in both simple and complex ways. While date and time arithmetic is supported, the 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. +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". @@ -25,22 +25,21 @@ 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 objects are easy to understand 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 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 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 deeper levels of detail is -up to the application. The rules for time adjustment across the +Coordinated Universal Time (UTC), local time, or time in some other timezone is +purely up to the program, just like it is up to the program whether a +particular number represents metres, 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 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 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 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. -- cgit v0.12