diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 7fa64e0b4ca91..6101d11e98b37 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -1034,7 +1034,7 @@ def _indexer(self): setattr(self, iname, i) return i - setattr(cls, name, property(_indexer)) + setattr(cls, name, property(_indexer, doc=indexer.__doc__)) # add to our internal names set cls._internal_names_set.add(iname) diff --git a/pandas/core/indexing.py b/pandas/core/indexing.py index e305eb828f410..f0543488fcd0d 100644 --- a/pandas/core/indexing.py +++ b/pandas/core/indexing.py @@ -1166,7 +1166,25 @@ def _get_slice_axis(self, slice_obj, axis=0): class _IXIndexer(_NDFrameIndexer): - """ A primarily location based indexer, with integer fallback """ + """A primarily label-location based indexer, with integer position + fallback. + + ``.ix[]`` supports mixed integer and label based access. It is + primarily label based, but will fall back to integer positional + access unless the corresponding axis is of integer type. + + ``.ix`` is the most general indexer and will support any of the + inputs in ``.loc`` and ``.iloc``. ``.ix`` also supports floating + point label schemes. ``.ix`` is exceptionally useful when dealing + with mixed positional and label based hierachical indexes. + + However, when an axis is integer based, ONLY label based access + and not positional access is supported. Thus, in such cases, it's + usually better to be explicit and use ``.iloc`` or ``.loc``. + + See more at :ref:`Advanced Indexing `. + + """ def _has_valid_type(self, key, axis): if isinstance(key, slice): @@ -1224,7 +1242,27 @@ def _get_slice_axis(self, slice_obj, axis=0): class _LocIndexer(_LocationIndexer): - """ purely label based location based indexing """ + """Purely label-location based indexer for selection by label. + + ``.loc[]`` is primarily label based, but may also be used with a + boolean array. + + Allowed inputs are: + + - A single label, e.g. ``5`` or ``'a'``, (note that ``5`` is + interpreted as a *label* of the index, and **never** as an + integer position along the index). + - A list or array of labels, e.g. ``['a', 'b', 'c']``. + - A slice object with labels, e.g. ``'a':'f'`` (note that contrary + to usual python slices, **both** the start and the stop are included!). + - A boolean array. + + ``.loc`` will raise a ``KeyError`` when the items are not found. + + See more at :ref:`Selection by Label ` + + """ + _valid_types = ("labels (MUST BE IN THE INDEX), slices of labels (BOTH " "endpoints included! Can be slices of integers if the " "index is integers), listlike of labels, boolean") @@ -1340,7 +1378,27 @@ def _getitem_axis(self, key, axis=0): class _iLocIndexer(_LocationIndexer): - """ purely integer based location based indexing """ + """Purely integer-location based indexing for selection by position. + + ``.iloc[]`` is primarily integer position based (from ``0`` to + ``length-1`` of the axis), but may also be used with a boolean + array. + + Allowed inputs are: + + - An integer, e.g. ``5``. + - A list or array of integers, e.g. ``[4, 3, 0]``. + - A slice object with ints, e.g. ``1:7``. + - A boolean array. + + ``.iloc`` will raise ``IndexError`` if a requested indexer is + out-of-bounds, except *slice* indexers which allow out-of-bounds + indexing (this conforms with python/numpy *slice* semantics). + + See more at :ref:`Selection by Position ` + + """ + _valid_types = ("integer, integer slice (START point is INCLUDED, END " "point is EXCLUDED), listlike of integers, boolean array") _exception = IndexError @@ -1512,7 +1570,13 @@ def __setitem__(self, key, value): class _AtIndexer(_ScalarAccessIndexer): - """ label based scalar accessor """ + """Fast label-based scalar accessor + + Similarly to ``loc``, ``at`` provides **label** based scalar lookups. + You can also set using these indexers. + + """ + _takeable = False def _convert_key(self, key, is_setter=False): @@ -1535,7 +1599,13 @@ def _convert_key(self, key, is_setter=False): class _iAtIndexer(_ScalarAccessIndexer): - """ integer based scalar accessor """ + """Fast integer location scalar accessor. + + Similarly to ``iloc``, ``iat`` provides **integer** based lookups. + You can also set using these indexers. + + """ + _takeable = True def _has_valid_setitem_indexer(self, indexer):