[issue8822] datetime naive and aware types should have a well-defined definition that can be cross-referenced
New submission from anatoly techtonik techtonik@gmail.com:
'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.
---------- assignee: docs@python components: Documentation messages: 106524 nosy: docs@python, techtonik priority: normal severity: normal status: open title: datetime naive and aware types should have a well-defined definition that can be cross-referenced
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8822 _______________________________________
Changes by Antoine Pitrou pitrou@free.fr:
---------- nosy: +belopolsky stage: -> needs patch versions: +Python 2.6, Python 2.7, Python 3.1, Python 3.2
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8822 _______________________________________
Alexander Belopolsky belopolsky@users.sourceforge.net added the comment:
'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. """
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8822 _______________________________________
Jakob Malm jakob.malm@gmail.com added the comment:
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'.
---------- nosy: +shaq
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8822 _______________________________________
Jakob Malm jakob.malm@gmail.com added the comment:
I created a patch with the revised wording.
---------- keywords: +patch Added file: http://bugs.python.org/file23135/datetime_doc.patch
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8822 _______________________________________
Alexander Belopolsky alexander.belopolsky@gmail.com added the comment:
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.
---------- nosy: +Alexander.Belopolsky
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8822 _______________________________________
anatoly techtonik techtonik@gmail.com added the comment:
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.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8822 _______________________________________
Alexander Belopolsky alexander.belopolsky@gmail.com added the comment:
On Mon, Sep 12, 2011 at 4:36 PM, anatoly techtonik report@bugs.python.org wrote: ..
- 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.
- 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.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8822 _______________________________________
Jakob Malm jakob.malm@gmail.com added the comment:
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...
---------- Added file: http://bugs.python.org/file23167/datetime_doc_noreflow.patch
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8822 _______________________________________
Alexander Belopolsky alexander.belopolsky@gmail.com added the comment:
-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.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8822 _______________________________________
anatoly techtonik techtonik@gmail.com added the comment:
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.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8822 _______________________________________
Alexander Belopolsky alexander.belopolsky@gmail.com added the comment:
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
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8822 _______________________________________
Jakob Malm jakob.malm@gmail.com added the comment:
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...
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8822 _______________________________________
Mark Lawrence added the comment:
I like the wording in the patch as it's clearer than the original and so think it should be applied.
---------- nosy: +BreamoreBoy
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8822 _______________________________________
Change by Mark Lawrence breamoreboy@gmail.com:
---------- nosy: -BreamoreBoy
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue8822 _______________________________________
Change by Senthil Kumaran senthil@uthcode.com:
---------- versions: +Python 3.10 -Python 2.6, Python 2.7, Python 3.1, Python 3.2
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue8822 _______________________________________
-
Alexander Belopolsky -
anatoly techtonik
-
Antoine Pitrou
-
Jakob Malm
-
Mark Lawrence
-
Senthil Kumaran