API: Implement new indexing behavior for intervals
State: closed

- [X] closes #16316, closes #23705, closes #25087, closes #25860, closes #24931
- [X] tests added / passed
- [X] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [X] whatsnew entry

I left the `test_interval.py` and `test_interval_new.py` files separate for now, in order to make it more obvious what is being changed.  Will condense these files in a follow-up.

Labels:
name: Indexing
description: Related to indexing on series/frames, not to indexes themselves
name: API Design
name: Interval
description: Interval data type

Comments:
if you have other issues you are closing add them as closes in the top of the PR
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/27100?src=pr&el=h1) Report
> Merging [#27100](https://codecov.io/gh/pandas-dev/pandas/pull/27100?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/1be0561df529ef0597465c6dfe023e34f7dd6d4d?src=pr&el=desc) will **decrease** coverage by `49.97%`.
> The diff coverage is `8.69%`.

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

```diff
@@             Coverage Diff             @@
##           master   #27100       +/-   ##
===========================================
- Coverage   91.87%    41.9%   -49.98%     
===========================================
  Files         180      180               
  Lines       50853    50861        +8     
===========================================
- Hits        46719    21311    -25408     
- Misses       4134    29550    +25416
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `?` | |
| #single | `41.9% <8.69%> (-0.07%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/27100?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/indexing.py](https://codecov.io/gh/pandas-dev/pandas/pull/27100/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhpbmcucHk=) | `53.68% <100%> (-39.62%)` | :arrow_down: |
| [pandas/core/indexes/base.py](https://codecov.io/gh/pandas-dev/pandas/pull/27100/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9iYXNlLnB5) | `55.52% <100%> (-41.41%)` | :arrow_down: |
| [pandas/core/indexes/interval.py](https://codecov.io/gh/pandas-dev/pandas/pull/27100/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9pbnRlcnZhbC5weQ==) | `34.24% <6.66%> (-62.21%)` | :arrow_down: |
| [pandas/io/formats/latex.py](https://codecov.io/gh/pandas-dev/pandas/pull/27100/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2Zvcm1hdHMvbGF0ZXgucHk=) | `0% <0%> (-100%)` | :arrow_down: |
| [pandas/io/gcs.py](https://codecov.io/gh/pandas-dev/pandas/pull/27100/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2djcy5weQ==) | `0% <0%> (-100%)` | :arrow_down: |
| [pandas/io/sas/sas\_constants.py](https://codecov.io/gh/pandas-dev/pandas/pull/27100/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL3Nhcy9zYXNfY29uc3RhbnRzLnB5) | `0% <0%> (-100%)` | :arrow_down: |
| [pandas/core/groupby/categorical.py](https://codecov.io/gh/pandas-dev/pandas/pull/27100/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ3JvdXBieS9jYXRlZ29yaWNhbC5weQ==) | `0% <0%> (-100%)` | :arrow_down: |
| [pandas/tseries/plotting.py](https://codecov.io/gh/pandas-dev/pandas/pull/27100/diff?src=pr&el=tree#diff-cGFuZGFzL3RzZXJpZXMvcGxvdHRpbmcucHk=) | `0% <0%> (-100%)` | :arrow_down: |
| [pandas/tseries/converter.py](https://codecov.io/gh/pandas-dev/pandas/pull/27100/diff?src=pr&el=tree#diff-cGFuZGFzL3RzZXJpZXMvY29udmVydGVyLnB5) | `0% <0%> (-100%)` | :arrow_down: |
| [pandas/io/s3.py](https://codecov.io/gh/pandas-dev/pandas/pull/27100/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL3MzLnB5) | `0% <0%> (-100%)` | :arrow_down: |
| ... and [135 more](https://codecov.io/gh/pandas-dev/pandas/pull/27100/diff?src=pr&el=tree-more) | |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/27100?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/27100?src=pr&el=footer). Last update [1be0561...50c257c](https://codecov.io/gh/pandas-dev/pandas/pull/27100?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

It would also be good to add some documentation on indexing in the advanced.rst interval section (maybe copy some example from the whatsnew you added)
@jorisvandenbossche : added a description of the new behavior to `advanced.rst`.
@jreback @jorisvandenbossche : also removed the warning about indexing behavior being provisional
@jreback @jorisvandenbossche : all existing comments have been addressed
also merge master
merge master (as the other PR was merged)
thanks @jschendel very nice patch!
Glad to see this finally resolved. Looking forward to trying out the new behavior. 
@zfrenchee it would be very welcome to test and give feedback ! 
(there should also be a release candidate in a few days, if that is easier to test than master)
@jorisvandenbossche I noticed today 

```
NotImplementedError: contains not implemented for two intervals
```

Both in 25.3 and master. Is there still room to contribute to intervalIndex? 
@alexlenail I think it is best to open a new issue for this (to ensure it doesn't get lost) 
I need to look back whether this was done on purpose or just because it was less straightforward / lack of time (the error type seems to suggest the second). But let's use a new issue to discuss that. Contributions are certainly welcome!