Skip to content

DOC: Refactor numeric index docs #14985

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

DOC: Refactor numeric index docs #14985

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 24 additions & 15 deletions pandas/indexes/base.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1128,17 +1128,17 @@ def is_mixed(self):
def holds_integer(self):
return self.inferred_type in ['integer', 'mixed-integer']

# validate / convert indexers
def _convert_scalar_indexer(self, key, kind=None):
"""
convert a scalar indexer
_index_shared_docs['_convert_scalar_indexer'] = """
Convert a scalar indexer.

Parameters
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also a blank line missing above 'Parameters' here I think

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch. Done.

----------
key : label of the slice bound
kind : {'ix', 'loc', 'getitem', 'iloc'} or None
"""
"""

@Appender(_index_shared_docs['_convert_scalar_indexer'])
def _convert_scalar_indexer(self, key, kind=None):
assert kind in ['ix', 'loc', 'getitem', 'iloc', None]

if kind == 'iloc':
Expand Down Expand Up @@ -1173,15 +1173,20 @@ def _convert_scalar_indexer(self, key, kind=None):

return key

def _convert_slice_indexer(self, key, kind=None):
"""
convert a slice indexer. disallow floats in the start/stop/step
_index_shared_docs['_convert_slice_indexer'] = """
Convert a slice indexer.

By definition, these are labels unless 'iloc' is passed in.
Floats are not allowed as the start, step, or stop of the slice.

Parameters
----------
key : label of the slice bound
kind : {'ix', 'loc', 'getitem', 'iloc'} or None
"""
"""

@Appender(_index_shared_docs['_convert_slice_indexer'])
def _convert_slice_indexer(self, key, kind=None):
assert kind in ['ix', 'loc', 'getitem', 'iloc', None]

# if we are not a slice, then we are done
Expand Down Expand Up @@ -2102,9 +2107,8 @@ def _get_unique_index(self, dropna=False):

return self._shallow_copy(values)

def get_loc(self, key, method=None, tolerance=None):
"""
Get integer location for requested label
_index_shared_docs['get_loc'] = """
Get integer location for requested label.

Parameters
----------
Expand All @@ -2125,7 +2129,10 @@ def get_loc(self, key, method=None, tolerance=None):
Returns
-------
loc : int if unique index, possibly slice or mask if not
"""
"""

