DOC: Index.get_loc Cannot Accept List-like Tolerance

[WillAyd]

The docs for Index.get_loc suggest that the tolerance parameter may accept both a scalar and list-like argument. However, I don't think this is actually possible:

# Can only pass scalar label to unique Index, so tolerance cannot be list-like
>>> pd.Index([0, 1, 2]).get_loc(1)
1
>>> pd.Index([0, 1, 2]).get_loc([1, 1])
TypeError: '[1, 1]' is an invalid key

# Inexact matches do not work against non-unique index
>>> pd.Index([1, 1, 2]).get_loc(1.1, method='nearest')
pandas.core.indexes.base.InvalidIndexError: Reindexing only valid with uniquely valued Index objects

In short I don't think this method can ever return a list using inexact matches. IIUC the documented list-like tolerance argument is therefore invalid.

I don't see any tests for this behavior and my assumption is it was documented as part of this methods overlap with get_indexer, but the documentation for get_loc should be updated to reflect what can actually be accepted

[jreback]

is this just a doc issue? the above looks correct

[WillAyd]

If the above is all correct then yes it is a doc issue. Below is taken directly from the API docs:

"Tolerance may be a scalar value, which applies the same tolerance to all values, or list-like, which applies variable tolerance per element..."

[jreback]

yeah above is correct
not sure if it’s noted but get_loc requires a unique index

[WillAyd]

I think that limitation only applies when doing anything but an exact match.

>>> index = pd.Index([1, 1, 1])
>>> index.get_loc(1)
slice(0, 3, None)
>>> index.get_loc(1, method='pad')
pandas.core.indexes.base.InvalidIndexError: Reindexing only valid with uniquely valued Index objects

The docs even provide an example of this. Regardless good opportunity for cleanup here