bpo-37488 : Document a warning for datetime.utcnow() and utcfromtimestamp() #15773

nanjekyejoannah · 2019-09-09T12:46:33Z

https://bugs.python.org/issue37488

Automerge-Triggered-By: @pganssle

pganssle · 2019-09-09T12:53:45Z

@nanjekyejoannah I don't think we can (or possibly should) put an actual warning in the code here - people will likely complain about it and we're not actually deprecating the function yet, it will likely just cause a lot of uproar and spam (as much as I'd like to...).

What I was referring to in bpo-15733 was a warning box in the documentation, like:

.. warning::

    Because naive datetimes are treated by many functions as local times,
    it is recommended that you create a timezone-aware datetime using
    ``datetime.now(tz=timezone.utc)`` instead.

I have not spent much time thinking about this. We may want a little footnote showing one of the gotchas to be referenced by both utcfromtimestamp and utcnow.

pganssle · 2019-09-09T12:59:17Z

Doc/library/datetime.rst

@@ -29,8 +29,9 @@ 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
+itself relative to other date/time objects.  Native objects are no longer


Was this an intentional change? It looks like you kept in the beginnings of an explanation of the problem, but also the problematic old text.

This is actually a bit complicated to reword, because the sentiment behind it has changed, and we may need to hedge a bit. Let me think about how best to communicate the new intent....

nanjekyejoannah · 2019-09-09T13:03:47Z

Okay. I had thought you wanted us to introduce a warning. I will update this PR accordingly.

epicfaace · 2019-09-10T03:28:42Z

Doc/library/datetime.rst

@@ -804,6 +811,11 @@ Other constructors, all class methods:
   except the latter formula always supports the full years range: between
   :const:`MINYEAR` and :const:`MAXYEAR` inclusive.

+   .. warning::
+
+      Because naive datetimes are treated by many functions as local times.


Can you change this wording to be of a similar sentence structure as in the earlier section (for datetime.utcnow())?

Misc/NEWS.d/next/Library/2019-09-09-12-48-10.bpo-37488.kteuwA.rst

aeros

Thanks for the PR @nanjekyejoannah.

I have a few suggestions:

aeros · 2019-09-10T08:26:44Z

Doc/library/datetime.rst

@@ -752,6 +752,13 @@ Other constructors, all class methods:
   :class:`.datetime` object.  An aware current UTC datetime can be obtained by
   calling ``datetime.now(timezone.utc)``.  See also :meth:`now`.

+   .. warning::
+
+      Because naive datetimes are treated by many functions as local times,


This should be a bit more specific. Also, code comments or Sphinx roles should be used when referencing objects (such as classes, methods, or functions). In this case, code comments would be more appropriate since this is already within the section for datetime.

Suggested change

Because naive datetimes are treated by many functions as local times,

Because naive ``datetime`` objects are treated by many ``datetime`` methods as local times,

This line will need to be split off into the next one since it will exceed the reST maximum width of 80 chars (94 chars after the suggestion).

Doc/library/datetime.rst

pganssle · 2019-09-11T10:15:53Z

@nanjekyejoannah I believe this will have merge conflicts now that #13410 has been merged. Can you rebase against master? I also think adding a warning in utctimetuple() will allow us to close #10870.

aeros

@nanjekyejoannah For consistency, can provide the warning message for each of them?

Because naive datetime objects are treated by many datetime methods
as local times, the recommended way to create aware datetime objects for
the current time in UTC is by calling datetime.now(timezone.utc).

Otherwise, everything else looks good to me.

This also removes several examples using utc* methods, to avoid confusion. bpo-37488: https://bugs.python.org/issue37488

miss-islington · 2019-09-11T13:58:41Z

@nanjekyejoannah: Status check is done, and it's a success ✅ .

@pganssle

…tamp() (pythonGH-15773) https://bugs.python.org/issue37488 Automerge-Triggered-By: @pganssle

miss-islington · 2019-09-12T14:43:48Z

Thanks @nanjekyejoannah for the PR 🌮🎉.. I'm working now to backport this PR to: 3.8.
🐍🍒⛏🤖

@pganssle

…tamp() (pythonGH-15773) https://bugs.python.org/issue37488 Automerge-Triggered-By: @pganssle (cherry picked from commit 1a53c78) Co-authored-by: Joannah Nanjekye <[email protected]>

bedevere-bot · 2019-09-12T14:43:58Z

GH-16059 is a backport of this pull request to the 3.8 branch.

@pganssle

…tamp() (GH-15773) https://bugs.python.org/issue37488 Automerge-Triggered-By: @pganssle (cherry picked from commit 1a53c78) Co-authored-by: Joannah Nanjekye <[email protected]>

nanjekyejoannah requested review from abalkin and pganssle as code owners September 9, 2019 12:46

the-knights-who-say-ni added the CLA signed label Sep 9, 2019

bedevere-bot added the awaiting review label Sep 9, 2019

pganssle reviewed Sep 9, 2019

View reviewed changes

nanjekyejoannah changed the title ~~bpo-37488 : Add warning to datetime.utcnow() and datetime.utcfromtimestamp()~~ bpo-37488 : Document a warning for datetime.utcnow() Sep 9, 2019

nanjekyejoannah changed the title ~~bpo-37488 : Document a warning for datetime.utcnow()~~ bpo-37488 : Document a warning for datetime.utcnow() and utcfromtimestamp() Sep 9, 2019

epicfaace suggested changes Sep 10, 2019

View reviewed changes

bedevere-bot added awaiting core review and removed awaiting review labels Sep 10, 2019

aeros added the docs Documentation in the Doc dir label Sep 10, 2019

aeros reviewed Sep 10, 2019

View reviewed changes

pganssle mentioned this pull request Sep 11, 2019

bpo-9004: Recommend against using utctimetuple in the docs. #10870

Closed

nanjekyejoannah force-pushed the issue37488 branch from 2588293 to 2e5dc03 Compare September 11, 2019 11:42

aeros approved these changes Sep 11, 2019

View reviewed changes

Add warning notes in the documentation for utc* methods

84887b0

This also removes several examples using utc* methods, to avoid confusion. bpo-37488: https://bugs.python.org/issue37488

pganssle force-pushed the issue37488 branch from 7d9e901 to 84887b0 Compare September 11, 2019 13:37

pganssle approved these changes Sep 11, 2019

View reviewed changes

bedevere-bot added awaiting merge and removed awaiting core review labels Sep 11, 2019

pganssle added the 🤖 automerge label Sep 11, 2019

miss-islington merged commit 1a53c78 into python:master Sep 11, 2019

bedevere-bot removed the awaiting merge label Sep 11, 2019

nanjekyejoannah deleted the issue37488 branch September 11, 2019 14:33

DinoV pushed a commit to DinoV/cpython that referenced this pull request Sep 12, 2019

bpo-37488 : Document a warning for datetime.utcnow() and utcfromtimes…

9ee4794

…tamp() (pythonGH-15773) https://bugs.python.org/issue37488 Automerge-Triggered-By: @pganssle

pganssle added the needs backport to 3.8 label Sep 12, 2019

bedevere-bot removed the needs backport to 3.8 label Sep 12, 2019

abalkin mentioned this pull request Apr 10, 2022

datetime.utctimetuple() should not set tm_isdst flag to 0 #53250

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

bpo-37488 : Document a warning for datetime.utcnow() and utcfromtimestamp() #15773

bpo-37488 : Document a warning for datetime.utcnow() and utcfromtimestamp() #15773

nanjekyejoannah commented Sep 9, 2019 •

edited by miss-islington

Loading

pganssle commented Sep 9, 2019 •

edited by bedevere-bot

Loading

pganssle Sep 9, 2019

nanjekyejoannah commented Sep 9, 2019 •

edited

Loading

epicfaace Sep 10, 2019

aeros left a comment

aeros Sep 10, 2019 •

edited

Loading

pganssle commented Sep 11, 2019

aeros left a comment

miss-islington commented Sep 11, 2019

miss-islington commented Sep 12, 2019

bedevere-bot commented Sep 12, 2019

	Because naive datetimes are treated by many functions as local times,
	Because naive ``datetime`` objects are treated by many ``datetime`` methods as local times,

bpo-37488 : Document a warning for datetime.utcnow() and utcfromtimestamp() #15773

bpo-37488 : Document a warning for datetime.utcnow() and utcfromtimestamp() #15773

Conversation

nanjekyejoannah commented Sep 9, 2019 • edited by miss-islington Loading

pganssle commented Sep 9, 2019 • edited by bedevere-bot Loading

pganssle Sep 9, 2019

Choose a reason for hiding this comment

nanjekyejoannah commented Sep 9, 2019 • edited Loading

epicfaace Sep 10, 2019

Choose a reason for hiding this comment

aeros left a comment

Choose a reason for hiding this comment

aeros Sep 10, 2019 • edited Loading

Choose a reason for hiding this comment

pganssle commented Sep 11, 2019

aeros left a comment

Choose a reason for hiding this comment

miss-islington commented Sep 11, 2019

miss-islington commented Sep 12, 2019

bedevere-bot commented Sep 12, 2019

nanjekyejoannah commented Sep 9, 2019 •

edited by miss-islington

Loading

pganssle commented Sep 9, 2019 •

edited by bedevere-bot

Loading

nanjekyejoannah commented Sep 9, 2019 •

edited

Loading

aeros Sep 10, 2019 •

edited

Loading