TYP fixup overloads for reset_index
State: closed

- [x] Ensure all linting tests pass, see [here](https://pandas.pydata.org/pandas-docs/dev/development/contributing.html#code-standards) for how to run them

Took me longer than I'm proud to admit, but I think I've finally understood the deal with overload and default types.

We need one overload for the default case (here, `inplace=False`), and then an extra overload of each combination of keyword arguments which _precede_ `inplace`.

So here, we need:
- one case for the defaults
- one case for when there all all arguments and `inplace=True`
- one case for when there's no `level`, and `inplace=True`
- one case for when there's no `drop`, and `inplace=True`
- one case for when there's no `level`, no `drop`, and `inplace=True`

Then, `mypy` will be able to correctly infer the return type for `reset_index` based on the value of `inplace`.

This kind of thing will help resolve the mypy issues seen in #38594, where the return type from `fillna` couldn't be determined. It also means not needing to add the ignore error from #37137

----

Some examples:

```python
# t.py

import pandas as pd

reveal_type(pd.DataFrame([1,2,3]).reset_index(level=0))
reveal_type(pd.DataFrame([1,2,3]).reset_index(inplace=False))
reveal_type(pd.DataFrame([1,2,3]).reset_index(drop=True, inplace=True))
reveal_type(pd.DataFrame([1,2,3]).reset_index(level=0, inplace=True))
reveal_type(pd.DataFrame([1,2,3]).reset_index(level=0, drop=False, inplace=True))
reveal_type(pd.DataFrame([1,2,3]).reset_index(level=0, inplace=True, col_fill='a'))
reveal_type(pd.DataFrame([1,2,3]).reset_index(level=0, col_fill='a'))
reveal_type(pd.DataFrame([1,2,3]).reset_index(inplace=True))
```

```console
$ mypy t.py 
t.py:3: note: Revealed type is 'pandas.core.frame.DataFrame'
t.py:4: note: Revealed type is 'pandas.core.frame.DataFrame'
t.py:5: note: Revealed type is 'None'
t.py:6: note: Revealed type is 'None'
t.py:7: note: Revealed type is 'None'
t.py:8: note: Revealed type is 'None'
t.py:9: note: Revealed type is 'pandas.core.frame.DataFrame'
t.py:10: note: Revealed type is 'None'
```

Labels:
name: Typing
description: type annotations, mypy/pyright type checking

Comments:
> MarcoGorelli requested a review from simonjayhawkins 15 minutes ago

watch this space!
> > MarcoGorelli requested a review from simonjayhawkins 15 minutes ago
> 
> watch this space!

see #40202
Thanks - OK, merging then as I'm not sure how long it'll take for #40202 to be ready, have opened #40349 to make sure that adding tests for this isn't forgotten
> have opened #40349 to make sure that adding tests for this isn't forgotten

great. we can add the reveals from your comments here to the tests in #40202 
just one more thing!

these extra overloads are needed because of an issue with mypy. we have now lost that link to the issue.

although the mypy issue was initially dismissed, it appears that there is acknowledgement that the workaround can becomes impractical with many arguments. There therefore may be a fix on the mypy side in the future. We somehow need to track that issue.
The (*, level, inplace) overload should probably have been (level, *, inplace), but I'll check tomorrow