deprecate non-keyword args for clip

Author: MarcoGorelli

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

@@ -61,6 +61,7 @@
     InvalidIndexError,
 )
 from pandas.util._decorators import (
+    deprecate_nonkeyword_arguments,
     doc,
     rewrite_axis_style_signature,
 )
@@ -7469,6 +7470,9 @@ def clip(
     ) -> FrameOrSeries | None:
         ...
 
+    @deprecate_nonkeyword_arguments(
+        version="2.0", allowed_args=["self", "lower", "upper"]
+    )
     @final
     def clip(
         self: FrameOrSeries,

pandas/tests/frame/methods/test_clip.py

@@ -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 arguments 'self', 'lower' and 'upper' will be keyword-only"
+        )
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            df.clip(0, 1, 0)

pandas/tests/series/methods/test_clip.py

@@ -127,3 +127,13 @@ def test_clip_with_datetimes(self):
             ]
         )
         tm.assert_series_equal(result, expected)
+
+    def test_clip_pos_args_deprecation(self):
+        # https://github.com/pandas-dev/pandas/issues/41485
+        ser = Series([1, 2, 3])
+        msg = (
+            r"Starting with Pandas version 2\.0 all arguments of clip except "
+            r"for the arguments 'self', 'lower' and 'upper' will be keyword-only"
+        )
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            ser.clip(0, 1, 0)