Deprecate utcnow and utcfromtimestamp

Feature or enhancement

Previously, we have documented that utcnow and utcfromtimestamp should not be used, but we didn't go so far as to actually deprecate them, and I wrote a whole article about how you shouldn't use them.

The main reason I had for not deprecating them at the time was that .utcnow() is faster than .now(datetime.UTC), and if you are immediately converting the datetime to a string, like datetime.utcnow().isoformat(), there's no danger.

I have come around to the idea that this type of use case is not important enough to leave the attractive nuisances of utcnow() and utcfromtimestamp() in place, and we should go ahead and deprecate them.

Pitch

We should deprecate them in the documentation and also add DeprecationWarnings imploring people not to use them. I'm OK with us saying that we will remove them "at some point in the future" and not necessarily putting a deadline on it, considering how much use of utcnow() is out there.

Previous discussion

Linked PRs

I've gone ahead and done some benchmarks for the most common legitimate use case I've seen for utcnow and utcfromtimestamp, which is getting a naïve datetime and immediately formatting it to a string with no time zone offset. The alternatives are considerably slower, though I don't know how important that is for real life use cases:

>>> %timeit datetime.now(UTC).replace(tzinfo=None).isoformat(' ')
2.15 µs ± 19.9 ns per loop (mean ± std. dev. of 7 runs, 100,000 loops each)
>>> %timeit datetime.now(UTC).isoformat(' ')[:-6]
1.61 µs ± 23.7 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)
>>> %timeit datetime.utcnow().isoformat(' ')
919 ns ± 5.23 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)

As an example of how this changes the speed in a real-life application, here are the before and after measurements for the change to http.cookiejar.time2isoz:

>>> t = datetime.now().timestamp()
>>> %timeit cookiejar(None)  # Uses datetime.now
1.52 µs ± 16.2 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)
>>> %timeit cookiejar_utc(None)  # Uses datetime.utcnow
1.32 µs ± 6.72 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)

>>> %timeit cookiejar(t)  # Uses datetime.fromtimestamp
1.77 µs ± 24.2 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)
>>> %timeit cookiejar_utc(t)  # Uses datetime.utcfromtimestamp
1.4 µs ± 5.75 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)

I'm still more or less convinced that this is useful to do, and I'd like to see if anyone complains that it's a major problem after the deprecation before worrying about these micro-optimizations.

GH-103857: Deprecate utcnow and utcfromtimestamp (#103858)

#103858 is now merged, but we still need a What's New entry before closing this, I believe.

gh-103857: Update deprecation stacktrace to point to calling line (#1…

#103858 is now merged, but we still need a What's New entry before closing this, I believe.

Please see PR #104542.

Replace deprecated utcnow() with now(utc)\n\nRaises a deprecation war…

gh-103857: Document utcnow and utcfromtimestamp deprecations in What'…

I think we're all set here! 🚀

py-mongo: updated to 4.4.1

Remove use of deprecated `datetime.datetime` methods

[REF] hr*: remove the use of utcnow

tree-wide: replace utcnow and utcfromtimestamp (#4462)

chore: swap out deprecated datetime's utcnow and utcfromtimestamp (#1…

Replace datetime.utcnow() with datetime.now(timezone.utc)

py-mongo: updated to 4.4.1

Fix flaky unit tests caused by mismatched timezones.

Navigation Menu

Repository navigation

Deprecate `utcnow` and `utcfromtimestamp` #103857

Feature or enhancement

Pitch

Previous discussion

Linked PRs

3 remaining items

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Deprecate utcnow and utcfromtimestamp #103857

Description

Feature or enhancement

Pitch

Previous discussion

Linked PRs

Activity

pganssle commented on Apr 26, 2023

pganssle commented on Apr 27, 2023

hugovk commented on May 16, 2023

hugovk commented on May 22, 2023

3 remaining items

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions

Deprecate `utcnow` and `utcfromtimestamp` #103857