All commit authors signed the Contributor License Agreement.

Please do not use the Update Branch button unless necessary (e.g. fixing conflicts, jogging the CI, or very old PRs) as it uses valuable resources. For more information see the devguide.

I have been waiting for this fix. Thank you @NehaJeevan

I just took a cursory look, but the issue I have with this change in general is that it seems to be coming from a perspective that implies that datetime arithmetic is supposed to be absolute time arithmetic and that Python has some warts that makes this untrue in certain circumstances.

This was of thinking about things does the users a disservice, because that is not how datetime arithmetic works, and users should be as quickly disabused of this mental model as possible, rather than encouraging them to keep that mental model and introducing a few edge cases where it fails. With the correct mental model the behavior of datetime is entirely unsurprising.

@pganssle Thanks for the comment. I understand that Python datetime arithmetic is designed around wall time (based on comments on gh-116111) and my doc change doesn’t dispute that.

But I think it’s important to acknowledge that this behavior is very often misunderstood, especially around DST transitions. Python is one of the few languages to expose both fold and tzinfo while also performing arithmetic in local time. That combination is unusual and silently surprising to users expecting “elapsed” behavior.

The phrasing in the docs doesn’t imply that the current behavior is incorrect or a failure. It explains how arithmetic behaves, what implications that has across DST, and gives a correct, standard workaround (astimezone to UTC). This is entirely in line with how similar patterns are documented in other places (e.g. in astimezone itself), and it's consistent with the language and tone of the Python documentation style guide.

I think simply saying “this is by design” doesn't help users who are surprised especially since this exact confusion is what led to issue gh-116111 in the first place.

If you feel the current wording reinforces the wrong mental model, I’m open to rephrasing but I’d really appreciate a concrete suggestion. It’s not clear to me what part you’d want changed, especially since the doc already makes it clear that wall time is the model being used. The goal here is just to help users avoid common misunderstandings without misrepresenting the design.