Deprecate non-keyword arguments in mask

doc/source/whatsnew/v1.3.0.rst

@@ -648,6 +648,7 @@ Deprecations
 - Deprecated setting :attr:`Categorical._codes`, create a new :class:`Categorical` with the desired codes instead (:issue:`40606`)
 - Deprecated behavior of :meth:`DatetimeIndex.union` with mixed timezones; in a future version both will be cast to UTC instead of object dtype (:issue:`39328`)
 - Deprecated using ``usecols`` with out of bounds indices for ``read_csv`` with ``engine="c"`` (:issue:`25623`)
+- Deprecated passing arguments (apart from ``cond``) as positional in :meth:`DataFrame.mask` (:issue:`41485`)
 
 .. ---------------------------------------------------------------------------
 

pandas/core/generic.py

@@ -61,6 +61,7 @@
     InvalidIndexError,
 )
 from pandas.util._decorators import (
+    deprecate_nonkeyword_arguments,
     doc,
     rewrite_axis_style_signature,
 )
@@ -9231,6 +9232,9 @@ def where(
         name="mask",
         name_other="where",
     )
+    @deprecate_nonkeyword_arguments(
+        version=None, allowed_args=["self", "cond", "other"]
+    )
     def mask(
         self,
         cond,
@@ -9250,7 +9254,7 @@ def mask(
                 "try_cast keyword is deprecated and will be removed in a "
                 "future version",
                 FutureWarning,
-                stacklevel=2,
+                stacklevel=3,
             )
 
         # see gh-21891

pandas/tests/frame/indexing/test_mask.py

@@ -25,8 +25,8 @@ def test_mask(self):
 
         other = DataFrame(np.random.randn(5, 3))
         rs = df.where(cond, other)
-        tm.assert_frame_equal(rs, df.mask(df <= 0, other))
-        tm.assert_frame_equal(rs, df.mask(~cond, other))
+        tm.assert_frame_equal(rs, df.mask(df <= 0, other=other))
+        tm.assert_frame_equal(rs, df.mask(~cond, other=other))
 
         # see GH#21891
         df = DataFrame([1, 2])
@@ -51,7 +51,7 @@ def test_mask_inplace(self):
         return_value = rdf.where(cond, -df, inplace=True)
         assert return_value is None
         tm.assert_frame_equal(rdf, df.where(cond, -df))
-        tm.assert_frame_equal(rdf, df.mask(~cond, -df))
+        tm.assert_frame_equal(rdf, df.mask(~cond, other=-df))
 
     def test_mask_edge_case_1xN_frame(self):
         # GH#4071
@@ -63,22 +63,22 @@ def test_mask_edge_case_1xN_frame(self):
     def test_mask_callable(self):
         # GH#12533
         df = DataFrame([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
-        result = df.mask(lambda x: x > 4, lambda x: x + 1)
+        result = df.mask(lambda x: x > 4, other=lambda x: x + 1)
         exp = DataFrame([[1, 2, 3], [4, 6, 7], [8, 9, 10]])
         tm.assert_frame_equal(result, exp)
-        tm.assert_frame_equal(result, df.mask(df > 4, df + 1))
+        tm.assert_frame_equal(result, df.mask(df > 4, other=df + 1))
 
         # return ndarray and scalar
-        result = df.mask(lambda x: (x % 2 == 0).values, lambda x: 99)
+        result = df.mask(lambda x: (x % 2 == 0).values, other=lambda x: 99)
         exp = DataFrame([[1, 99, 3], [99, 5, 99], [7, 99, 9]])
         tm.assert_frame_equal(result, exp)
-        tm.assert_frame_equal(result, df.mask(df % 2 == 0, 99))
+        tm.assert_frame_equal(result, df.mask(df % 2 == 0, other=99))
 
         # chain
-        result = (df + 2).mask(lambda x: x > 8, lambda x: x + 10)
+        result = (df + 2).mask(lambda x: x > 8, other=lambda x: x + 10)
         exp = DataFrame([[3, 4, 5], [6, 7, 8], [19, 20, 21]])
         tm.assert_frame_equal(result, exp)
-        tm.assert_frame_equal(result, (df + 2).mask((df + 2) > 8, (df + 2) + 10))
+        tm.assert_frame_equal(result, (df + 2).mask((df + 2) > 8, other=(df + 2) + 10))
 
     def test_mask_dtype_bool_conversion(self):
         # GH#3733
@@ -90,6 +90,18 @@ def test_mask_dtype_bool_conversion(self):
         result = bools.mask(mask)
         tm.assert_frame_equal(result, expected)
 
+    def test_mask_pos_args_deprecation(self):
+        # https://github.com/pandas-dev/pandas/issues/41485
+        df = DataFrame(np.random.randn(5, 5))
+        cond = df > 0
+        other = DataFrame(np.random.randn(5, 3))
+
+        with tm.assert_produces_warning(FutureWarning):
+            result = df.mask(cond, other, False)
+
+        expected = df.mask(cond, other=other, inplace=False)
+        tm.assert_frame_equal(result, expected)
+
 
 def test_mask_try_cast_deprecated(frame_or_series):
 
@@ -101,7 +113,7 @@ def test_mask_try_cast_deprecated(frame_or_series):
 
     with tm.assert_produces_warning(FutureWarning):
         # try_cast keyword deprecated
-        obj.mask(mask, -1, try_cast=True)
+        obj.mask(mask, other=-1, try_cast=True)
 
 
 def test_mask_stringdtype():
@@ -115,7 +127,7 @@ def test_mask_stringdtype():
         {"A": ["this", "that"]}, index=["id2", "id3"], dtype=StringDtype()
     )
     filter_ser = Series([False, True, True, False])
-    result = df.mask(filter_ser, filtered_df)
+    result = df.mask(filter_ser, other=filtered_df)
 
     expected = DataFrame(
         {"A": [NA, "this", "that", NA]},

pandas/tests/series/indexing/test_mask.py

@@ -22,7 +22,7 @@ def test_mask():
     tm.assert_series_equal(rs, rs2)
 
     rs = s.where(~cond, -s)
-    rs2 = s.mask(cond, -s)
+    rs2 = s.mask(cond, other=-s)
     tm.assert_series_equal(rs, rs2)
 
     cond = Series([True, False, False, True, False], index=s.index)
@@ -32,18 +32,18 @@ def test_mask():
     tm.assert_series_equal(rs, rs2)
 
     rs = s2.where(~cond[:3], -s2)
-    rs2 = s2.mask(cond[:3], -s2)
+    rs2 = s2.mask(cond[:3], other=-s2)
     tm.assert_series_equal(rs, rs2)
 
     msg = "Array conditional must be same shape as self"
     with pytest.raises(ValueError, match=msg):
         s.mask(1)
     with pytest.raises(ValueError, match=msg):
-        s.mask(cond[:3].values, -s)
+        s.mask(cond[:3].values, other=-s)
 
     # dtype changes
     s = Series([1, 2, 3, 4])
-    result = s.mask(s > 2, np.nan)
+    result = s.mask(s > 2, other=np.nan)
     expected = Series([1, 2, np.nan, np.nan])
     tm.assert_series_equal(result, expected)
 
@@ -65,8 +65,8 @@ def test_mask_inplace():
     tm.assert_series_equal(rs, s.mask(cond))
 
     rs = s.copy()
-    rs.mask(cond, -s, inplace=True)
-    tm.assert_series_equal(rs, s.mask(cond, -s))
+    rs.mask(cond, other=-s, inplace=True)
+    tm.assert_series_equal(rs, s.mask(cond, other=-s))
 
 
 def test_mask_stringdtype():
@@ -78,11 +78,23 @@ def test_mask_stringdtype():
     )
     filtered_ser = Series(["this", "that"], index=["id2", "id3"], dtype=StringDtype())
     filter_ser = Series([False, True, True, False])
-    result = ser.mask(filter_ser, filtered_ser)
+    result = ser.mask(filter_ser, other=filtered_ser)
 
     expected = Series(
         [NA, "this", "that", NA],
         index=["id1", "id2", "id3", "id4"],
         dtype=StringDtype(),
     )
     tm.assert_series_equal(result, expected)
+
+
+def test_mask_pos_args_deprecation():
+    # https://github.com/pandas-dev/pandas/issues/41485
+    s = Series(np.random.randn(6))
+    cond = s > 0
+
+    with tm.assert_produces_warning(FutureWarning):
+        result = s.mask(cond, np.nan, False)
+
+    expected = s.mask(cond, other=np.nan, inplace=False)
+    tm.assert_series_equal(result, expected)

pandas/tests/series/indexing/test_where.py

@@ -314,7 +314,7 @@ def test_broadcast(size, mask, item, box):
     tm.assert_series_equal(result, expected)
 
     s = Series(data)
-    result = s.mask(selection, box(item))
+    result = s.mask(selection, other=box(item))
     tm.assert_series_equal(result, expected)