From 45dedab674e146cd93d2fa90579317a7944f0e73 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Thu, 3 Oct 2024 18:25:12 +0200 Subject: [3.13] Highlight `datetime.timedelta.seconds` vs `.total_seconds()` in docs. (GH-124811) (#124862) Highlight `datetime.timedelta.seconds` vs `.total_seconds()` in docs. (GH-124811) Thanks to the reviewers for suggesting the use of a "caution" section instead of "warning" or "note". (cherry picked from commit d150e4abcfc13770c2d239878ed337fb53e51de5) Co-authored-by: Gregory P. Smith --- Doc/library/datetime.rst | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index 0e7dc4f..9246aff 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -295,6 +295,20 @@ Instance attributes (read-only): Between 0 and 86,399 inclusive. + .. caution:: + + It is a somewhat common bug for code to unintentionally use this attribute + when it is actually intended to get a :meth:`~timedelta.total_seconds` + value instead: + + .. doctest:: + + >>> from datetime import timedelta + >>> duration = timedelta(seconds=11235813) + >>> duration.days, duration.seconds + (130, 3813) + >>> duration.total_seconds() + 11235813.0 .. attribute:: timedelta.microseconds @@ -351,7 +365,7 @@ Supported operations: | | same value. (2) | +--------------------------------+-----------------------------------------------+ | ``-t1`` | Equivalent to ``timedelta(-t1.days, | -| | -t1.seconds*, -t1.microseconds)``, | +| | -t1.seconds, -t1.microseconds)``, | | | and to ``t1 * -1``. (1)(4) | +--------------------------------+-----------------------------------------------+ | ``abs(t)`` | Equivalent to ``+t`` when ``t.days >= 0``, | -- cgit v0.12