Merge branch 'main' into free-threaded-wheels

Author: mroeschke

doc/source/user_guide/groupby.rst

@@ -668,8 +668,9 @@ column, which produces an aggregated result with a hierarchical column index:
    grouped[["C", "D"]].agg(["sum", "mean", "std"])
 
 
-The resulting aggregations are named after the functions themselves. If you
-need to rename, then you can add in a chained operation for a ``Series`` like this:
+The resulting aggregations are named after the functions themselves.
+
+For a ``Series``, if you need to rename, you can add in a chained operation like this:
 
 .. ipython:: python
 
@@ -679,8 +680,19 @@ need to rename, then you can add in a chained operation for a ``Series`` like th
        .rename(columns={"sum": "foo", "mean": "bar", "std": "baz"})
    )
 
+Or, you can simply pass a list of tuples each with the name of the new column and the aggregate function:
+
+.. ipython:: python
+
+   (
+      grouped["C"]
+      .agg([("foo", "sum"), ("bar", "mean"), ("baz", "std")])
+   )
+
 For a grouped ``DataFrame``, you can rename in a similar manner:
 
+By chaining ``rename`` operation,
+
 .. ipython:: python
 
    (
@@ -689,6 +701,16 @@ For a grouped ``DataFrame``, you can rename in a similar manner:
        )
    )
 
+Or, passing a list of tuples,
+
+.. ipython:: python
+
+   (
+      grouped[["C", "D"]].agg(
+         [("foo", "sum"), ("bar", "mean"), ("baz", "std")]
+      )
+   )
+
 .. note::
 
    In general, the output column names should be unique, but pandas will allow

doc/source/user_guide/text.rst

@@ -204,7 +204,7 @@ and replacing any remaining whitespaces with underscores:
 
 .. warning::
 
-    The type of the Series is inferred and the allowed types (i.e. strings).
+    The type of the Series is inferred and is one among the allowed types (i.e. strings).
 
     Generally speaking, the ``.str`` accessor is intended to work only on strings. With very few
     exceptions, other uses are not supported, and may be disabled at a later point.

doc/source/whatsnew/v3.0.0.rst

@@ -507,7 +507,7 @@ Datetimelike
 - Bug in :meth:`Dataframe.agg` with df with missing values resulting in IndexError (:issue:`58810`)
 - Bug in :meth:`DatetimeIndex.is_year_start` and :meth:`DatetimeIndex.is_quarter_start` does not raise on Custom business days frequencies bigger then "1C" (:issue:`58664`)
 - Bug in :meth:`DatetimeIndex.is_year_start` and :meth:`DatetimeIndex.is_quarter_start` returning ``False`` on double-digit frequencies (:issue:`58523`)
-- Bug in :meth:`DatetimeIndex.union` when ``unit`` was non-nanosecond (:issue:`59036`)
+- Bug in :meth:`DatetimeIndex.union` and :meth:`DatetimeIndex.intersection` when ``unit`` was non-nanosecond (:issue:`59036`)
 - Bug in :meth:`Series.dt.microsecond` producing incorrect results for pyarrow backed :class:`Series`. (:issue:`59154`)
 - Bug in :meth:`to_datetime` not respecting dayfirst if an uncommon date string was passed. (:issue:`58859`)
 - Bug in setting scalar values with mismatched resolution into arrays with non-nanosecond ``datetime64``, ``timedelta64`` or :class:`DatetimeTZDtype` incorrectly truncating those scalars (:issue:`56410`)

pandas/_libs/tslibs/dtypes.pyx

@@ -359,6 +359,8 @@ cdef dict c_PERIOD_AND_OFFSET_DEPR_FREQSTR = {
     "b": "B",
     "c": "C",
     "MIN": "min",
+    "US": "us",
+    "NS": "ns",
 }
 
 cdef str INVALID_FREQ_ERR_MSG = "Invalid frequency: {0}"

pandas/_libs/tslibs/offsets.pyx

