[3.14] gh-132642: document how to render human-readable timedelta objects (GH-133825) (#133837)

miss-islington · KentaroJay · web-flow · commit 13c94d040102 · 2025-05-10T16:00:36.000Z
gh-132642: document how to render human-readable `timedelta` objects (GH-133825) (cherry picked from commit efcc42b) Co-authored-by: Kentaro Jay Takahashi <64148935+KentaroJay@users.noreply.github.com>
diff --git 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
@@ -773,6 +773,9 @@ def test_str(self):
                    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)),
