DOC: Add examples for MultiIndex.get_locs + cleanups
State: closed

- [x ] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`

Adds examples to ``MultiIndex.get_locs`` and also some changes to ``.get_loc`` and ``.get_loc_values``.

Labels:
name: Docs
name: MultiIndex

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/17675?src=pr&el=h1) Report
> Merging [#17675](https://codecov.io/gh/pandas-dev/pandas/pull/17675?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/e2a0251d32a1467e9ab86281a31f57aca582a88f?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/17675/graphs/tree.svg?width=650&token=eZ4WkYLtcO&height=150&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/17675?src=pr&el=tree)

```diff
@@            Coverage Diff             @@
##           master   #17675      +/-   ##
==========================================
- Coverage   91.27%   91.25%   -0.02%     
==========================================
  Files         163      163              
  Lines       49765    49765              
==========================================
- Hits        45421    45412       -9     
- Misses       4344     4353       +9
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `89.04% <100%> (ø)` | :arrow_up: |
| #single | `40.33% <33.33%> (-0.07%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/17675?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/categorical.py](https://codecov.io/gh/pandas-dev/pandas/pull/17675?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvY2F0ZWdvcmljYWwucHk=) | `95.7% <ø> (ø)` | :arrow_up: |
| [pandas/core/indexes/multi.py](https://codecov.io/gh/pandas-dev/pandas/pull/17675?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9tdWx0aS5weQ==) | `96.9% <100%> (ø)` | :arrow_up: |
| [pandas/io/gbq.py](https://codecov.io/gh/pandas-dev/pandas/pull/17675?src=pr&el=tree#diff-cGFuZGFzL2lvL2dicS5weQ==) | `25% <0%> (-58.34%)` | :arrow_down: |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/17675?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.73% <0%> (-0.1%)` | :arrow_down: |

------

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

I've made some changes and put them in a new commit as it contains some (very minor) corrections to previous commits also.

#17655 had the reference to ``api.types.CategoricalDType`` wrong (``pandas.`` was prepended which made the link unusable). Given @TomAugspurger excellent new commit on CategoricalDType, I've changed the location + added a small text description.

#17653  had too many back-ticks in the links in section "Examples". I've removed those.
Seems like some issue with the API reference. I'm looking into it.

On Tue, Sep 26, 2017 at 6:48 AM, topper-123 <notifications@github.com>
wrote:

> *@topper-123* commented on this pull request.
> ------------------------------
>
> In pandas/core/categorical.py
> <https://github.com/pandas-dev/pandas/pull/17675#discussion_r141031952>:
>
> > @@ -223,7 +223,7 @@ class Categorical(PandasObject):
>
>      See also
>      --------
> -    pandas.api.types.CategoricalDtype
>
> Looking more into it, I actually think CategoricalDtype isn't shown at
> all in the generated API docs, so the reference will be not work in ant
> case. Is this correct?
>
> —
> You are receiving this because you were mentioned.
> Reply to this email directly, view it on GitHub
> <https://github.com/pandas-dev/pandas/pull/17675#discussion_r141031952>,
> or mute the thread
> <https://github.com/notifications/unsubscribe-auth/ABQHIj7WrfR-Cpu1g9U1bQrEdH6WLX7fks5smOShgaJpZM4Pjbs9>
> .
>

Is there anything I should do here wrt. the CircleCI tests failing? The test failure doesn't seem to related to my PR.
No, you don't need to care, there are some problems in general: https://github.com/pandas-dev/pandas/issues/17702
I've looked some more at the return value. The return is always ``index._values`` and ``index`` is always numerical. So the method does indeed only return integer arrays. I've changed the PR correspondingly.
@topper-123 Thanks a lot!