classification
Title: datetime naive and aware types should have a well-defined definition that can be cross-referenced
Type: Stage: needs patch
Components: Documentation Versions: Python 3.1, Python 3.2, Python 2.7, Python 2.6
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Alexander.Belopolsky, belopolsky, docs@python, shaq, techtonik
Priority: normal Keywords: patch

Created on 2010-05-26 12:07 by techtonik, last changed 2019-03-15 23:19 by BreamoreBoy.

Files
File name Uploaded Description Edit
datetime_doc.patch shaq, 2011-09-12 20:30 Patch for datetime.rst review
datetime_doc_noreflow.patch shaq, 2011-09-15 19:26 Patch for datetime.rst review
Messages (13)
msg106524 - (view) Author: anatoly techtonik (techtonik) Date: 2010-05-26 12:07
'naive' and 'aware' are key datetime types - they need a proper definition and anchor for crossrefences. If you take a look at http://docs.python.org/library/datetime.html - the definition of distinction between them is too vague and this seeds of uncertainty grow through the rest of the doc. It is not said how to make non-naive object, how to detect if object of naive or aware. All this stuff is very important for troubleshooting datetims issues in Python projects. It needs a proper documentation.
msg106614 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-05-27 18:09
> 'naive' and 'aware' are key datetime types - they need a proper
> definition and anchor for crossrefences.

The definition is given in the introductory section:
"""
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. 
"""

I am not sure what you propose to add to this.  Do you wan't to dedicate a separate subsection to naive and aware time and datetime? I feel that would be an overkill.  Would simply adding index entries for naive and aware time/datetime objects be enough?

> It is not said how to make non-naive object, 

This may be due to the fact that there is no concrete tzinfo implementation in stdlib.  See issue 5094.

I think it can be added in datetime constructor section that providing a tzinfo argument results in an aware object.  this is already so for datetime.fromtimestamp.

> how to detect if object of naive or aware.

This is already clear IMO:

"""
An object d of type time or 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.
"""
msg143930 - (view) Author: Jakob Malm (shaq) * Date: 2011-09-12 19:35
I agree with Alexander -- I think the current documentation is sufficient to describe 'naive' and 'aware' date and time objects.

The sentence "There are two kinds of date and time objects: “naive” and “aware”." is perhaps a bit unfortunate, however. It appears that Anatoly had misinterpreted 'naive' and 'aware' objects to be of different Python types:

> 'naive' and 'aware' are key datetime types

Perhaps the sentence could be changed to something like:

"date and time objects are either 'naive' or 'aware'.
msg143936 - (view) Author: Jakob Malm (shaq) * Date: 2011-09-12 20:30
I created a patch with the revised wording.
msg143937 - (view) Author: Alexander Belopolsky (Alexander.Belopolsky) Date: 2011-09-12 20:35
On Mon, Sep 12, 2011 at 4:30 PM, Jakob Malm <report@bugs.python.org> wrote:
..
> I created a patch with the revised wording.

Your patch seems to reflow the entire paragraph which makes it hard to
review and if applied will appear as a bigger change than it is.  Can
you regenerate the patch so that it does not have whitespace only
diffs?  Thanks.
msg143938 - (view) Author: anatoly techtonik (techtonik) Date: 2011-09-12 20:35
The point was:
1. Create an anchor to definition of "naive" object
2. Create an anchor to definition of "aware" object
3. Make definitions stand out from the inline text
4. Create cross-references for "naive" and "aware" keywords in text that lead directly to appropriate definition
5. Mention the fact: By default all objects are "naive", by definition, because they don't have any TZ information, and there are no classes in stdlib that provide this info (tzclass implemetations)
6. Answer the questions: How to make non-naive object? How to detect if object of naive or aware?

That's it. If it's already done - then this ticket can be closed.
msg143939 - (view) Author: Alexander Belopolsky (Alexander.Belopolsky) Date: 2011-09-12 20:50
On Mon, Sep 12, 2011 at 4:36 PM, anatoly techtonik
<report@bugs.python.org> wrote:
..
> 5. Mention the fact: By default all objects are "naive", by definition, because they don't have any
> TZ information, and there are no classes in stdlib that provide this info (tzclass implemetations)

This is simply wrong: in py3k we have the timezone class that
implements tzinfo interface.