@Appender(_index_shared_docs['get_loc'])
def get_loc(self, key, method=None, tolerance=None):
if method is None:
if tolerance is not None:
raise ValueError('tolerance argument only valid if using pad, '
Expand Down Expand Up @@ -3047,8 +3054,7 @@ def _validate_indexer(self, form, key, kind):
self._invalid_indexer(form, key)
return key

def _maybe_cast_slice_bound(self, label, side, kind):
"""
_index_shared_docs['_maybe_cast_slice_bound'] = """
This function should be overloaded in subclasses that allow non-trivial
casting on label-slice bounds, e.g. datetime-like indices allowing
strings containing formatted datetimes.
Expand All @@ -3068,6 +3074,9 @@ def _maybe_cast_slice_bound(self, label, side, kind):
Value of `side` parameter should be validated in caller.

"""

@Appender(_index_shared_docs['_maybe_cast_slice_bound'])
def _maybe_cast_slice_bound(self, label, side, kind):
assert kind in ['ix', 'loc', 'getitem', None]

# We are a plain index here (sub-class override this method if they
Expand Down
102 changes: 36 additions & 66 deletions pandas/indexes/numeric.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,9 @@
import pandas.indexes.base as ibase


_num_index_shared_docs = dict()


class NumericIndex(Index):
"""
Provide numeric type operations
Expand Down Expand Up @@ -47,27 +50,8 @@ def __new__(cls, data=None, dtype=None, copy=False, name=None,
name = data.name
return cls._simple_new(subarr, name=name)

@Appender(_index_shared_docs['_maybe_cast_slice_bound'])
def _maybe_cast_slice_bound(self, label, side, kind):
"""
This function should be overloaded in subclasses that allow non-trivial
casting on label-slice bounds, e.g. datetime-like indices allowing
strings containing formatted datetimes.

Parameters
----------
label : object
side : {'left', 'right'}
kind : {'ix', 'loc', 'getitem'}

Returns
-------
label : object

Notes
-----
Value of `side` parameter should be validated in caller.

"""
assert kind in ['ix', 'loc', 'getitem', None]

# we will try to coerce to integers
Expand All @@ -90,27 +74,37 @@ def _assert_safe_casting(cls, data, subarr):
pass


class Int64Index(NumericIndex):
"""
_num_index_shared_docs['class_descr'] = """
Immutable ndarray implementing an ordered, sliceable set. The basic object
storing axis labels for all pandas objects. Int64Index is a special case
of `Index` with purely integer labels. This is the default index type used
by the DataFrame and Series ctors when no explicit index is provided by the
user.
storing axis labels for all pandas objects. %(klass)s is a special case
of `Index` with purely %(ltype)s labels. %(extra)s

Parameters
----------
data : array-like (1-dimensional)
dtype : NumPy dtype (default: int64)
dtype : NumPy dtype (default: %(dtype)s)
copy : bool
Make a copy of input ndarray
name : object
Name to be stored in the index

Notes
-----
An Index instance can **only** contain hashable objects
"""
An Index instance can **only** contain hashable objects.
"""

_int64_descr_args = dict(
klass='Int64Index',
ltype='integer',
dtype='int64',
extra="""This is the default index type used
by the DataFrame and Series ctors when no explicit
index is provided by the user.
"""
)


class Int64Index(NumericIndex):
__doc__ = _num_index_shared_docs['class_descr'] % _int64_descr_args

_typ = 'int64index'
_arrmap = _algos.arrmap_int64
Expand Down Expand Up @@ -141,16 +135,8 @@ def is_all_dates(self):
"""
return False

@Appender(_index_shared_docs['_convert_scalar_indexer'])
def _convert_scalar_indexer(self, key, kind=None):
"""
convert a scalar indexer

Parameters
----------
key : label of the slice bound
kind : {'ix', 'loc', 'getitem'} or None
"""

assert kind in ['ix', 'loc', 'getitem', 'iloc', None]

# don't coerce ilocs to integers
Expand All @@ -177,25 +163,16 @@ def _assert_safe_casting(cls, data, subarr):
Int64Index._add_logical_methods()


class Float64Index(NumericIndex):
"""
Immutable ndarray implementing an ordered, sliceable set. The basic object
storing axis labels for all pandas objects. Float64Index is a special case
of `Index` with purely floating point labels.
_float64_descr_args = dict(
klass='Float64Index',
dtype='float64',
ltype='float',
extra=''
)

Parameters
----------
data : array-like (1-dimensional)
dtype : NumPy dtype (default: object)
copy : bool
Make a copy of input ndarray
name : object
Name to be stored in the index

Notes
-----
An Float64Index instance can **only** contain hashable objects
"""
class Float64Index(NumericIndex):
__doc__ = _num_index_shared_docs['class_descr'] % _float64_descr_args

_typ = 'float64index'
_engine_type = _index.Float64Engine
Expand Down Expand Up @@ -228,6 +205,7 @@ def astype(self, dtype, copy=True):
self.__class__)
return Index(values, name=self.name, dtype=dtype)

@Appender(_index_shared_docs['_convert_scalar_indexer'])
def _convert_scalar_indexer(self, key, kind=None):
"""
convert a scalar indexer
Expand All @@ -245,17 +223,8 @@ def _convert_scalar_indexer(self, key, kind=None):

return key

@Appender(_index_shared_docs['_convert_slice_indexer'])
def _convert_slice_indexer(self, key, kind=None):
"""
convert a slice indexer, by definition these are labels
unless we are iloc

Parameters
----------
key : label of the slice bound
kind : optional, type of the indexing operation (loc/ix/iloc/None)
"""

# if we are not a slice, then we are done
if not isinstance(key, slice):
return key
Expand Down Expand Up @@ -325,6 +294,7 @@ def __contains__(self, other):
except:
return False

@Appender(_index_shared_docs['get_loc'])
def get_loc(self, key, method=None, tolerance=None):
try:
if np.all(np.isnan(key)):
Expand Down