ENH: Add case_when method

doc/source/whatsnew/v2.2.0.rst

@@ -13,6 +13,23 @@ including other versions of pandas.
 
 Enhancements
 ~~~~~~~~~~~~
+.. _whatsnew_220.enhancements.case_when:
+
+Create a pandas Series based on one or more conditions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The :func:`case_when` function has been added to create a Series object based on one or more conditions. (:issue:`39154`)
+
+.. ipython:: python
+
+   import pandas as pd
+
+   df = pd.DataFrame(dict(a=[1, 2, 3], b=[4, 5, 6]))
+   pd.case_when(
+        (df.a == 1, 'first'),  # condition, replacement
+        (df.a.gt(1) & df.b.eq(5), 'second'),  # condition, replacement
+        default = 'default', # optional
+   )
 
 .. _whatsnew_220.enhancements.adbc_support:
 

pandas/core/case_when.py

@@ -17,12 +17,16 @@
 from pandas.core.construction import array as pd_array
 
 if TYPE_CHECKING:
-    from pandas._typing import Series
+    from pandas._typing import (
+        ArrayLike,
+        Scalar,
+        Series,
+    )
 
 
 def case_when(
-    *args: tuple[tuple],
-    default=lib.no_default,
+    *args: tuple[tuple[tuple[ArrayLike], tuple[ArrayLike | Scalar]]],
+    default: ArrayLike | Scalar = lib.no_default,
 ) -> Series:
     """
     Replace values where the conditions are True.
@@ -189,6 +193,7 @@ def validate_case_when(args: tuple) -> tuple:
     """
     Validates the variable arguments for the case_when function.
     """
+
     if not len(args):
         raise ValueError(
             "provide at least one boolean condition, "

pandas/core/series.py

@@ -5588,7 +5588,7 @@ def between(
 
     def case_when(
         self,
-        *args: tuple[tuple],
+        *args: tuple[tuple[tuple[ArrayLike], tuple[ArrayLike | Scalar]]],
     ) -> Series:
         """
         Replace values where the conditions are True.