https://github.com/python/cpython/commit/d150e4abcfc13770c2d239878ed337fb53e51de5
commit: d150e4abcfc13770c2d239878ed337fb53e51de5
branch: main
author: Gregory P. Smith <[email protected]>
committer: gpshead <[email protected]>
date: 2024-10-01T18:10:13Z
summary:
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".
files:
M Doc/library/datetime.rst
diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
index 59e2dbd6847538..64510a77c67c11 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``,
|
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: [email protected]
