DEPR: unit->input_unit in to_datetime, to_timedelta

asv_bench/benchmarks/categoricals.py

@@ -79,7 +79,8 @@ def setup(self):
             "int": np.random.randint(2**16, size=154),
             "float": sys.maxsize * np.random.random((38,)),
             "timestamp": [
-                pd.Timestamp(x, unit="s") for x in np.random.randint(2**18, size=578)
+                pd.Timestamp(x, input_unit="s")
+                for x in np.random.randint(2**18, size=578)
             ],
         }
 

asv_bench/benchmarks/groupby.py

@@ -1134,7 +1134,7 @@ def setup(self):
         index = MultiIndex.from_product(
             [
                 np.arange(num_groups),
-                to_timedelta(np.arange(num_timedeltas), unit="s"),
+                to_timedelta(np.arange(num_timedeltas), input_unit="s"),
             ],
             names=["groups", "timedeltas"],
         )

asv_bench/benchmarks/inference.py

@@ -118,22 +118,22 @@ def setup(self):
     # speed of int64, uint64 and float64 paths should be comparable
 
     def time_nanosec_int64(self):
-        to_datetime(self.ts_nanosec, unit="ns")
+        to_datetime(self.ts_nanosec, input_unit="ns")
 
     def time_nanosec_uint64(self):
-        to_datetime(self.ts_nanosec_uint, unit="ns")
+        to_datetime(self.ts_nanosec_uint, input_unit="ns")
 
     def time_nanosec_float64(self):
-        to_datetime(self.ts_nanosec_float, unit="ns")
+        to_datetime(self.ts_nanosec_float, input_unit="ns")
 
     def time_sec_uint64(self):
-        to_datetime(self.ts_sec_uint, unit="s")
+        to_datetime(self.ts_sec_uint, input_unit="s")
 
     def time_sec_int64(self):
-        to_datetime(self.ts_sec, unit="s")
+        to_datetime(self.ts_sec, input_unit="s")
 
     def time_sec_float64(self):
-        to_datetime(self.ts_sec_float, unit="s")
+        to_datetime(self.ts_sec_float, input_unit="s")
 
 
 class ToDatetimeYYYYMMDD:
@@ -250,10 +250,10 @@ def setup(self, cache):
         self.dup_string_with_tz = ["2000-02-11 15:00:00-0800"] * N
 
     def time_unique_seconds_and_unit(self, cache):
-        to_datetime(self.unique_numeric_seconds, unit="s", cache=cache)
+        to_datetime(self.unique_numeric_seconds, input_unit="s", cache=cache)
 
     def time_dup_seconds_and_unit(self, cache):
-        to_datetime(self.dup_numeric_seconds, unit="s", cache=cache)
+        to_datetime(self.dup_numeric_seconds, input_unit="s", cache=cache)
 
     def time_dup_string_dates(self, cache):
         to_datetime(self.dup_string_dates, cache=cache)
@@ -275,7 +275,7 @@ def setup(self):
             self.str_seconds.append(f"00:00:{i:02d}")
 
     def time_convert_int(self):
-        to_timedelta(self.ints, unit="s")
+        to_timedelta(self.ints, input_unit="s")
 
     def time_convert_string_days(self):
         to_timedelta(self.str_days)

asv_bench/benchmarks/tslibs/timedelta.py

@@ -14,13 +14,13 @@ class TimedeltaConstructor:
     def setup(self):
         self.nptimedelta64 = np.timedelta64(3600)
         self.dttimedelta = datetime.timedelta(seconds=3600)
-        self.td = Timedelta(3600, unit="s")
+        self.td = Timedelta(3600, input_unit="s")
 
     def time_from_int(self):
         Timedelta(123456789)
 
     def time_from_unit(self):
