From d150e4abcfc13770c2d239878ed337fb53e51de5 Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith" Date: Tue, 1 Oct 2024 11:10:13 -0700 Subject: [PATCH] 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". --- 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 59e2dbd6847..64510a77c67 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``, |