> 6. Answer the questions: How to make non-naive object? How to detect if object of naive or aware?

I would go one step further: we should review the examples in datetime
module documentation and use aware datetime objects unless the point
of the example is to demonstrate a naive datetime.  We should also
replace examples that use sample implementations of tzinfo to use the
timezone class.
msg144091 - (view) Author: Jakob Malm (shaq) * Date: 2011-09-15 19:26
Patch without reflow attached.

This is my first patch to CPython. I considered submitting the patch without reflowing the paragraph, to make the changes clearer, but I thought that that would mean more work for the committer, if the patch were to be accepted. Are non-reflown paragraphs like this generally preferred, then?

Concerning timezone aware objects in the examples, this may make the examples more verbose and less to-the-point, which may not be desirable. I'm still on Python 2.6 and haven't actually used the new timezone class yet...
msg144094 - (view) Author: Alexander Belopolsky (Alexander.Belopolsky) Date: 2011-09-15 19:42
-There are two kinds of date and time objects: "naive" and "aware". This
+Date and time objects are either "naive" or "aware". This

Shouldn't we say "datetime and time" instead of "date and time"?
There is no tzinfo attribute in date objects.
msg144096 - (view) Author: Jakob Malm (shaq) * Date: 2011-09-15 19:46
> Shouldn't we say "datetime and time" instead of "date and time"?
> There is no tzinfo attribute in date objects.

Perhaps like this?

:class:`datetime` and :class:`time` objects are...
msg144099 - (view) Author: anatoly techtonik (techtonik) Date: 2011-09-15 20:17
On Thu, Sep 15, 2011 at 10:42 PM, Alexander Belopolsky
<report@bugs.python.org> wrote:
>
> Shouldn't we say "datetime and time" instead of "date and time"?
> There is no tzinfo attribute in date objects.

Does that mean that if aware `datetime` is converted to `date` and
then back, the tzinfo information is lost and object implicitly
becomes naive? In this case it should mentioned IMO.
--
anatoly t.
msg144101 - (view) Author: Alexander Belopolsky (Alexander.Belopolsky) Date: 2011-09-15 20:26
On Thu, Sep 15, 2011 at 4:17 PM, anatoly techtonik
<report@bugs.python.org> wrote:
..
> Does that mean that if aware `datetime` is converted to `date` and
> then back, the tzinfo information is lost and object implicitly
> becomes naive?

Yes, but one cannot convert "back" from date to datetime.  To get a
datetime object, one needs to combine date and time and tzinfo is
attached to the time component.

> In this case it should mentioned IMO.

I agree.  The following is not really intuitive:

-> None

In order to preserve tzinfo, one has to preserve it when extracting
the time component:

-> datetime.timezone.utc
msg220773 - (view) Author: Mark Lawrence (BreamoreBoy) * Date: 2014-06-16 21:53
I like the wording in the patch as it's clearer than the original and so think it should be applied.
History
Date User Action Args
2019-03-15 23:19:19BreamoreBoysetnosy: - BreamoreBoy
2014-06-16 21:53:00BreamoreBoysetnosy: + BreamoreBoy
messages: + msg220773
2011-09-15 20:26:48Alexander.Belopolskysetmessages: + msg144101
2011-09-15 20:17:56techtoniksetmessages: + msg144099
2011-09-15 19:46:54shaqsetmessages: + msg144096
2011-09-15 19:42:27Alexander.Belopolskysetmessages: + msg144094
2011-09-15 19:26:10shaqsetfiles: + datetime_doc_noreflow.patch

messages: + msg144091
2011-09-12 20:50:37Alexander.Belopolskysetmessages: + msg143939
2011-09-12 20:35:59techtoniksetmessages: + msg143938
2011-09-12 20:35:14Alexander.Belopolskysetnosy: + Alexander.Belopolsky
messages: + msg143937
2011-09-12 20:30:51shaqsetfiles: + datetime_doc.patch
keywords: + patch
messages: + msg143936
2011-09-12 19:35:38shaqsetnosy: + shaq
messages: + msg143930
2010-05-27 18:09:07belopolskysetmessages: + msg106614
2010-05-27 16:36:28pitrousetnosy: + belopolsky
stage: needs patch

versions: + Python 2.6, Python 3.1, Python 2.7, Python 3.2
2010-05-26 12:07:26techtonikcreate