Deprecate non-keyword arguments for methods with `inplace`

Background

Having many parameters with defaults makes static typing a lot harder when one of them changes the return type, as they require many* overloads.

There’s still no broad agreement about whether or not to deprecate the inplace argument, so in the meanwhile, if we force default-arguments to be keyword-only, then we can at least set the correct return types for these methods without requiring all these overloads (as many as 38 in one case!).

What to do

1. Choose a method from the following list:

• pandas/core/computation/eval.py:164:0, eval (skip for now)
• pandas/core/frame.py:4718:4, set_axis
• pandas/core/frame.py:4743:4, drop
• pandas/core/frame.py:5134:4, fillna
• pandas/core/frame.py:5306:4, set_index
• pandas/core/frame.py:5572:4, reset_index
• pandas/core/frame.py:5809:4, dropna
• pandas/core/frame.py:5958:4, drop_duplicates
• pandas/core/frame.py:6196:4, sort_values
• pandas/core/frame.py:6267:4, sort_index
• pandas/core/generic.py:6432:4, ffill
• pandas/core/generic.py:6495:4, bfill
• pandas/core/generic.py:6700:4, interpolate
• pandas/core/generic.py:7473:4, clip
• pandas/core/generic.py:9080:4, where
• pandas/core/generic.py:9234:4, mask
• pandas/core/indexes/base.py:1530:4, set_names
• pandas/core/indexes/multi.py:810:4, set_levels
• pandas/core/indexes/multi.py:997:4, set_codes
• pandas/core/resample.py:831:4, interpolate
• pandas/core/series.py:1279:4, reset_index
• pandas/core/series.py:2028:4, drop_duplicates
• pandas/core/series.py:3228:4, sort_values
• pandas/core/series.py:3438:4, sort_index
• pandas/core/series.py:4475:4, set_axis
• pandas/core/series.py:4490:4, drop
• pandas/core/series.py:4713:4, fillna
• pandas/core/series.py:5064:4, dropna
• read_csv
• read_table
• concat

1. Use pandas.util._decorators.deprecate_nonkeyword_arguments to issue a FutureWarning that the method’s default arguments will be keyword-only in the next release.

2. Fixup any tests / internal code which uses such default arguments positionally. See this gist for a helper-script which can help identify cases which need fixing, just replace "drop" with whatever method you’re working on and then run it as python visitor.py.

3. Add a new test, checking that a FutureWarning is raised if this method’s default arguments are used positionally.

4. Add a note to doc/source/whatsnew/v1.3.0.rst

See https://github.com/pandas-dev/pandas/pull/41511 for an example of how to do this.

In most of these methods, the first argument is probably fine to be kept as is, it’s the ones after that (such as axis) which should become keyword-only.

---

*(2^{number of default types preceding the one to overload} +2)

---

It’s really common to call replace with both value and to_replace as positional, so I think we can make an exception for that one. It’ll only require 6 overloads, which I’d argue isn’t too many, especially if no other method requires more than 3 or 4

---

TODO: unify the whatsnew entries

[MarcoGorelli]

yup, that’s the one

easiest way to find where things are defined is probably to find the function in the documentation, then click “source”

[MarcoGorelli]

@Anupam-USP Thanks!

This wasn’t part of the original issue, but read_csv also has keyword argument which changes the return type, if you wanted to make a PR for that one too that would be welcome!