API: Remove IntervalArray from top-level
State: closed

cc @jschendel @jreback @jorisvandenbossche 

Originally, we put IntervalArray in the top-level since it has the special alternative constructors. But it's a bit inconsistent with all our new arrays, so this is a proposal to remove it from the top-level and just have it in `pandas.arrays`. I don't think the extra typing is too bad, and it's more consistent with our other (new) arrays.

Labels:
name: API Design

Comments:
+1 on this. I think we had every intention of moving this, but namespace didn't exist when it was originallly created.
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/24926?src=pr&el=h1) Report
> :exclamation: No coverage uploaded for pull request base (`master@85982ed`). [Click here to learn what that means](https://docs.codecov.io/docs/error-reference#section-missing-base-commit).
> The diff coverage is `n/a`.

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

```diff
@@            Coverage Diff            @@
##             master   #24926   +/-   ##
=========================================
  Coverage          ?   92.38%           
=========================================
  Files             ?      166           
  Lines             ?    52388           
  Branches          ?        0           
=========================================
  Hits              ?    48397           
  Misses            ?     3991           
  Partials          ?        0
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.8% <ø> (?)` | |
| #single | `42.89% <ø> (?)` | |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/24926?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/arrays/interval.py](https://codecov.io/gh/pandas-dev/pandas/pull/24926/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXJyYXlzL2ludGVydmFsLnB5) | `93.12% <ø> (ø)` | |
| [pandas/core/api.py](https://codecov.io/gh/pandas-dev/pandas/pull/24926/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXBpLnB5) | `100% <ø> (ø)` | |
| [pandas/core/arrays/array\_.py](https://codecov.io/gh/pandas-dev/pandas/pull/24926/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXJyYXlzL2FycmF5Xy5weQ==) | `100% <ø> (ø)` | |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/24926?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/24926?src=pr&el=footer). Last update [85982ed...a5efedf](https://codecov.io/gh/pandas-dev/pandas/pull/24926?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/24926?src=pr&el=h1) Report
> :exclamation: No coverage uploaded for pull request base (`master@85982ed`). [Click here to learn what that means](https://docs.codecov.io/docs/error-reference#section-missing-base-commit).
> The diff coverage is `n/a`.

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

```diff
@@            Coverage Diff            @@
##             master   #24926   +/-   ##
=========================================
  Coverage          ?   92.38%           
=========================================
  Files             ?      166           
  Lines             ?    52388           
  Branches          ?        0           
=========================================
  Hits              ?    48397           
  Misses            ?     3991           
  Partials          ?        0
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.8% <ø> (?)` | |
| #single | `42.89% <ø> (?)` | |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/24926?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/arrays/interval.py](https://codecov.io/gh/pandas-dev/pandas/pull/24926/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXJyYXlzL2ludGVydmFsLnB5) | `93.12% <ø> (ø)` | |
| [pandas/core/indexes/interval.py](https://codecov.io/gh/pandas-dev/pandas/pull/24926/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9pbnRlcnZhbC5weQ==) | `95.25% <ø> (ø)` | |
| [pandas/core/api.py](https://codecov.io/gh/pandas-dev/pandas/pull/24926/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXBpLnB5) | `100% <ø> (ø)` | |
| [pandas/core/arrays/array\_.py](https://codecov.io/gh/pandas-dev/pandas/pull/24926/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXJyYXlzL2FycmF5Xy5weQ==) | `100% <ø> (ø)` | |

------

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

@TomAugspurger there is one remaining doctest failure:

```
2019-01-25T13:45:18.3796803Z 
2019-01-25T13:45:18.3796844Z =================================== FAILURES ===================================
2019-01-25T13:45:18.3796901Z _________ [doctest] pandas.core.arrays.interval.IntervalArray.overlaps _________
2019-01-25T13:45:18.3796959Z 1096 ndarray
2019-01-25T13:45:18.3796997Z 1097     Boolean array positionally indicating where an overlap occurs.
2019-01-25T13:45:18.3797032Z 1098 
2019-01-25T13:45:18.3797083Z 1099 See Also
2019-01-25T13:45:18.3797548Z 1100 --------
2019-01-25T13:45:18.3797595Z 1101 Interval.overlaps : Check whether two Interval objects overlap.
2019-01-25T13:45:18.3797632Z 1102 
2019-01-25T13:45:18.3797680Z 1103 Examples
2019-01-25T13:45:18.3797850Z 1104 --------
2019-01-25T13:45:18.3797892Z 1105 >>> intervals = pd.IntervalArray.from_tuples([(0, 1), (1, 3), (2, 4)])
2019-01-25T13:45:18.3798294Z UNEXPECTED EXCEPTION: AttributeError("module 'pandas' has no attribute 'IntervalArray'")
2019-01-25T13:45:18.3798337Z Traceback (most recent call last):
2019-01-25T13:45:18.3798363Z 
2019-01-25T13:45:18.3798808Z   File "/home/vsts/miniconda3/envs/pandas-dev/lib/python3.7/doctest.py", line 1329, in __run
2019-01-25T13:45:18.3798879Z     compileflags, 1), test.globs)
2019-01-25T13:45:18.3798903Z 
2019-01-25T13:45:18.3798942Z   File "<doctest pandas.core.arrays.interval.IntervalArray.overlaps[0]>", line 1, in <module>
2019-01-25T13:45:18.3798988Z 
2019-01-25T13:45:18.3799178Z AttributeError: module 'pandas' has no attribute 'IntervalArray'
2019-01-25T13:45:18.3799208Z 
2019-01-25T13:45:18.3799246Z /home/vsts/work/1/s/pandas/core/arrays/interval.py:1105: UnexpectedException
2019-01-25T13:45:18.3799413Z ============== 1 failed, 6 passed, 12 deselected in 0.05 seconds ===============
2019-01-25T13:45:18.4697773Z Doctests interval classes DONE
```
Ah, that docstring is templated, so I didn't see it earlier.

Gotta fixup the template a bit, one sec.
Fixed all the interval doctests aside from IntervalIndex.get_loc https://github.com/pandas-dev/pandas/issues/24931