Merge branch 'main' into enforce-pdep6

Author: MarcoGorelli

ci/code_checks.sh

@@ -154,7 +154,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         -i "pandas.Series.dt.tz_convert PR01,PR02" \
         -i "pandas.Series.dt.tz_localize PR01,PR02" \
         -i "pandas.Series.dt.unit GL08" \
-        -i "pandas.Series.ge SA01" \
         -i "pandas.Series.gt SA01" \
         -i "pandas.Series.list.__getitem__ SA01" \
         -i "pandas.Series.list.flatten SA01" \
@@ -213,7 +212,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         -i "pandas.Timedelta.asm8 SA01" \
         -i "pandas.Timedelta.ceil SA01" \
         -i "pandas.Timedelta.components SA01" \
-        -i "pandas.Timedelta.days SA01" \
         -i "pandas.Timedelta.floor SA01" \
         -i "pandas.Timedelta.max PR02" \
         -i "pandas.Timedelta.min PR02" \

doc/source/user_guide/missing_data.rst

@@ -60,7 +60,7 @@ To detect these missing value, use the :func:`isna` or :func:`notna` methods.
 
 .. warning::
 
-   Equality compaisons between ``np.nan``, :class:`NaT`, and :class:`NA`
+   Equality comparisons between ``np.nan``, :class:`NaT`, and :class:`NA`
    do not act like ``None``
 
    .. ipython:: python

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, unit="D")
 
    # from a datetime.timedelta/np.timedelta64
    pd.Timedelta(datetime.timedelta(days=1, seconds=1))
@@ -94,7 +94,7 @@ 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), unit="D")
 
 .. warning::
     If a string or array of strings is passed as an input then the ``unit`` keyword

doc/source/whatsnew/v0.13.0.rst

@@ -523,13 +523,25 @@ Enhancements
   Using the new top-level ``to_timedelta``, you can convert a scalar or array from the standard
   timedelta format (produced by ``to_csv``) into a timedelta type (``np.timedelta64`` in ``nanoseconds``).
 
-  .. ipython:: python
+  .. code-block:: ipython
+
+     In [53]: pd.to_timedelta('1 days 06:05:01.00003')
+     Out[53]: Timedelta('1 days 06:05:01.000030')
+
+     In [54]: pd.to_timedelta('15.5us')
+     Out[54]: Timedelta('0 days 00:00:00.000015500')
+
+     In [55]: pd.to_timedelta(['1 days 06:05:01.00003', '15.5us', 'nan'])
+     Out[55]: TimedeltaIndex(['1 days 06:05:01.000030', '0 days 00:00:00.000015500', NaT], dtype='timedelta64[ns]', freq=None)
+
+     In [56]: pd.to_timedelta(np.arange(5), unit='s')
+     Out[56]:
+     TimedeltaIndex(['0 days 00:00:00', '0 days 00:00:01', '0 days 00:00:02',
+                     '0 days 00:00:03', '0 days 00:00:04'],
+                    dtype='timedelta64[ns]', freq=None)
 
-     pd.to_timedelta('1 days 06:05:01.00003')
-     pd.to_timedelta('15.5us')
-     pd.to_timedelta(['1 days 06:05:01.00003', '15.5us', 'nan'])
-     pd.to_timedelta(np.arange(5), unit='s')
-     pd.to_timedelta(np.arange(5), unit='d')
+     In [57]: pd.to_timedelta(np.arange(5), unit='d')
+     Out[57]: TimedeltaIndex(['0 days', '1 days', '2 days', '3 days', '4 days'], dtype='timedelta64[ns]', freq=None)
 
   A Series of dtype ``timedelta64[ns]`` can now be divided by another
   ``timedelta64[ns]`` object, or astyped to yield a ``float64`` dtyped Series. This

doc/source/whatsnew/v3.0.0.rst

@@ -273,6 +273,7 @@ Other Deprecations
 - Deprecated allowing non-keyword arguments in :meth:`Series.to_string` except ``buf``. (:issue:`57280`)
 - Deprecated behavior of :meth:`Series.dt.to_pytimedelta`, in a future version this will return a :class:`Series` containing python ``datetime.timedelta`` objects instead of an ``ndarray`` of timedelta; this matches the behavior of other :meth:`Series.dt` properties. (:issue:`57463`)
 - Deprecated parameter ``method`` in :meth:`DataFrame.reindex_like` / :meth:`Series.reindex_like` (:issue:`58667`)
+- Deprecated strings ``w``, ``d``, ``MIN``, ``MS``, ``US`` and ``NS`` denoting units in :class:`Timedelta` in favour of ``W``, ``D``, ``min``, ``ms``, ``us`` and ``ns`` (:issue:`59051`)
 - Deprecated using ``epoch`` date format in :meth:`DataFrame.to_json` and :meth:`Series.to_json`, use ``iso`` instead. (:issue:`57063`)
 
 .. ---------------------------------------------------------------------------

pandas/_libs/tslibs/dtypes.pxd

@@ -15,6 +15,7 @@ cdef dict c_OFFSET_TO_PERIOD_FREQSTR
 cdef dict c_PERIOD_TO_OFFSET_FREQSTR
 cdef dict c_OFFSET_RENAMED_FREQSTR
 cdef dict c_DEPR_ABBREVS
