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

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.

Labels:
name: API Design
name: Clean

Comments:
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](https://codecov.io/gh/pandas-dev/pandas/pull/26635?src=pr&el=h1) Report
> Merging [#26635](https://codecov.io/gh/pandas-dev/pandas/pull/26635?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/8d124ea4c5200f218db7cea8e3ff504b0045a4e6?src=pr&el=desc) will **decrease** coverage by `0.01%`.
> The diff coverage is `100%`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/26635/graphs/tree.svg?width=650&token=eZ4WkYLtcO&height=150&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/26635?src=pr&el=tree)

```diff
@@            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%)` | :arrow_down: |
| #single | `41.77% <100%> (-0.12%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/26635?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/indexes/numeric.py](https://codecov.io/gh/pandas-dev/pandas/pull/26635/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9udW1lcmljLnB5) | `97.3% <ø> (-0.04%)` | :arrow_down: |
| [pandas/core/indexes/datetimelike.py](https://codecov.io/gh/pandas-dev/pandas/pull/26635/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9kYXRldGltZWxpa2UucHk=) | `98.13% <100%> (ø)` | :arrow_up: |
| [pandas/core/indexes/base.py](https://codecov.io/gh/pandas-dev/pandas/pull/26635/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9iYXNlLnB5) | `96.66% <100%> (-0.06%)` | :arrow_down: |
| [pandas/io/gbq.py](https://codecov.io/gh/pandas-dev/pandas/pull/26635/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2dicS5weQ==) | `78.94% <0%> (-10.53%)` | :arrow_down: |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/26635/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97% <0%> (-0.12%)` | :arrow_down: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/26635?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/26635?src=pr&el=footer). Last update [8d124ea...0970cf6](https://codecov.io/gh/pandas-dev/pandas/pull/26635?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/26635?src=pr&el=h1) Report
> Merging [#26635](https://codecov.io/gh/pandas-dev/pandas/pull/26635?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/8d124ea4c5200f218db7cea8e3ff504b0045a4e6?src=pr&el=desc) will **decrease** coverage by `0.01%`.
> The diff coverage is `100%`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/26635/graphs/tree.svg?width=650&token=eZ4WkYLtcO&height=150&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/26635?src=pr&el=tree)

```diff
@@            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%)` | :arrow_down: |
| #single | `41.77% <100%> (-0.12%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/26635?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/indexes/numeric.py](https://codecov.io/gh/pandas-dev/pandas/pull/26635/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9udW1lcmljLnB5) | `97.3% <ø> (-0.04%)` | :arrow_down: |
| [pandas/core/indexes/datetimelike.py](https://codecov.io/gh/pandas-dev/pandas/pull/26635/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9kYXRldGltZWxpa2UucHk=) | `98.13% <100%> (ø)` | :arrow_up: |
| [pandas/core/indexes/base.py](https://codecov.io/gh/pandas-dev/pandas/pull/26635/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9iYXNlLnB5) | `96.66% <100%> (-0.06%)` | :arrow_down: |
| [pandas/io/gbq.py](https://codecov.io/gh/pandas-dev/pandas/pull/26635/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2dicS5weQ==) | `78.94% <0%> (-10.53%)` | :arrow_down: |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/26635/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97% <0%> (-0.12%)` | :arrow_down: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/26635?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/26635?src=pr&el=footer). Last update [8d124ea...0970cf6](https://codecov.io/gh/pandas-dev/pandas/pull/26635?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

> 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?
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
@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.