Deprecate `utcnow` and `utcfromtimestamp`

pganssle · GitHub

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

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

Document the "gotcha" behaviors in utcnow() and utcfromtimestamp() #81669

https://discuss.python.org/t/add-aliases-with-explicit-names-for-naive-and-aware-datetime-now-and-utcnow/25997

Various bugs about this:

datetime.utcnow() should return a timezone aware datetime #90477

datetime.datetime.utcnow should return a UTC timestamp #56965

Using datetime.datetime.utcnow().timestamp() in Python3.6.0 can't get correct UTC timestamp. #77474

Linked PRs

GH-103857: Deprecate utcnow and utcfromtimestamp #103858

gh-103857: Update deprecation stacktrace to point to calling line #104431

gh-103857: Document utcnow and utcfromtimestamp deprecations in What's New #104542