+cdef dict c_DEPR_UNITS
 cdef dict c_PERIOD_AND_OFFSET_DEPR_FREQSTR
 cdef dict attrname_to_abbrevs
 cdef dict npy_unit_to_attrname

pandas/_libs/tslibs/dtypes.pyx

@@ -346,6 +346,17 @@ cdef dict c_DEPR_ABBREVS = {
     "S": "s",
 }
 
+cdef dict c_DEPR_UNITS = {
+    "w": "W",
+    "d": "D",
+    "H": "h",
+    "MIN": "min",
+    "S": "s",
+    "MS": "ms",
+    "US": "us",
+    "NS": "ns",
+}
+
 cdef dict c_PERIOD_AND_OFFSET_DEPR_FREQSTR = {
     "w": "W",
     "MIN": "min",

pandas/_libs/tslibs/timedeltas.pyx

@@ -43,7 +43,7 @@ from pandas._libs.tslibs.conversion cimport (
     precision_from_unit,
 )
 from pandas._libs.tslibs.dtypes cimport (
-    c_DEPR_ABBREVS,
+    c_DEPR_UNITS,
     get_supported_reso,
     is_supported_unit,
     npy_unit_to_abbrev,
@@ -719,15 +719,15 @@ cpdef inline str parse_timedelta_unit(str unit):
         return "ns"
     elif unit == "M":
         return unit
-    elif unit in c_DEPR_ABBREVS:
+    elif unit in c_DEPR_UNITS:
         warnings.warn(
             f"\'{unit}\' is deprecated and will be removed in a "
-            f"future version. Please use \'{c_DEPR_ABBREVS.get(unit)}\' "
+            f"future version. Please use \'{c_DEPR_UNITS.get(unit)}\' "
             f"instead of \'{unit}\'.",
             FutureWarning,
             stacklevel=find_stack_level(),
         )
-        unit = c_DEPR_ABBREVS[unit]
+        unit = c_DEPR_UNITS[unit]
     try:
         return timedelta_abbrevs[unit.lower()]
     except KeyError:
@@ -1078,10 +1078,22 @@ cdef class _Timedelta(timedelta):
         """
         Returns the days of the timedelta.
 
+        The `days` attribute of a `pandas.Timedelta` object provides the number
+        of days represented by the `Timedelta`. This is useful for extracting
+        the day component from a `Timedelta` that may also include hours, minutes,
+        seconds, and smaller time units. This attribute simplifies the process
+        of working with durations where only the day component is of interest.
+
         Returns
         -------
         int
 
+        See Also
+        --------
+        Timedelta.seconds : Returns the seconds component of the timedelta.
+        Timedelta.microseconds : Returns the microseconds component of the timedelta.
+        Timedelta.total_seconds : Returns the total duration in seconds.
+
         Examples
         --------
         >>> td = pd.Timedelta(1, "d")
@@ -1811,6 +1823,11 @@ class Timedelta(_Timedelta):
             Values `H`, `T`, `S`, `L`, `U`, and `N` are deprecated in favour
             of the values `h`, `min`, `s`, `ms`, `us`, and `ns`.
 
+        .. deprecated:: 3.0.0
+
+            Allowing the values `w`, `d`, `MIN`, `MS`, `US` and `NS` to denote units
+            are deprecated in favour of the values `W`, `D`, `min`, `ms`, `us` and `ns`.
+
     **kwargs
         Available kwargs: {days, seconds, microseconds,
         milliseconds, minutes, hours, weeks}.

pandas/core/arrays/timedeltas.py

@@ -746,7 +746,7 @@ def total_seconds(self) -> npt.NDArray[np.float64]:
         --------
         **Series**
 
-        >>> s = pd.Series(pd.to_timedelta(np.arange(5), unit="d"))
+        >>> s = pd.Series(pd.to_timedelta(np.arange(5), unit="D"))
         >>> s
         0   0 days
         1   1 days
@@ -765,7 +765,7 @@ def total_seconds(self) -> npt.NDArray[np.float64]:
 
         **TimedeltaIndex**
 
-        >>> idx = pd.to_timedelta(np.arange(5), unit="d")
+        >>> idx = pd.to_timedelta(np.arange(5), unit="D")
         >>> idx
         TimedeltaIndex(['0 days', '1 days', '2 days', '3 days', '4 days'],
                        dtype='timedelta64[ns]', freq=None)
@@ -809,7 +809,7 @@ def to_pytimedelta(self) -> npt.NDArray[np.object_]:
     --------
     For Series:
 
-    >>> ser = pd.Series(pd.to_timedelta([1, 2, 3], unit='d'))
+    >>> ser = pd.Series(pd.to_timedelta([1, 2, 3], unit='D'))
     >>> ser
     0   1 days
     1   2 days

pandas/core/indexes/accessors.py

@@ -459,7 +459,7 @@ def to_pytimedelta(self) -> np.ndarray:
 
         Examples
         --------
-        >>> s = pd.Series(pd.to_timedelta(np.arange(5), unit="d"))
+        >>> s = pd.Series(pd.to_timedelta(np.arange(5), unit="D"))
         >>> s
         0   0 days
         1   1 days