New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
datetime naive and aware types should have a well-defined definition that can be cross-referenced #53068
Comments
'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. |
The definition is given in the introductory section: 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?
This may be due to the fact that there is no concrete tzinfo implementation in stdlib. See bpo-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.
This is already clear IMO: """ |
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:
Perhaps the sentence could be changed to something like: "date and time objects are either 'naive' or 'aware'. |
I created a patch with the revised wording. |
On Mon, Sep 12, 2011 at 4:30 PM, Jakob Malm <report@bugs.python.org> wrote:
Your patch seems to reflow the entire paragraph which makes it hard to |
The point was:
That's it. If it's already done - then this ticket can be closed. |
On Mon, Sep 12, 2011 at 4:36 PM, anatoly techtonik
This is simply wrong: in py3k we have the timezone class that
I would go one step further: we should review the examples in datetime |
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... |
-There are two kinds of date and time objects: "naive" and "aware". This Shouldn't we say "datetime and time" instead of "date and time"? |
Perhaps like this? :class:`datetime` and :class:`time` objects are... |
On Thu, Sep 15, 2011 at 10:42 PM, Alexander Belopolsky
Does that mean that if aware
|
On Thu, Sep 15, 2011 at 4:17 PM, anatoly techtonik
Yes, but one cannot convert "back" from date to datetime. To get a
I agree. The following is not really intuitive: -> None In order to preserve tzinfo, one has to preserve it when extracting -> datetime.timezone.utc |
I like the wording in the patch as it's clearer than the original and so think it should be applied. |
It looks to me that the current document addresses the main concerns here: the wording regarding types is clarified, there is an anchor to the aware/naive objects, and aware/naive are marked bold for clarity. There's also a pretty clear section on determining when an object's aware/naive. Since these sections are at the top of the document, imo they've got good enough visibility that not linking every instance of aware/naive is fine, so I think this can be considered resolved. If there are unaddressed issues though, feel free to comment/reopen. |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
bugs.python.org fields:
The text was updated successfully, but these errors were encountered: