Repository navigation
Document the "gotcha" behaviors in utcnow() and utcfromtimestamp() #81669
Description
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']
Activity
pganssle commentedon Jul 2, 2019
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()andutcfromtimestamp()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_Yorkon a machine with IANA data installed:>>> from datetime import datetime >>> dt = datetime.utcfromtimestamp(0) >>> dt datetime.datetime(1970, 1, 1, 0, 0) >>> dt.timestamp() 18000This 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 withutcnow().I'm not sure if actually deprecating
utcnowandutcfromtimestampis worth it at the moment, but we can definitely start by adding a warning box toutcnow()andutcfromtimestamp()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.epicfaace commentedon Sep 10, 2019
Why not deprecate them?
miss-islington commentedon Sep 11, 2019
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
miss-islington commentedon Sep 12, 2019
New changeset 307c5fe by Miss Islington (bot) in branch '3.8':
bpo-37488 : Document a warning for datetime.utcnow() and utcfromtimestamp() (GH-15773)
307c5fe
pganssle commentedon Sep 12, 2019
Thanks Joannah!
[REF] hr*: remove the use of utcnow
[REF] hr*: remove the use of utcnow
fix: update utcnow for python 3.12 deprecation