Description

pganssle

opened on Jul 2, 2019

Issue body actions

BPO	37488
Nosy	@abalkin, @pganssle, @miss-islington, @epicfaace
PRs	bpo-37488 : Document a warning for datetime.utcnow() and utcfromtimestamp() #15773 [3.8] bpo-37488 : Document a warning for datetime.utcnow() and utcfromtimestamp() (GH-15773) #16059

^{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:

assignee = None
closed_at = <Date 2019-09-12.14:59:27.100>
created_at = <Date 2019-07-02.16:01:38.841>
labels = ['3.8', 'type-feature', '3.7', '3.9', 'docs']
title = 'Document the "gotcha" behaviors in utcnow() and utcfromtimestamp()'
updated_at = <Date 2019-09-12.14:59:27.100>
user = 'https://github.com/pganssle'

bugs.python.org fields:

activity = <Date 2019-09-12.14:59:27.100>
actor = 'p-ganssle'
assignee = 'docs@python'
closed = True
closed_date = <Date 2019-09-12.14:59:27.100>
closer = 'p-ganssle'
components = ['Documentation']
creation = <Date 2019-07-02.16:01:38.841>
creator = 'p-ganssle'
dependencies = []
files = []
hgrepos = []
issue_num = 37488
keywords = ['patch']
message_count = 5.0
messages = ['347148', '351567', '351884', '352189', '352192']
nosy_count = 5.0
nosy_names = ['belopolsky', 'docs@python', 'p-ganssle', 'miss-islington', 'epicfaace']
pr_nums = ['15773', '16059']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue37488'
versions = ['Python 3.7', 'Python 3.8', 'Python 3.9']

Reacted by Dmitry D. Chernov

Activity

1. pganssle commented on Jul 2, 2019

   

   pganssle

   on Jul 2, 2019

   MemberAuthor

   More actions

   Between Python 2 and Python 3, the meaning of a naive datetime underwent a subtle change. Previously a naive datetime was mostly treated as an abstract datetime in the same way a unitless number is treated as an abstract quantity (this is reflected in the current datetime documentation). In Python 3, though, it became more concrete in the sense that rather than just throwing an error whenever you try to do an operation that requires knowing the absolute datetime (e.g. convert between time zones, convert to timestamp, etc), certain operations will succeed with the assumption that naive times represent system local times. This makes utcnow() and utcfromtimestamp() dangerous, because they create a naive datetime as if the naive datetime represents UTC, but this context is then lost and if you ever use one of these "aware-only" operations (.astimezone, .timestamp, etc), you'll get an unexpected answer.

   For example, see this script, executed this with TZ=America/New_York on a machine with IANA data installed:

       >>> from datetime import datetime
       >>> dt = datetime.utcfromtimestamp(0)
       >>> dt
       datetime.datetime(1970, 1, 1, 0, 0)
       >>> dt.timestamp()
       18000

   This happens because EST is 18000s behind UTC, and .timestamp() gives a number of seconds after UTC (a concrete, not an abstract time). You get the same gotchas with utcnow().

   I'm not sure if actually deprecating utcnow and utcfromtimestamp is worth it at the moment, but we can definitely start by adding a warning box to utcnow() and utcfromtimestamp() suggesting that you use the timezone-aware versions of these instead. We may also want to adjust the opening phrasing for the "naive objects" portion of the datetime documentation as well (https://docs.python.org/3.7/library/datetime.html), to reflect the fact that naive datetimes are no longer purely abstract quantities.

   Reacted by Dmitry D. Chernov
2. pganssle

   added

   3.7 (EOL)end of lifeend of life

   3.8 (EOL)end of lifeend of life

   3.9 (EOL)end of lifeend of life

   on Jul 2, 2019
3. pganssle

   assigned

   docspython

   on Jul 2, 2019
4. pganssle

   added

   docsDocumentation in the Doc dirDocumentation in the Doc dir

   type-featureA feature request or enhancementA feature request or enhancement

   on Jul 2, 2019
5. epicfaace commented on Sep 10, 2019

   

   epicfaacemannequin

   on Sep 10, 2019

   Mannequin

   More actions

   Why not deprecate them?
6. miss-islington commented on Sep 11, 2019

   

   miss-islington

   on Sep 11, 2019

   Contributor

   More actions

   New changeset 1a53c78 by Miss Islington (bot) (Joannah Nanjekye) in branch 'master':
   bpo-37488 : Document a warning for datetime.utcnow() and utcfromtimestamp() (GH-15773)
   1a53c78
7. miss-islington commented on Sep 12, 2019

   

   miss-islington

   on Sep 12, 2019

   Contributor

   More actions

   New changeset 307c5fe by Miss Islington (bot) in branch '3.8':
   bpo-37488 : Document a warning for datetime.utcnow() and utcfromtimestamp() (GH-15773)
   307c5fe
8. pganssle commented on Sep 12, 2019

   

   pganssle

   on Sep 12, 2019

   MemberAuthor

   More actions

   Thanks Joannah!
9. pganssle

   closed this as completedon Sep 12, 2019
10. ezio-melotti

    transferred this issue fromon Apr 10, 2022
11. Flotchet

    added a commit that references this issue on May 16, 2024

    [REF] hr*: remove the use of utcnow

    67ff28c
12. robodoo

    added a commit that references this issue on May 30, 2024

    [REF] hr*: remove the use of utcnow

    bc08fb2
13. donbowman

    added a commit that references this issue on Jul 14, 2024

    fix: update utcnow for python 3.12 deprecation

    03544a5

Issue actions