CLN/API: clean-up of level argument of isin for indexes

[simonjayhawkins]

The docstring for Index.isin() states:

        level : str or int, optional
            Name or position of the index level to use (if the index is a
            `MultiIndex`).

But the keyword is accepted by the other indexes, validated and raises if the level parameter does not match the only level in the index.

This PR removes the levels argument from the indexes (except MultiIndex)

Series.isin() and DataFrame.isin() do not have a level parameter, so isin for indexes will be consistent.

The implementation for MultiIndex.isin is independent from Index.isin, so i think that a separate docstring for MultiIndex would be much clearer. (but out of scope for this PR)

The docstring for datetimelike indexes does not include the level parameter but is not part of the published api, so has been removed to avoid confusion.

NOTE: This is not a change to the api, but a clean-up to match the api to the published api.

[WillAyd]

I think at least worth a whatsnew in case anyone out there was using this without worrying whether they are using an Index or MultiIndex in some ops

[codecov]

Codecov Report

Merging #26635 into master will decrease coverage by 0.01%.
The diff coverage is 100%.

@@            Coverage Diff             @@
##           master   #26635      +/-   ##
==========================================
- Coverage   91.88%   91.86%   -0.02%     
==========================================
  Files         174      174              
  Lines       50692    50687       -5     
==========================================
- Hits        46576    46566      -10     
- Misses       4116     4121       +5

Flag	Coverage Δ
#multiple	90.4% <100%> (-0.01%)	⬇️
#single	41.77% <100%> (-0.12%)	⬇️

Impacted Files	Coverage Δ
pandas/core/indexes/numeric.py	97.3% <ø> (-0.04%)	⬇️
pandas/core/indexes/datetimelike.py	98.13% <100%> (ø)	⬆️
pandas/core/indexes/base.py	96.66% <100%> (-0.06%)	⬇️
pandas/io/gbq.py	78.94% <0%> (-10.53%)	⬇️
pandas/core/frame.py	97% <0%> (-0.12%)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 8d124ea...0970cf6. Read the comment docs.

[codecov]

Codecov Report

Merging #26635 into master will decrease coverage by 0.01%.
The diff coverage is 100%.

@@            Coverage Diff             @@
##           master   #26635      +/-   ##
==========================================
- Coverage   91.88%   91.86%   -0.02%     
==========================================
  Files         174      174              
  Lines       50692    50687       -5     
==========================================
- Hits        46576    46566      -10     
- Misses       4116     4121       +5

Flag	Coverage Δ
#multiple	90.4% <100%> (-0.01%)	⬇️
#single	41.77% <100%> (-0.12%)	⬇️

Impacted Files	Coverage Δ
pandas/core/indexes/numeric.py	97.3% <ø> (-0.04%)	⬇️
pandas/core/indexes/datetimelike.py	98.13% <100%> (ø)	⬆️
pandas/core/indexes/base.py	96.66% <100%> (-0.06%)	⬇️
pandas/io/gbq.py	78.94% <0%> (-10.53%)	⬇️
pandas/core/frame.py	97% <0%> (-0.12%)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 8d124ea...0970cf6. Read the comment docs.

[simonjayhawkins]

I think at least worth a whatsnew

as a bug or an API change?

in case anyone out there was using this without worrying whether they are using an Index or MultiIndex in some ops

that's a possibility. do you think we need to deprecate first?

[WillAyd]

API change. This does fall a little bit into a gray area though; deprecation would be safer but this is also clearly documented as only supported for MultiIndex, so maybe outright removal is OK. Let's see what others think

[simonjayhawkins]

@WillAyd : I could have this the wrong way round. it was added in and the api for levels defined in #7892.

It looks like the documentation may be inconsistent. would need to add in the raises section and remove the level only being applicable to the MultiIndex

We do have a variation though on the error raised, we are raising IndexError and KeyError for the level numbers and labels.

If this is the defined api and as you said could be used in ops without needing to check the index type then all indexes must obey this interface and validate the input, i'll need to check the implementations of other index types to make sure.