GeezerVison

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.