deprecate nonkeywordargs in clip

Author: MarcoGorelli

asv_bench/benchmarks/series_methods.py

@@ -124,7 +124,7 @@ def setup(self, n):
         self.s = Series(np.random.randn(n))
 
     def time_clip(self, n):
-        self.s.clip(0, 1)
+        self.s.clip(lower=0, upper=1)
 
 
 class ValueCounts:

doc/source/whatsnew/v1.3.0.rst

@@ -647,6 +647,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 as positional in :meth:`DataFrame.clip` and :meth:`Series.clip` (:issue:`41485`)
 
 .. ---------------------------------------------------------------------------
 

pandas/core/generic.py

@@ -7469,6 +7469,7 @@ def clip(
     ) -> FrameOrSeries | None:
         ...
 
+    @deprecate_nonkeyword_arguments(version="2.0", allowed_args=["self"])
     @final
     def clip(
         self: FrameOrSeries,

pandas/tests/frame/methods/test_clip.py

@@ -33,7 +33,7 @@ def test_dataframe_clip(self):
         df = DataFrame(np.random.randn(1000, 2))
 
         for lb, ub in [(-1, 1), (1, -1)]:
-            clipped_df = df.clip(lb, ub)
+            clipped_df = df.clip(lower=lb, upper=ub)
 
             lb, ub = min(lb, ub), max(ub, lb)
             lb_mask = df.values <= lb
@@ -48,7 +48,7 @@ def test_clip_mixed_numeric(self):
         # clip on mixed integer or floats
         # with integer clippers coerces to float
         df = DataFrame({"A": [1, 2, 3], "B": [1.0, np.nan, 3.0]})
-        result = df.clip(1, 2)
+        result = df.clip(lower=1, upper=2)
         expected = DataFrame({"A": [1, 2, 2], "B": [1.0, np.nan, 2.0]})
         tm.assert_frame_equal(result, expected, check_like=True)
 
@@ -67,7 +67,7 @@ def test_clip_against_series(self, inplace):
         ub = lb + 1
 
         original = df.copy()
-        clipped_df = df.clip(lb, ub, axis=0, inplace=inplace)
+        clipped_df = df.clip(lower=lb, upper=ub, axis=0, inplace=inplace)
 
         if inplace:
             clipped_df = df
@@ -113,7 +113,7 @@ def test_clip_against_frame(self, axis):
         lb = DataFrame(np.random.randn(1000, 2))
         ub = lb + 1
 
-        clipped_df = df.clip(lb, ub, axis=axis)
+        clipped_df = df.clip(lower=lb, upper=ub, axis=axis)
 
         lb_mask = df <= lb
         ub_mask = df >= ub
@@ -166,3 +166,13 @@ def test_clip_with_na_args(self, float_frame):
         result = df.clip(lower=t, axis=0)
         expected = DataFrame({"col_0": [9, -3, 0, 6, 5], "col_1": [2, -4, 6, 8, 3]})
         tm.assert_frame_equal(result, expected)
+
+    def test_clip_pos_args_deprecation(self):
+        # https://github.com/pandas-dev/pandas/issues/41485
+        df = DataFrame({"a": [1, 2, 3]})
+        msg = (
+            r"Starting with Pandas version 2\.0 all arguments of clip except "
+            r"for the argument 'self' will be keyword-only"
+        )
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            df.clip(0)

pandas/tests/series/methods/test_clip.py

@@ -18,7 +18,7 @@ def test_clip(self, datetime_series):
         assert datetime_series.clip(lower=val).min() == val
         assert datetime_series.clip(upper=val).max() == val
 
-        result = datetime_series.clip(-0.5, 0.5)
+        result = datetime_series.clip(lower=-0.5, upper=0.5)
         expected = np.clip(datetime_series, -0.5, 0.5)
         tm.assert_series_equal(result, expected)
         assert isinstance(expected, Series)
@@ -74,7 +74,7 @@ def test_clip_with_na_args(self):
 
         # GH#40420
         s = Series([1, 2, 3])
-        result = s.clip(0, [np.nan, np.nan, np.nan])
+        result = s.clip(lower=0, upper=[np.nan, np.nan, np.nan])
         tm.assert_series_equal(s, result)
 
     def test_clip_against_series(self):
@@ -85,8 +85,10 @@ def test_clip_against_series(self):
         lower = Series([1.0, 2.0, 3.0])
         upper = Series([1.5, 2.5, 3.5])
 
-        tm.assert_series_equal(s.clip(lower, upper), Series([1.0, 2.0, 3.5]))
-        tm.assert_series_equal(s.clip(1.5, upper), Series([1.5, 1.5, 3.5]))
+        tm.assert_series_equal(
+            s.clip(lower=lower, upper=upper), Series([1.0, 2.0, 3.5])
+        )
+        tm.assert_series_equal(s.clip(lower=1.5, upper=upper), Series([1.5, 1.5, 3.5]))
 
     @pytest.mark.parametrize("inplace", [True, False])
     @pytest.mark.parametrize("upper", [[1, 2, 3], np.asarray([1, 2, 3])])