DEPR: Deprecate box kwarg for to_timedelta and to_datetime

Author: Chris Bertinato

doc/source/whatsnew/v0.24.0.rst

@@ -1152,6 +1152,7 @@ Deprecations
 - Passing a string alias like ``'datetime64[ns, UTC]'`` as the ``unit`` parameter to :class:`DatetimeTZDtype` is deprecated. Use :class:`DatetimeTZDtype.construct_from_string` instead (:issue:`23990`).
 - In :meth:`Series.where` with Categorical data, providing an ``other`` that is not present in the categories is deprecated. Convert the categorical to a different dtype or add the ``other`` to the categories first (:issue:`24077`).
 - :meth:`Series.clip_lower`, :meth:`Series.clip_upper`, :meth:`DataFrame.clip_lower` and :meth:`DataFrame.clip_upper` are deprecated and will be removed in a future version. Use ``Series.clip(lower=threshold)``, ``Series.clip(upper=threshold)`` and the equivalent ``DataFrame`` methods (:issue:`24203`)
+- The functions :func:`pandas.to_datetime` and :func:`pandas.to_timedelta` have deprecated the ``box`` keyword. Use :attr:`Series.values` and :meth:`Timestamp.to_datetime64`/:meth:`Timedelta.to_timedelta64` instead to get an ndarray of values or ``numpy.timestamp64``/``numpy.timedelta64``, respectively (:issue:`24416`).
 
 .. _whatsnew_0240.deprecations.datetimelike_int_ops:
 

pandas/core/tools/datetimes.py

@@ -20,6 +20,8 @@
 from pandas import compat
 from pandas.core import algorithms
 
+from pandas.util._decorators import deprecate_kwarg
+
 
 def _guess_datetime_format_for_array(arr, **kwargs):
     # Try to guess the format based on the first non-NaN element
@@ -388,6 +390,7 @@ def _adjust_to_origin(arg, origin, unit):
     return arg
 
 
+@deprecate_kwarg(old_arg_name='box', new_arg_name=None)
 def to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False,
                 utc=None, box=True, format=None, exact=True,
                 unit=None, infer_datetime_format=False, origin='unix',
@@ -434,6 +437,12 @@ def to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False,
 
         - If True returns a DatetimeIndex or Index-like object
         - If False returns ndarray of values.
+
+        .. deprecated:: 0.24.0
+            Use :attr:`Series.values` or :meth:`Timestamp.to_datetime64`
+            instead to get an ndarray of values or numpy.datetime64,
+            respectively.
+
     format : string, default None
         strftime to parse time, eg "%d/%m/%Y", note that "%f" will parse
         all the way up to nanoseconds.

pandas/core/tools/timedeltas.py

@@ -14,7 +14,10 @@
 import pandas as pd
 from pandas.core.arrays.timedeltas import sequence_to_td64ns
 
+from pandas.util._decorators import deprecate_kwarg
 
+
+@deprecate_kwarg(old_arg_name='box', new_arg_name=None)
 def to_timedelta(arg, unit='ns', box=True, errors='raise'):
     """
     Convert argument to timedelta.
@@ -40,6 +43,12 @@ def to_timedelta(arg, unit='ns', box=True, errors='raise'):
         - If True returns a Timedelta/TimedeltaIndex of the results.
         - If False returns a numpy.timedelta64 or numpy.darray of
           values of dtype timedelta64[ns].
+
+        .. deprecated:: 0.24.0
+            Use :attr:`Series.values` or :meth:`Timedelta.to_timedelta64`
+            instead to get an ndarray of values or numpy.timedelta64,
+            respectively.
+
     errors : {'ignore', 'raise', 'coerce'}, default 'raise'
         - If 'raise', then invalid parsing will raise an exception.
         - If 'coerce', then invalid parsing will be set as NaT.

pandas/tests/indexes/datetimes/test_tools.py

@@ -665,6 +665,16 @@ def test_timestamp_utc_true(self, ts, expected):
         result = to_datetime(ts, utc=True)
         assert result == expected
 
+    def test_to_datetime_box_deprecated(self):
+        expected = np.datetime64('2018-09-09')
+
+        # Deprecated - see GH24416
+        with tm.assert_produces_warning(FutureWarning):
+            pd.to_datetime(expected, box=False)
+
+        result = pd.to_datetime(expected).to_datetime64()
+        assert result == expected
+
 
 class TestToDatetimeUnit(object):
     @pytest.mark.parametrize('cache', [True, False])

pandas/tests/indexes/timedeltas/test_tools.py

@@ -172,3 +172,13 @@ def test_to_timedelta_on_missing_values(self):
 
         actual = pd.to_timedelta(pd.NaT)
         assert actual.value == timedelta_NaT.astype('int64')
+
+    def test_to_timedelta_box_deprecated(self):
+        result = np.timedelta64(0, 'ns')
+
+        # Deprecated - see GH24416
+        with tm.assert_produces_warning(FutureWarning):
+            to_timedelta(0, box=False)
+
+        expected = to_timedelta(0).to_timedelta64()
+        assert result == expected