-        Timedelta(1, unit="D")
+        Timedelta(1, input_unit="D")
 
     def time_from_components(self):
         Timedelta(

doc/source/user_guide/timedeltas.rst

@@ -35,7 +35,7 @@ You can construct a ``Timedelta`` scalar through various arguments, including `I
    pd.Timedelta(days=1, seconds=1)
 
    # integers with a unit
-   pd.Timedelta(1, unit="D")
+   pd.Timedelta(1, input_unit="D")
 
    # from a datetime.timedelta/np.timedelta64
    pd.Timedelta(datetime.timedelta(days=1, seconds=1))
@@ -93,8 +93,8 @@ is numeric:
 
 .. ipython:: python
 
-   pd.to_timedelta(np.arange(5), unit="s")
-   pd.to_timedelta(np.arange(5), unit="D")
+   pd.to_timedelta(np.arange(5), input_unit="s")
+   pd.to_timedelta(np.arange(5), input_unit="D")
 
 .. warning::
     If a string or array of strings is passed as an input then the ``unit`` keyword
@@ -199,7 +199,7 @@ You can fillna on timedeltas, passing a timedelta to get a particular value.
 .. ipython:: python
 
    y.fillna(pd.Timedelta(0))
-   y.fillna(pd.Timedelta(10, unit="s"))
+   y.fillna(pd.Timedelta(10, input_unit="s"))
    y.fillna(pd.Timedelta("-1 days, 00:00:05"))
 
 You can also negate, multiply and use ``abs`` on ``Timedeltas``:

doc/source/user_guide/timeseries.rst

@@ -307,25 +307,25 @@ Epoch timestamps
 ~~~~~~~~~~~~~~~~
 
 pandas supports converting integer or float epoch times to ``Timestamp`` and
-``DatetimeIndex``. The default unit is nanoseconds, since that is how ``Timestamp``
-objects are stored internally. However, epochs are often stored in another ``unit``
+``DatetimeIndex``. The default input_unit is nanoseconds, since that is how ``Timestamp``
+objects are stored internally. However, epochs are often stored in another ``input_unit``
 which can be specified. These are computed from the starting point specified by the
 ``origin`` parameter.
 
 .. ipython:: python
 
    pd.to_datetime(
-       [1349720105, 1349806505, 1349892905, 1349979305, 1350065705], unit="s"
+       [1349720105, 1349806505, 1349892905, 1349979305, 1350065705], input_unit="s"
    )
 
    pd.to_datetime(
        [1349720105100, 1349720105200, 1349720105300, 1349720105400, 1349720105500],
-       unit="ms",
+       input_unit="ms",
    )
 
 .. note::
 
-   The ``unit`` parameter does not use the same strings as the ``format`` parameter
+   The ``input_unit`` parameter does not use the same strings as the ``format`` parameter
    that was discussed :ref:`above<timeseries.converting.format>`. The
    available units are listed on the documentation for :func:`pandas.to_datetime`.
 
@@ -353,8 +353,8 @@ as timezone-naive timestamps and then localize to the appropriate timezone:
 
    .. ipython:: python
 
-      pd.to_datetime([1490195805.433, 1490195805.433502912], unit="s")
-      pd.to_datetime(1490195805433502912, unit="ns")
+      pd.to_datetime([1490195805.433, 1490195805.433502912], input_unit="s")
+      pd.to_datetime(1490195805433502912, input_unit="ns")
 
 .. seealso::
 
@@ -389,14 +389,14 @@ of a ``DatetimeIndex``. For example, to use 1960-01-01 as the starting date:
 
 .. ipython:: python
 
-   pd.to_datetime([1, 2, 3], unit="D", origin=pd.Timestamp("1960-01-01"))
+   pd.to_datetime([1, 2, 3], input_unit="D", origin=pd.Timestamp("1960-01-01"))
 
 The default is set at ``origin='unix'``, which defaults to ``1970-01-01 00:00:00``.
 Commonly called 'unix epoch' or POSIX time.
 
 .. ipython:: python
 
-   pd.to_datetime([1, 2, 3], unit="D")
+   pd.to_datetime([1, 2, 3], input_unit="D")
 
 .. _timeseries.daterange:
 
@@ -2633,7 +2633,7 @@ Transform nonexistent times to ``NaT`` or shift the times.
     dti
     dti.tz_localize("Europe/Warsaw", nonexistent="shift_forward")
     dti.tz_localize("Europe/Warsaw", nonexistent="shift_backward")
-    dti.tz_localize("Europe/Warsaw", nonexistent=pd.Timedelta(1, unit="h"))
+    dti.tz_localize("Europe/Warsaw", nonexistent=pd.Timedelta(1, input_unit="h"))
     dti.tz_localize("Europe/Warsaw", nonexistent="NaT")
 
 

doc/source/whatsnew/v0.20.0.rst

@@ -142,13 +142,15 @@ from where to compute the resulting timestamps when parsing numerical values wit
 For example, with 1960-01-01 as the starting date:
 
 .. ipython:: python
+   :okwarning:
 
    pd.to_datetime([1, 2, 3], unit='D', origin=pd.Timestamp('1960-01-01'))
 
 The default is set at ``origin='unix'``, which defaults to ``1970-01-01 00:00:00``, which is
 commonly called 'unix epoch' or POSIX time. This was the previous default, so this is a backward compatible change.
 
 .. ipython:: python
+   :okwarning:
 
    pd.to_datetime([1, 2, 3], unit='D')
 

doc/source/whatsnew/v3.0.0.rst

@@ -717,6 +717,7 @@ Other Deprecations
 - Deprecated allowing ``fill_value`` that cannot be held in the original dtype (excepting NA values for integer and bool dtypes) in :meth:`Series.unstack` and :meth:`DataFrame.unstack` (:issue:`12189`, :issue:`53868`)
 - Deprecated allowing ``fill_value`` that cannot be held in the original dtype (excepting NA values for integer and bool dtypes) in :meth:`Series.shift` and :meth:`DataFrame.shift` (:issue:`53802`)
 - Deprecated slicing on a :class:`Series` or :class:`DataFrame` with a :class:`DatetimeIndex` using a ``datetime.date`` object, explicitly cast to :class:`Timestamp` instead (:issue:`35830`)
+- Deprecated the ``unit`` keyword in :meth:`to_datetime` and :meth:`to_timedelta`, use ``input_unit`` instead (:issue:`62097`)
 
 .. ---------------------------------------------------------------------------
 .. _whatsnew_300.prior_deprecations:

pandas/_libs/tslibs/conversion.pyx

@@ -117,7 +117,7 @@ def cast_from_unit_vectorized(
             #  but not clear what 2.5 "M" corresponds to, so we will
             #  disallow that case.
             raise ValueError(
-                f"Conversion of non-round float with unit={unit} "
+                f"Conversion of non-round float with input_unit={unit} "
                 "is ambiguous"
             )
 
@@ -194,7 +194,7 @@ cdef int64_t cast_from_unit(
             #  but not clear what 2.5 "M" corresponds to, so we will
             #  disallow that case.
             raise ValueError(
-                f"Conversion of non-round float with unit={unit} "
+                f"Conversion of non-round float with input_unit={unit} "
                 "is ambiguous"
             )
         # GH#47266 go through np.datetime64 to avoid weird results e.g. with "Y"

pandas/_libs/tslibs/offsets.pyx

@@ -5404,7 +5404,7 @@ cpdef to_offset(freq, bint is_period=False):
                     # For these prefixes, we have something like "3h" or
                     #  "2.5min", so we can construct a Timedelta with the
                     #  matching unit and get our offset from delta_to_tick
-                    td = Timedelta(1, unit=name)
+                    td = Timedelta(1, input_unit=name)
                     off = delta_to_tick(td)
                     offset = off * float(stride)
                     if n != 0:

pandas/_libs/tslibs/timedeltas.pyi

@@ -95,6 +95,8 @@ class Timedelta(timedelta):
     def __new__(  # type: ignore[misc]
         cls: type[Self],
         value=...,
+        input_unit: str | None = ...,
+        *,
         unit: str | None = ...,
         **kwargs: float | np.integer | np.floating,
     ) -> Self | NaTType: ...