@@ -4697,13 +4697,9 @@ _lite_rule_alias = {
     "BYS": "BYS-JAN",  # BYearBegin(month=1),
 
     "Min": "min",
-    "min": "min",
-    "ms": "ms",
-    "us": "us",
-    "ns": "ns",
 }
 
-_dont_uppercase = {"h", "bh", "cbh", "MS", "ms", "s"}
+_dont_uppercase = {"min", "h", "bh", "cbh", "s", "ms", "us", "ns"}
 
 
 INVALID_FREQ_ERR_MSG = "Invalid frequency: {0}"
@@ -4713,6 +4709,37 @@ INVALID_FREQ_ERR_MSG = "Invalid frequency: {0}"
 _offset_map = {}
 
 
+def _warn_about_deprecated_aliases(name: str, is_period: bool) -> str:
+    if name in _lite_rule_alias:
+        return name
+    if name in c_PERIOD_AND_OFFSET_DEPR_FREQSTR:
+        warnings.warn(
+            f"\'{name}\' is deprecated and will be removed "
+            f"in a future version, please use "
+            f"\'{c_PERIOD_AND_OFFSET_DEPR_FREQSTR.get(name)}\' "
+            f" instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+            )
+        return c_PERIOD_AND_OFFSET_DEPR_FREQSTR[name]
+
+    for _name in (name.lower(), name.upper()):
+        if name == _name:
+            continue
+        if _name in c_PERIOD_AND_OFFSET_DEPR_FREQSTR.values():
+            warnings.warn(
+                f"\'{name}\' is deprecated and will be removed "
+                f"in a future version, please use "
+                f"\'{_name}\' "
+                f" instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+                )
+            return _name
+
+    return name
+
+
 def _validate_to_offset_alias(alias: str, is_period: bool) -> None:
     if not is_period:
         if alias.upper() in c_OFFSET_RENAMED_FREQSTR:
@@ -4750,35 +4777,6 @@ def _get_offset(name: str) -> BaseOffset:
     --------
     _get_offset('EOM') --> BMonthEnd(1)
     """
-    if (
-        name not in _lite_rule_alias
-        and (name.upper() in _lite_rule_alias)
-        and name != "ms"
-    ):
-        warnings.warn(
-            f"\'{name}\' is deprecated and will be removed "
-            f"in a future version, please use \'{name.upper()}\' instead.",
-            FutureWarning,
-            stacklevel=find_stack_level(),
-        )
-    elif (
-        name not in _lite_rule_alias
-        and (name.lower() in _lite_rule_alias)
-        and name != "MS"
-    ):
-        warnings.warn(
-            f"\'{name}\' is deprecated and will be removed "
-            f"in a future version, please use \'{name.lower()}\' instead.",
-            FutureWarning,
-            stacklevel=find_stack_level(),
-        )
-    if name not in _dont_uppercase:
-        name = name.upper()
-        name = _lite_rule_alias.get(name, name)
-        name = _lite_rule_alias.get(name.lower(), name)
-    else:
-        name = _lite_rule_alias.get(name, name)
-
     if name not in _offset_map:
         try:
             split = name.split("-")
@@ -4880,6 +4878,7 @@ cpdef to_offset(freq, bint is_period=False):
 
             tups = zip(split[0::4], split[1::4], split[2::4])
             for n, (sep, stride, name) in enumerate(tups):
+                name = _warn_about_deprecated_aliases(name, is_period)
                 _validate_to_offset_alias(name, is_period)
                 if is_period:
                     if name.upper() in c_PERIOD_TO_OFFSET_FREQSTR:
@@ -4888,31 +4887,21 @@ cpdef to_offset(freq, bint is_period=False):
                                 f"\'{name}\' is no longer supported, "
                                 f"please use \'{name.upper()}\' instead.",
                             )
-                        name = c_PERIOD_TO_OFFSET_FREQSTR.get(name.upper())
-
-                if name in c_PERIOD_AND_OFFSET_DEPR_FREQSTR:
-                    warnings.warn(
-                        f"\'{name}\' is deprecated and will be removed "
-                        f"in a future version, please use "
-                        f"\'{c_PERIOD_AND_OFFSET_DEPR_FREQSTR.get(name)}\' "
-                        f"instead.",
-                        FutureWarning,
-                        stacklevel=find_stack_level(),
-                        )
-                    name = c_PERIOD_AND_OFFSET_DEPR_FREQSTR.get(name)
+                        name = c_PERIOD_TO_OFFSET_FREQSTR[name.upper()]
+                name = _lite_rule_alias.get(name, name)
+
                 if sep != "" and not sep.isspace():
                     raise ValueError("separator must be spaces")
-                prefix = _lite_rule_alias.get(name) or name
                 if stride_sign is None:
                     stride_sign = -1 if stride.startswith("-") else 1
                 if not stride:
                     stride = 1
 
-                if prefix in {"D", "h", "min", "s", "ms", "us", "ns"}:
+                if name in {"D", "h", "min", "s", "ms", "us", "ns"}:
                     # 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=prefix)
+                    td = Timedelta(1, unit=name)
                     off = delta_to_tick(td)
                     offset = off * float(stride)
                     if n != 0:
@@ -4921,7 +4910,7 @@ cpdef to_offset(freq, bint is_period=False):
                         offset *= stride_sign
                 else:
                     stride = int(stride)
-                    offset = _get_offset(prefix)
+                    offset = _get_offset(name)
                     offset = offset * int(np.fabs(stride) * stride_sign)
 
                 if result is None:
@@ -4931,7 +4920,7 @@ cpdef to_offset(freq, bint is_period=False):
         except (ValueError, TypeError) as err:
             raise ValueError(INVALID_FREQ_ERR_MSG.format(
                 f"{freq}, failed to parse with error message: {repr(err)}")
-            )
+            ) from err
     else:
         result = None
 

pandas/_typing.py

@@ -526,3 +526,5 @@ def closed(self) -> bool:
 
 # maintaine the sub-type of any hashable sequence
 SequenceT = TypeVar("SequenceT", bound=Sequence[Hashable])
+
+SliceType = Optional[Hashable]

pandas/core/generic.py

@@ -1491,14 +1491,12 @@ def __invert__(self) -> Self:
         return res.__finalize__(self, method="__invert__")
 
     @final
-    def __nonzero__(self) -> NoReturn:
+    def __bool__(self) -> NoReturn:
         raise ValueError(
             f"The truth value of a {type(self).__name__} is ambiguous. "
             "Use a.empty, a.bool(), a.item(), a.any() or a.all()."
         )
 
-    __bool__ = __nonzero__
-
     @final
     def abs(self) -> Self:
         """

pandas/core/indexes/base.py

@@ -45,7 +45,9 @@
     ArrayLike,
     Axes,
     Axis,
+    AxisInt,
     DropKeep,
+    Dtype,
     DtypeObj,
     F,
     IgnoreRaise,
@@ -57,6 +59,7 @@
     ReindexMethod,
     Self,
     Shape,
+    SliceType,
     npt,
 )
 from pandas.compat.numpy import function as nv
@@ -1087,7 +1090,7 @@ def view(self, cls=None):
             result._id = self._id
         return result
 
-    def astype(self, dtype, copy: bool = True):
+    def astype(self, dtype: Dtype, copy: bool = True):
         """
         Create an Index with values cast to dtypes.
 
@@ -2907,14 +2910,12 @@ def __iadd__(self, other):
         return self + other
 
     @final
-    def __nonzero__(self) -> NoReturn:
+    def __bool__(self) -> NoReturn:
         raise ValueError(
             f"The truth value of a {type(self).__name__} is ambiguous. "
             "Use a.empty, a.bool(), a.item(), a.any() or a.all()."
         )
 
-    __bool__ = __nonzero__
-
     # --------------------------------------------------------------------
     # Set Operation Methods
 
@@ -2957,7 +2958,7 @@ def _dti_setop_align_tzs(self, other: Index, setop: str_t) -> tuple[Index, Index
         return self, other
 
     @final
-    def union(self, other, sort=None):
+    def union(self, other, sort: bool | None = None):
         """
         Form the union of two Index objects.
 
@@ -3334,7 +3335,7 @@ def _intersection_via_get_indexer(
         return result
 
     @final
-    def difference(self, other, sort=None):
+    def difference(self, other, sort: bool | None = None):
         """
         Return a new Index with elements of index not in `other`.
 
@@ -3420,7 +3421,12 @@ def _wrap_difference_result(self, other, result):
         # We will override for MultiIndex to handle empty results
         return self._wrap_setop_result(other, result)
 
-    def symmetric_difference(self, other, result_name=None, sort=None):
+    def symmetric_difference(
+        self,
+        other,
+        result_name: abc.Hashable | None = None,
+        sort: bool | None = None,
+    ):
         """
         Compute the symmetric difference of two Index objects.
 
@@ -6389,7 +6395,7 @@ def _transform_index(self, func, *, level=None) -> Index:
             items = [func(x) for x in self]
             return Index(items, name=self.name, tupleize_cols=False)
 
-    def isin(self, values, level=None) -> npt.NDArray[np.bool_]:
+    def isin(self, values, level: str_t | int | None = None) -> npt.NDArray[np.bool_]:
         """
         Return a boolean array where the index values are in `values`.
 
@@ -6687,7 +6693,12 @@ def get_slice_bound(self, label, side: Literal["left", "right"]) -> int:
             else:
                 return slc
 
-    def slice_locs(self, start=None, end=None, step=None) -> tuple[int, int]:
+    def slice_locs(
+        self,
+        start: SliceType = None,
+        end: SliceType = None,
+        step: int | None = None,
+    ) -> tuple[int, int]:
         """
         Compute slice locations for input labels.
 
@@ -6781,7 +6792,9 @@ def slice_locs(self, start=None, end=None, step=None) -> tuple[int, int]:
 
         return start_slice, end_slice
 
-    def delete(self, loc) -> Self:
+    def delete(
+        self, loc: int | np.integer | list[int] | npt.NDArray[np.integer]
+    ) -> Self:
         """
         Make new Index with passed location(-s) deleted.
 
@@ -7227,7 +7240,9 @@ def _maybe_disable_logical_methods(self, opname: str_t) -> None:
             raise TypeError(f"cannot perform {opname} with {type(self).__name__}")
 
     @Appender(IndexOpsMixin.argmin.__doc__)
-    def argmin(self, axis=None, skipna: bool = True, *args, **kwargs) -> int:
+    def argmin(
+        self, axis: AxisInt | None = None, skipna: bool = True, *args, **kwargs
+    ) -> int:
         nv.validate_argmin(args, kwargs)
         nv.validate_minmax_axis(axis)
 
@@ -7240,7 +7255,9 @@ def argmin(self, axis=None, skipna: bool = True, *args, **kwargs) -> int:
         return super().argmin(skipna=skipna)
 
     @Appender(IndexOpsMixin.argmax.__doc__)
-    def argmax(self, axis=None, skipna: bool = True, *args, **kwargs) -> int:
+    def argmax(
+        self, axis: AxisInt | None = None, skipna: bool = True, *args, **kwargs
+    ) -> int:
         nv.validate_argmax(args, kwargs)
         nv.validate_minmax_axis(axis)
 
@@ -7251,7 +7268,7 @@ def argmax(self, axis=None, skipna: bool = True, *args, **kwargs) -> int:
                 raise ValueError("Encountered all NA values")
         return super().argmax(skipna=skipna)
 
-    def min(self, axis=None, skipna: bool = True, *args, **kwargs):
+    def min(self, axis: AxisInt | None = None, skipna: bool = True, *args, **kwargs):
         """
         Return the minimum value of the Index.
 
@@ -7314,7 +7331,7 @@ def min(self, axis=None, skipna: bool = True, *args, **kwargs):
 
         return nanops.nanmin(self._values, skipna=skipna)
 
-    def max(self, axis=None, skipna: bool = True, *args, **kwargs):
+    def max(self, axis: AxisInt | None = None, skipna: bool = True, *args, **kwargs):
         """
         Return the maximum value of the Index.