Highlight datetime.timedelta.seconds vs .total_seconds() in docs.

[gpshead]

This comes out of a discovery a colleague made:

Should we create a linter rule for code that looks at timedelta.seconds when they mean timedelta.total_seconds(), and if so, what would that look like? A quick grep suggests we have this bug in a number of places in our code.

which prompted an investigation by @Zac-HD:

of N occurences of .seconds >N-6 of them are this bug on timedeltas, and the rest are attributes of classes we define and can thus change.

meaning basically 100% of uses of datetime.timedelta.seconds should've been using .total_seconds()...

If you know that you will never be encountering a timedelta longer than 1 day there is no difference between the two (which is why code often gets away with this...), but how often does code guarantee that and would fail in a surprising manner when >=1 day deltas are encountered as a result of the mistake?

Documenting the caveat seems useful to guide people away from this mistake.

Linter ecosystem checks to highlight this deemed useful but are outside of our purview.

---

📚 Documentation preview 📚: https://cpython-previews--124811.org.readthedocs.build/

https://cpython-previews--124811.org.readthedocs.build/en/124811/library/datetime.html#datetime.timedelta.seconds

[terryjreedy]

LGTM as edited.

[miss-islington-app]

Thanks @gpshead for the PR 🌮🎉.. I'm working now to backport this PR to: 3.12, 3.13.
🐍🍒⛏🤖

[bedevere-app]

GH-124862 is a backport of this pull request to the 3.13 branch.

[bedevere-app]

GH-124863 is a backport of this pull request to the 3.12 branch.

[pganssle]

I think this is... fine, but doesn't seem especially specific to seconds? Shouldn't the same also apply to minutes and hours and whatnot?

I think it might be a good idea to refactor this into a single note about how to get total durations (usually dividing by the unit you want, my_td / timedelta(seconds=1)), and then maybe have caution notes on the struct accessors pointing to the central note.

[gpshead]

I was pondering that as well but timedelta only has .days, .seconds, and .microseconds attributes. Not hours or days.

So this caution sandwiched inbetween the others at least hopefully provides the right hint for those as well. But those two being the less commonly used bookend most and least significant terms are much more obvious when they don't give what someone wants in most cases as microseconds would quickly overflow and days would always lack a fraction so I feel like they're less likely to actually be used in a significantly buggy manner.

The value of the cautionary note is in having it right next to the docs for the thing people otherwise naturally reach for. So if it is moved to be reworded as general covering all three, please keep it in that section right next to the attributes overall.

The division by a dynamically created temporary value of units is less intuitive (and probably slower) than just calling .total_seconds() in this case. But that approach is already covered in the .total_seconds docs for other units.