gh-118542: improve datetime deprecation warnings

[Max-Herbold]

Add suggestion for code authors to have an in-place, future-proof replacement if desired.

Builds on the initial issue raised by also adding compatibility suggestion for datetime.datetime.fromtimestamp(timestamp, datetime.UTC) -> datetime.datetime.fromtimestamp(timestamp). By not providing a timezone, the returned object is not timezone aware.

fixes #118542

• Issue: utcnow deprecation note is misleading #118542

[ghost]

All commit authors signed the Contributor License Agreement.

[bedevere-app]

Most changes to Python require a NEWS entry. Add one using the blurb_it web app or the blurb command-line tool.

If this change has little impact on Python users, wait for a maintainer to apply the skip news label instead.

[arhadthedev]

Small typo nitpicks.

[srittau]

Could you also apply a similar change to the deprecation notice in the datetime module documentation?

[pganssle]

I do think we can make it clearer that switching to timezone-aware datetimes is a breaking change if the datetimes you are using them with are exposed to end users, I am still firmly against the idea of anything that looks like recommending an alternative way to get naive datetimes that represent UTC.

[pganssle]

I don't think this is right?

[Max-Herbold]

It was observed, if no timezone is provided, fromtimestamp returns a naïve datetime object.

[pganssle]

If we do decide to offer this approach, I would be much clearer in the message that doing this is effectively equivalent to suppressing the warning without fixing the underlying issue.

[Max-Herbold]

That's true, this issue was raised (and I had the same experience) because there was no in-place replacement to maintain compatibility provided. I ended up at the same conclusion currently proposed several weeks before the original issue was opened but after some significant time.

Is this the correct understanding here; that the proposed modifications correctly address the case where code written for py<3.12 being run on py>=3.12. But do not adequately address (or propose a misleading solution when) the deprecated functions being called when new code is being written in py>=3.12?

[bedevere-app]

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.