ENH: enhanced the Timedelta.total_seconds() override for compatibility reasons

DOC: updated the docstring of the `Timedelta.total_seconds()`
TST: updated respective testing

Author: deponovo

pandas/_libs/tslibs/nattype.pyx

@@ -442,7 +442,32 @@ class NaTType(_NaT):
         Monday == 1 ... Sunday == 7.
         """,
     )
-    total_seconds = _make_nan_func("total_seconds", timedelta.total_seconds.__doc__)
+    total_seconds = _make_nan_func(
+        "total_seconds",
+        """
+        Total seconds in the duration with default us precision
+        (for compatibility with `datetime.timedelta`).
+
+        Parameters
+        ----------
+        ns_precision : bool, default False
+            Return the duration with ns precision.
+
+        Examples
+        --------
+        >>> td = pd.Timedelta(days=6, minutes=50, seconds=3,
+        ...                   milliseconds=10, microseconds=10, nanoseconds=12)
+        >>> td
+        Timedelta('6 days 00:50:03.010010012')
+
+        >>> td.total_seconds()
+        521403.01001
+
+        >>> td.total_seconds(ns_precision=True)
+        521403.010010012
+
+        """
+    )
     month_name = _make_nan_func(
         "month_name",
         """

pandas/_libs/tslibs/timedeltas.pyx

@@ -1539,9 +1539,34 @@ class Timedelta(_Timedelta):
         div = other // self
         return div, other - div * self
 
-    def total_seconds(self):
-        """Total seconds in the duration."""
-        return self.value / 1_000_000_000
+    # GH45129
+    def total_seconds(self, *, ns_precision=False) -> float:
+        """
+        Total seconds in the duration with default us precision
+        (for compatibility with `datetime.timedelta`).
+
+        Parameters
+        ----------
+        ns_precision : bool, default False
+            Return the duration with ns precision.
+
+        Examples
+        --------
+        >>> td = pd.Timedelta(days=6, minutes=50, seconds=3,
+        ...                   milliseconds=10, microseconds=10, nanoseconds=12)
+        >>> td
+        Timedelta('6 days 00:50:03.010010012')
+
+        >>> td.total_seconds()
+        521403.01001
+
+        >>> td.total_seconds(ns_precision=True)
+        521403.010010012
+
+        """
+        if ns_precision:
+            return self.value / 1_000_000_000
+        return super().total_seconds()
 
 
 cdef bint is_any_td_scalar(object obj):

pandas/tests/tslibs/test_timedeltas.py

@@ -50,19 +50,20 @@ def test_huge_nanoseconds_overflow():
 
 # GH40946
 @pytest.mark.parametrize(
-    "obj, expected",
+    "obj, expected_ns, expected_us",
     [
-        (Timedelta("1us"), 1e-6),
-        (Timedelta("500ns"), 5e-7),
-        (Timedelta(nanoseconds=500), 5e-7),
-        (Timedelta(seconds=1, nanoseconds=500), 1 + 5e-7),
-        # require GH45108
-        # (Timedelta(seconds=1e-9, milliseconds=1e-5, microseconds=1e-1), 111e-9),
-        # (
-        #     Timedelta(days=1, seconds=1e-9, milliseconds=1e-5, microseconds=1e-1),
-        #     24 * 3600 + 111e-9
-        # )
+        (Timedelta("1us"), 1e-6, 1e-6),
+        (Timedelta("500ns"), 5e-7, 0.0),
+        (Timedelta(nanoseconds=500), 5e-7, 0.0),
+        (Timedelta(seconds=1, nanoseconds=500), 1 + 5e-7, 1.0),
+        (Timedelta(seconds=1e-9, milliseconds=1e-5, microseconds=1e-1), 111e-9, 0.0),
+        (
+            Timedelta(days=1, seconds=1e-9, milliseconds=1e-5, microseconds=1e-1),
+            24 * 3600 + 111e-9,
+            24 * 3600,
+        ),
     ],
 )
-def test_total_seconds(obj, expected):
-    assert obj.total_seconds() == expected
+def test_total_seconds(obj: Timedelta, expected_ns, expected_us):
+    assert obj.total_seconds() == expected_us
+    assert obj.total_seconds(ns_precision=True) == expected_ns