gh-116111: Clarify DST behaviour in datetime arithmetic and zoneinfo docs #137092
Conversation
|
All commit authors signed the Contributor License Agreement. |
…evan/cpython into fix-issue-116111-on-datetime-docs
|
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 |
This PR updates the documentation for
datetimeandzoneinfoto clarify how arithmetic involving aware datetime objects behaves during daylight saving time (DST) transitions.Changes include:
.. warning::in thetimedeltasection noting that arithmetic on aware datetime objects with the sametzinfoignores DST... note::in the datetime subtraction section, with a concrete example, explaining the "naive time" behavior.zoneinfo.rstthat previously claimed "no further intervention" was required to handle DST transitions... note::inzoneinfo.rstto show howtimedeltaarithmetic skips DST transitions unless handled explicitly.This PR resolves gh-116111 based on the suggestions on the issue
📚 Documentation preview 📚: https://cpython-previews--137092.org.readthedocs.build/