From 09327f36754bf34e98debf757e812f20c84d740f Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith [Google LLC]" Date: Mon, 30 Sep 2024 23:23:28 +0000 Subject: [PATCH 1/3] Highlight `timedelta.seconds` vs `.total_seconds()` in docs. --- Doc/library/datetime.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index 59e2dbd6847538f..b730753b60f214b 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -295,6 +295,11 @@ Instance attributes (read-only): Between 0 and 86,399 inclusive. + .. warning:: + + It is a somewhat common bug for code to unintentionally use this attribute + when it actually intended to get a :meth:`~timedelta.total_seconds` value + instead. .. attribute:: timedelta.microseconds From 10aab8464575b44d52d06ac53047e7fd5a040689 Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith [Google LLC]" Date: Tue, 1 Oct 2024 16:55:33 +0000 Subject: [PATCH 2/3] add an example, fix a later typo. --- Doc/library/datetime.rst | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index b730753b60f214b..e9631b682bff64e 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -299,7 +299,16 @@ Instance attributes (read-only): It is a somewhat common bug for code to unintentionally use this attribute when it actually intended to get a :meth:`~timedelta.total_seconds` value - instead. + instead: + + .. doctest:: + + >>> from datetime import timedelta + >>> duration = timedelta(seconds=11235813) + >>> duration.days, duration.seconds + (130, 3813) + >>> duration.total_seconds() + 11235813.0 .. attribute:: timedelta.microseconds @@ -356,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``, | From 86dba0f676cef9a34eb3a0830f393cd6a6681c11 Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith [Google LLC]" Date: Tue, 1 Oct 2024 17:46:44 +0000 Subject: [PATCH 3/3] use caution instead, add missing is. --- Doc/library/datetime.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index e9631b682bff64e..64510a77c67c118 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -295,11 +295,11 @@ Instance attributes (read-only): Between 0 and 86,399 inclusive. - .. warning:: + .. caution:: It is a somewhat common bug for code to unintentionally use this attribute - when it actually intended to get a :meth:`~timedelta.total_seconds` value - instead: + when it is actually intended to get a :meth:`~timedelta.total_seconds` + value instead: .. doctest::