ENH: Timedelta isoformat

Author: TomAugspurger

doc/source/timedeltas.rst

@@ -310,6 +310,16 @@ similarly to the ``Series``. These are the *displayed* values of the ``Timedelta
    td.dt.components
    td.dt.components.seconds
 
+You can convert a ``Timedelta`` to an ISO 8601 Duration string with the
+``.isoformat`` method
+
+.. ipython:: python
+    pd.Timedelta(days=6, minutes=50, seconds=3,
+                 milliseconds=10, microseconds=10,
+                 nanoseconds=12).isoformat()
+
+.. _ISO 8601 duration: https://en.wikipedia.org/wiki/ISO_8601#Durations
+
 .. _timedeltas.index:
 
 TimedeltaIndex

doc/source/whatsnew/v0.20.0.txt

@@ -91,6 +91,22 @@ support for bz2 compression in the python 2 c-engine improved (:issue:`14874`).
    df = pd.read_table(url, compression='bz2')  # explicitly specify compression
    df.head(2)
 
+
+.. _whatsnew_0200.enhancements.timedelta_isoformat:
+
+Timedelta isoformat
+^^^^^^^^^^^^^^^^^^^
+
+Added a Timedelta.isoformat method for formatting Timedeltas as an
+`ISO 8601 duration`_ (:issue:`15136`)
+
+.. _ISO 8601 duration: https://en.wikipedia.org/wiki/ISO_8601#Durations
+
+.. ipython:: python
+   td = pd.Timedelta(days=6, minutes=50, seconds=3,
+                     milliseconds=10, microseconds=10, nanoseconds=12)
+   td.isoformat()
+
 .. _whatsnew_0200.enhancements.other:
 
 Other enhancements
@@ -369,4 +385,4 @@ Bug Fixes
 
 - Bug in ``pd.read_csv()`` for the C engine where ``usecols`` were being indexed incorrectly with ``parse_dates`` (:issue:`14792`)
 
-- Bug in ``Series.dt.round`` inconsistent behaviour on NAT's with different arguments (:issue:`14940`)
+- Bug in ``Series.dt.round`` inconsistent behaviour on NAT's with different arguments (:issue:`14940`)

pandas/tseries/tests/test_timedeltas.py

@@ -1347,6 +1347,45 @@ def test_components(self):
         self.assertFalse(result.iloc[0].isnull().all())
         self.assertTrue(result.iloc[1].isnull().all())
 
+    def test_isoformat(self):
+        td = Timedelta(days=6, minutes=50, seconds=3,
+                       milliseconds=10, microseconds=10, nanoseconds=12)
+        expected = 'P6DT0H50M3.010010012S'
+        result = td.isoformat()
+        self.assertEqual(result, expected)
+
+        td = Timedelta(days=4, hours=12, minutes=30, seconds=5)
+        result = td.isoformat()
+        expected = 'P4DT12H30M5S'
+        self.assertEqual(result, expected)
+
+        td = Timedelta(nanoseconds=123)
+        result = td.isoformat()
+        expected = 'P0DT0H0M0.000000123S'
+        self.assertEqual(result, expected)
+
+        # trim nano
+        td = Timedelta(microseconds=10)
+        result = td.isoformat()
+        expected = 'P0DT0H0M0.00001S'
+        self.assertEqual(result, expected)
+
+        # trim micro
+        td = Timedelta(milliseconds=1)
+        result = td.isoformat()
+        expected = 'P0DT0H0M0.001S'
+        self.assertEqual(result, expected)
+
+        # NaT
+        result = Timedelta('NaT').isoformat()
+        expected = 'NaT'
+        self.assertEqual(result, expected)
+
+        # don't strip every 0
+        result = Timedelta(minutes=1).isoformat()
+        expected = 'P0DT0H1M0S'
+        self.assertEqual(result, expected)
+
     def test_constructor(self):
         expected = TimedeltaIndex(['1 days', '1 days 00:00:05', '2 days',
                                    '2 days 00:00:02', '0 days 00:00:03'])

pandas/tslib.pyx

@@ -2966,6 +2966,54 @@ class Timedelta(_Timedelta):
         """
         return 1e-9 *self.value
 
+    def isoformat(self):
+        """
+        Format Timedelta as ISO 8601 Duration like
+        `P[n]Y[n]M[n]DT[n]H[n]M[n]S`, where the `[n]`s are replaced by the
+        values. See https://en.wikipedia.org/wiki/ISO_8601#Durations
+
+        Returns
+        -------
+        formatted : str
+
+        Notes
+        -----
+        The longest component is days, whose value may be larger than
+        365.
+        Every component is always included, even if its value is 0.
+        Pandas uses nanosecond precision, so up to 9 decimal places may
+        be included in the seconds component.
+        Trailing 0's are removed from the seconds component after the decimal.
+        We do not 0 pad components, so it's `...T5H...`, not `...T05H...`
+
+        Examples
+        --------
+        >>> td = pd.Timedelta(days=6, minutes=50, seconds=3,
+        ...                   milliseconds=10, microseconds=10, nanoseconds=12)
+        >>> td.isoformat()
+        'P6DT0H50M3.010010012S'
+        >>> pd.Timedelta(hours=1, seconds=10).isoformat()
+        'P0DT0H0M10S'
+        >>> pd.Timedelta(hours=1, seconds=10).isoformat()
+        'P0DT0H0M10S'
+        >>> pd.Timedelta(days=500.5).isoformat()
+        'P500DT12H0MS'
+
+        See Also
+        --------
+        Timestamp.isoformat
+        """
+        components = self.components
+        seconds = '{}.{:0>3}{:0>3}{:0>3}'.format(components.seconds,
+                                                 components.milliseconds,
+                                                 components.microseconds,
+                                                 components.nanoseconds)
+        # Trim unnecessary 0s, 1.000000000 -> 1
+        seconds = seconds.rstrip('0').rstrip('.')
+        tpl = 'P{td.days}DT{td.hours}H{td.minutes}M{seconds}S'.format(
+            td=components, seconds=seconds)
+        return tpl
+
     def __setstate__(self, state):
         (value) = state
         self.value = value