GH-103857: Deprecate utcnow and utcfromtimestamp by pganssle · Pull Request #103858 · python/cpython · GitHub

Per the reasoning in #103857.

To do:

Add tests
Clean up internal uses of utcnow and utcfromtimestamp

Issue: Deprecate utcnow and utcfromtimestamp #103857

LGTM (fixing the remaining test failures seems straight-forward.)

I like this, my nit is about the wordiness of the warnings.

Outside of that, there's the question of mixing tz-aware and tz-naive datetimes when it comes to comparisons and arithmetic operations. It might be somewhat disruptive for users to replace one with the other to discover TypeErrors in their code due to mixing naive and tz-aware datetimes.

I find this a little wordy for a warning, and tentative. The deprecated function will be removed in the future so we are not recommending an alternative, we are telling people to use an alternative. How about this:

Suggested change

      
                    warnings.warn("datetime.utcfromtimestamp() is deprecated and scheduled "
          
                                  "for removal in a future version. It is instead "
          
                                  "recommended that users use timezone-aware objects to "
          
                                  "represent datetimes in UTC. To get such an object from "
          
                                  "a timestamp, use datetime.fromtimestamp(t, datetime.UTC).",
          
                                  DeprecationWarning,
          
                                  stacklevel=2)
          
                    warnings.warn("datetime.utcfromtimestamp() is deprecated and will be "
          
                                  "removed in a future version. Use timezone-aware objects to "
          
                                  "represent datetimes in UTC: "
          
                                  "datetime.fromtimestamp(t, datetime.UTC)",
          
                                  DeprecationWarning,
          
                                  stacklevel=2)

I did think it was a bit wordy when I wrote it. My only reservation here is that users still can use naïve objects as they want, they just need to do datetime.now(UTC).replace(tzinfo=None).

I suppose this subtle distinction is probably going to be lost on most people, so I'll just go with your wording.

I agree that Łukasz's suggestion is an improvement. I think it is ok to suggest the slightly disruptive change; we want people to use tz-aware objects1.

Providing a drop-in replacement does not promote using tz-aware objects. ↩

I agree that Łukasz's suggestion is an improvement. I think it is ok to suggest the slightly disruptive change; we want people to use tz-aware objects

I mean, in either case we're suggesting the change, the question is how best to communicate to users that the thing we're suggesting is not a drop-in replacement for the existing workflow. I tend to assume that when I see a deprecation warning with a code snippet in it, the code snippet is how you achieve the same thing in the new version. Ideally we'd make it clear that we are saying, "The thing you are doing now is not something you should continue doing, here's a new way to do it but you need to understand the implications of making this change."

That said, I'm not convinced that it's possible to convey this succinctly, so probably best to just leave it at Łukasz's wording.

Ditto.

Suggested change

      
                    warnings.warn("datetime.utcnow() is deprecated and scheduled for "
          
                                  "removal in a future version. It is instead recommended "
          
                                  "that users use timezone-aware objects to represent "
          
                                  "datetimes in UTC. To get such an object representing "
          
                                  "the current time, use datetime.now(datetime.UTC).",
          
                                  DeprecationWarning,
          
                                  stacklevel=2)
          
                    warnings.warn("datetime.utcnow() is deprecated and will be removed "
          
                                  "in a future version. Use timezone-aware objects to "
          
                                  "represent datetimes in UTC: datetime.now(datetime.UTC)",
          
                                  DeprecationWarning,
          
                                  stacklevel=2)

Ditto here about replacing the warning with the shorter version.

Ditto.

Outside of that, there's the question of mixing tz-aware and tz-naive datetimes when it comes to comparisons and arithmetic operations. It might be somewhat disruptive for users to replace one with the other to discover TypeErrors in their code due to mixing naive and tz-aware datetimes.

Yes, this was somewhat hard to convey in the wording here. I am not trying to suggest that datetime.now(UTC) is a drop-in replacement for datetime.utcnow(). The drop-in replacement is datetime.now(UTC).replace(tzinfo=None). We're deprecating utcnow() because you should be using aware objects to represent datetimes that are actually aware, but it is a breaking change if you change your interfaces that return naïve datetimes into ones that return aware datetimes (which is why we're deprecating these instead of just making them return aware datetimes 😅). This is one reason I worded the warning the way I did.

Another option is to just say, "Use timezone-aware datetimes instead" and not include the code for how to do that, so that they are forced to look up how to do that and are less likely to think it's a drop-in replacement? I suspect that doing so would be a somewhat frustrating user expreience, though. Tough call.

@ambv (or others), what do you think of this wording?

datetime.utcnow() is deprecated and scheduled for removal in a future version.
Instead, Use timezone-aware objects to represent datetimes in UTC:
datetime.now(datetime.UTC). This is not a drop-in replacement.

Alternatively, This will not be a backwards-compatible change. or something to that effect?

OK, I'm going to merge this when CI passes, using Łukasz's wording, unless there are some objections.

LGTM

pganssle requested a review from abalkin as a code owner April 25, 2023 23:04

bedevere-bot mentioned this pull request Apr 25, 2023

Deprecate utcnow and utcfromtimestamp #103857

Closed

bedevere-bot added the awaiting core review label Apr 25, 2023

pganssle requested review from a team, berkerpeksag and erlend-aasland as code owners April 25, 2023 23:59

erlend-aasland approved these changes Apr 26, 2023

View reviewed changes

Comment thread Lib/datetime.py Outdated

