gh-132642: document how to render human-readable `timedelta` objects (#133825)

diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
index 1ce2013f05da2eba8df2072900d01f9fd5824562..3470f42a6c622d02a1fc12939b245ae6225bd9cc 100644 (file)
--- a/Doc/library/datetime.rst
+++ b/Doc/library/datetime.rst
@@ -261,6 +261,22 @@ A :class:`timedelta` object represents a duration, the difference between two
       >>> (d.days, d.seconds, d.microseconds)
       (-1, 86399, 999999)
 
+   Since the string representation of :class:`!timedelta` objects can be confusing,
+   use the following recipe to produce a more readable format:
+
+   .. code-block:: pycon
+
+      >>> def pretty_timedelta(td):
+      ...     if td.days >= 0:
+      ...         return str(td)
+      ...     return f'-({-td!s})'
+      ...
+      >>> d = timedelta(hours=-1)
+      >>> str(d)  # not human-friendly
+      '-1 day, 23:00:00'
+      >>> pretty_timedelta(d)
+      '-(1:00:00)'
+
 
 Class attributes:
 

diff --git a/Lib/test/datetimetester.py b/Lib/test/datetimetester.py
index 55844ec35a90c94ed4820677dc79555e17dff1e8..d1882a310bbbb0c972a1b213cc29dc57fe091369 100644 (file)
--- a/Lib/test/datetimetester.py
+++ b/Lib/test/datetimetester.py
@@ -773,6 +773,9 @@ class TestTimeDelta(HarmlessMixedComparison, unittest.TestCase):
                    microseconds=999999)),
            "999999999 days, 23:59:59.999999")
 
+        # test the Doc/library/datetime.rst recipe
+        eq(f'-({-td(hours=-1)!s})', "-(1:00:00)")
+
     def test_repr(self):
         name = 'datetime.' + self.theclass.__name__
         self.assertEqual(repr(self.theclass(1)),