Comment thread Lib/datetime.py Outdated

Comment thread Modules/_datetimemodule.c Outdated

Comment thread Modules/_datetimemodule.c Outdated

bedevere-bot added awaiting merge and removed awaiting core review labels Apr 26, 2023

pganssle force-pushed the deprecate_utcnow branch 2 times, most recently from 6294fc7 to 66a82a0 Compare April 26, 2023 16:00

ambv reviewed Apr 26, 2023

View reviewed changes

pganssle force-pushed the deprecate_utcnow branch from 66a82a0 to 3c7c703 Compare April 26, 2023 20:55

pganssle added 5 commits April 27, 2023 10:30

Deprecate utcnow and utcfromtimestamp

d73e4b9

Add news entry for utcnow deprecation

b9c08cf

Remove internal uses of utcnow

261d1d9

Remove all internal uses of utcfromtimestamp

97eff7f

Adjust message to be less wordy

b223173

pganssle force-pushed the deprecate_utcnow branch from 688bb05 to b223173 Compare April 27, 2023 16:30

pganssle merged commit 0b7fd8f into python:main Apr 27, 2023

bedevere-bot removed the awaiting merge label Apr 27, 2023

sobolevn mentioned this pull request Apr 27, 2023

crash in "./python.exe -We -m test -v test_datetime -m test_folds" #103944

Closed

ankit-gautam23 reviewed Apr 28, 2023

View reviewed changes

tacaswell mentioned this pull request May 18, 2023

deal with upcoming deprecations in CPython matplotlib/matplotlib#25912

Closed

pganssle mentioned this pull request Jun 9, 2023

datetime utcnow deprecation leads to type confusion #105544

Closed

wjandrea mentioned this pull request Jul 4, 2023

datetime UTC deprecation warnings use the name "datetime" inconsistently #106392

Closed

JavierUhagon mentioned this pull request May 27, 2024

Modify timestamp generation to remove deprecation warning locustio/locust#2738

Merged

coderabbitai Bot mentioned this pull request May 21, 2026

FE: dashboard page changes dhruvbatra810/card-game#3

Merged

This was referenced Jul 3, 2026

(micro-fix)Add AWS CloudWatch MCP tool aden-hive/hive#7304

Closed

feat: intelligent download system with platform detection JesusQuijada34/packagemaker#3

Open

Fix stale SRI hashes blocking HTMX and Chart.js JJKW1984/golden#4

Merged

This was referenced Jul 20, 2026

Genie 1709/story/built in system redhat-community-ai-tools/UnifAI#239

Closed

Medical Coding Engine: persist coded-term assignments and manual coding workflow fderuiter/cadence-clinical#524

Merged

This was referenced Aug 10, 2026

chore: the audit tail — frontmatter nit, skill sizes, and settled decisions Vycari/maintainerd#20

Merged

feat: Buttons Flow runtime with research-deck example autonoco/buttons#285

Open

+                  PyErr_WarnEx(
+                      PyExc_DeprecationWarning,
+                      "datetime.utcnow() is deprecated and scheduled for removal in a future "
+                      "version. It is instead recommended that users use timezone-aware "
+                      "objects to represent datetimes in UTC. To get such an object "
+                      "representing the current time, use datetime.now(datetime.UTC).",
+
+                  );

+                  PyErr_WarnEx(
+                      PyExc_DeprecationWarning,
+                      "datetime.utcfromtimestamp() is deprecated and scheduled for removal "
+                      "in a future version. It is instead recommended that users use "
+                      "timezone-aware objects to represent datetimes in UTC. To get such an "
+                      "object from a timestamp, use datetime.fromtimestamp(t, datetime.UTC).",
+
+                  );

GH-103857: Deprecate utcnow and utcfromtimestamp by pganssle · Pull Request #103858 · python/cpython · GitHub

Uh oh!

Uh oh!

GH-103857: Deprecate utcnow and utcfromtimestamp - #103858

GH-103857: Deprecate utcnow and utcfromtimestamp#103858pganssle merged 5 commits intopython:mainpython/cpython:mainfrom pganssle:deprecate_utcnowpganssle/cpython:deprecate_utcnowCopy head branch name to clipboard

Conversation

pganssle commented Apr 25, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

erlend-aasland left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ambv left a comment

Choose a reason for hiding this comment

Uh oh!

ambv Apr 26, 2023

Choose a reason for hiding this comment

Uh oh!

pganssle Apr 26, 2023

Choose a reason for hiding this comment

Uh oh!

erlend-aasland Apr 26, 2023

Choose a reason for hiding this comment

Footnotes

Uh oh!

pganssle Apr 26, 2023

Choose a reason for hiding this comment

Uh oh!

ambv Apr 26, 2023

Choose a reason for hiding this comment

Uh oh!

ambv Apr 26, 2023

Choose a reason for hiding this comment

Uh oh!

ambv Apr 26, 2023

Choose a reason for hiding this comment

Uh oh!

pganssle commented Apr 26, 2023

Uh oh!

pganssle commented Apr 26, 2023

Uh oh!

pganssle commented Apr 27, 2023

Uh oh!

ankit-gautam23 left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

GH-103857: Deprecate utcnow and utcfromtimestamp#103858
pganssle merged 5 commits into
python:mainfrom
pganssle:deprecate_utcnow

pganssle commented Apr 25, 2023 •
edited
Loading

erlend-aasland left a comment •
edited
Loading