DOC: NumericIndex (#42706)

Author: topper-123

doc/source/reference/indexing.rst

@@ -170,6 +170,7 @@ Numeric Index
    :toctree: api/
    :template: autosummary/class_without_autosummary.rst
 
+   NumericIndex
    RangeIndex
    Int64Index
    UInt64Index

doc/source/user_guide/advanced.rst

@@ -7,7 +7,7 @@ MultiIndex / advanced indexing
 ******************************
 
 This section covers :ref:`indexing with a MultiIndex <advanced.hierarchical>`
-and :ref:`other advanced indexing features <indexing.index_types>`.
+and :ref:`other advanced indexing features <advanced.index_types>`.
 
 See the :ref:`Indexing and Selecting Data <indexing>` for general indexing documentation.
 
@@ -738,7 +738,7 @@ faster than fancy indexing.
    %timeit ser.iloc[indexer]
    %timeit ser.take(indexer)
 
-.. _indexing.index_types:
+.. _advanced.index_types:
 
 Index types
 -----------
@@ -749,7 +749,7 @@ and documentation about ``TimedeltaIndex`` is found :ref:`here <timedeltas.index
 
 In the following sub-sections we will highlight some other index types.
 
-.. _indexing.categoricalindex:
+.. _advanced.categoricalindex:
 
 CategoricalIndex
 ~~~~~~~~~~~~~~~~
@@ -846,22 +846,36 @@ values **not** in the categories, similarly to how you can reindex **any** panda
       In [1]: pd.concat([df4, df5])
       TypeError: categories must match existing categories when appending
 
-.. _indexing.rangeindex:
+.. _advanced.rangeindex:
 
 Int64Index and RangeIndex
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
+.. note::
+
+    In pandas 2.0, :class:`NumericIndex` will become the default index type for numeric types
+    instead of ``Int64Index``, ``Float64Index`` and ``UInt64Index`` and those index types
+    will be removed. See :ref:`here <advanced.numericindex>` for more.
+    ``RangeIndex`` however, will not be removed, as it represents an optimized version of an integer index.
+
 :class:`Int64Index` is a fundamental basic index in pandas. This is an immutable array
 implementing an ordered, sliceable set.
 
 :class:`RangeIndex` is a sub-class of ``Int64Index``  that provides the default index for all ``NDFrame`` objects.
 ``RangeIndex`` is an optimized version of ``Int64Index`` that can represent a monotonic ordered set. These are analogous to Python `range types <https://docs.python.org/3/library/stdtypes.html#typesseq-range>`__.
 
-.. _indexing.float64index:
+.. _advanced.float64index:
 
 Float64Index
 ~~~~~~~~~~~~
 
+.. note::
+
+    In pandas 2.0, :class:`NumericIndex` will become the default index type for numeric types
+    instead of ``Int64Index``, ``Float64Index`` and ``UInt64Index`` and those index types
+    will be removed. See :ref:`here <advanced.numericindex>` for more.
+    ``RangeIndex`` however, will not be removed, as it represents an optimized version of an integer index.
+
 By default a :class:`Float64Index` will be automatically created when passing floating, or mixed-integer-floating values in index creation.
 This enables a pure label-based slicing paradigm that makes ``[],ix,loc`` for scalar indexing and slicing work exactly the
 same.
@@ -956,6 +970,38 @@ If you need integer based selection, you should use ``iloc``:
 
    dfir.iloc[0:5]
 
+
+.. _advanced.numericindex:
+
+NumericIndex
+~~~~~~~~~~~~
+
+.. versionadded:: 1.4.0
+
+.. note::
+
+    In pandas 2.0, :class:`NumericIndex` will become the default index type for numeric types
+    instead of ``Int64Index``, ``Float64Index`` and ``UInt64Index`` and those index types
+    will be removed.
+    ``RangeIndex`` however, will not be removed, as it represents an optimized version of an integer index.
+
+:class:`NumericIndex` is an index type that can hold data of any numpy int/uint/float dtype. For example:
+
+.. ipython:: python
+
+   idx = pd.NumericIndex([1, 2, 4, 5], dtype="int8")
+   idx
+   ser = pd.Series(range(4), index=idx)
+   ser
+
+``NumericIndex`` works the same way as the existing ``Int64Index``, ``Float64Index`` and
+``UInt64Index`` except that it can hold any numpy int, uint or float dtype.
+
+Until Pandas 2.0, you will have to call ``NumericIndex`` explicitly in order to use it, like in the example above.
+In Pandas 2.0, ``NumericIndex`` will become the default pandas numeric index type and will automatically be used where appropriate.
+
+Please notice that ``NumericIndex`` *can not* hold Pandas numeric dtypes (:class:`Int64Dtype`, :class:`Int32Dtype` etc.).
+
 .. _advanced.intervalindex:
 
 IntervalIndex

doc/source/user_guide/categorical.rst

@@ -1141,7 +1141,7 @@ Categorical index
 ``CategoricalIndex`` is a type of index that is useful for supporting
 indexing with duplicates. This is a container around a ``Categorical``
 and allows efficient indexing and storage of an index with a large number of duplicated elements.
-See the :ref:`advanced indexing docs <indexing.categoricalindex>` for a more detailed
+See the :ref:`advanced indexing docs <advanced.categoricalindex>` for a more detailed
 explanation.
 
 Setting the index will create a ``CategoricalIndex``:

doc/source/whatsnew/v0.13.0.rst

@@ -310,7 +310,7 @@ Float64Index API change
 
 - Added a new index type, ``Float64Index``. This will be automatically created when passing floating values in index creation.
   This enables a pure label-based slicing paradigm that makes ``[],ix,loc`` for scalar indexing and slicing work exactly the
-  same. See :ref:`the docs<indexing.float64index>`, (:issue:`263`)
+  same. See :ref:`the docs<advanced.float64index>`, (:issue:`263`)
 
   Construction is by default for floating type values.
 

doc/source/whatsnew/v0.16.1.rst

@@ -168,7 +168,7 @@ values NOT in the categories, similarly to how you can reindex ANY pandas index.
                                  ordered=False, name='B',
                                  dtype='category')
 
-See the :ref:`documentation <indexing.categoricalindex>` for more. (:issue:`7629`, :issue:`10038`, :issue:`10039`)
+See the :ref:`documentation <advanced.categoricalindex>` for more. (:issue:`7629`, :issue:`10038`, :issue:`10039`)
 
 .. _whatsnew_0161.enhancements.sample:
 

doc/source/whatsnew/v1.4.0.rst

@@ -15,10 +15,53 @@ including other versions of pandas.
 Enhancements
 ~~~~~~~~~~~~
 
-.. _whatsnew_140.enhancements.enhancement1:
+.. _whatsnew_140.enhancements.numeric_index:
 
-enhancement1
-^^^^^^^^^^^^
+More flexible numeric dtypes for indexes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Until now, it has only been possible to create numeric indexes with int64/float64/uint64 dtypes.
+It is now possible to create an index of any numpy int/uint/float dtype using the new :class:`NumericIndex` index type (:issue:`41153`):
+
+.. ipython:: python
+
+    pd.NumericIndex([1, 2, 3], dtype="int8")
+    pd.NumericIndex([1, 2, 3], dtype="uint32")
+    pd.NumericIndex([1, 2, 3], dtype="float32")
+
+In order to maintain backwards compatibility, calls to the base :class:`Index` will in
+pandas 1.x. return :class:`Int64Index`, :class:`UInt64Index` and :class:`Float64Index`.
+For example, the code below returns an ``Int64Index`` with dtype ``int64``:
+
+.. code-block:: ipython
+
+    In [1]: pd.Index([1, 2, 3], dtype="int8")
+    Int64Index([1, 2, 3], dtype='int64')
+
+For the duration of Pandas 1.x, in order to maintain backwards compatibility, all
+operations that until now have returned :class:`Int64Index`, :class:`UInt64Index` and
+:class:`Float64Index` will continue to so. This means, that in order to use
+``NumericIndex``, you will have to call ``NumericIndex`` explicitly. For example the below series
+will have an ``Int64Index``:
+
+.. code-block:: ipython
+
+    In [2]: ser = pd.Series([1, 2, 3], index=[1, 2, 3])
+    In [3]: ser.index
+    Int64Index([1, 2, 3], dtype='int64')
+
+Instead if you want to use a ``NumericIndex``, you should do:
+
+.. ipython:: python
+
+    idx = pd.NumericIndex([1, 2, 3], dtype="int8")
+    ser = pd.Series([1, 2, 3], index=idx)
+    ser.index
+
+In Pandas 2.0, :class:`NumericIndex` will become the default numeric index type and
+``Int64Index``, ``UInt64Index`` and ``Float64Index`` will be removed.
+
+See :ref:`here <advanced.numericindex>` for more.
 
 .. _whatsnew_140.enhancements.enhancement2:
 

pandas/__init__.py

@@ -75,6 +75,7 @@
     UInt64Index,
     RangeIndex,
     Float64Index,
+    NumericIndex,
     MultiIndex,
     IntervalIndex,
     TimedeltaIndex,

pandas/_testing/__init__.py

@@ -50,6 +50,7 @@
     Int64Index,
     IntervalIndex,
     MultiIndex,
+    NumericIndex,
     RangeIndex,
     Series,
     UInt64Index,
@@ -105,7 +106,6 @@
     use_numexpr,
     with_csv_dialect,
 )
-from pandas.core.api import NumericIndex
 from pandas.core.arrays import (
     DatetimeArray,
     PandasArray,

pandas/core/indexes/category.py

@@ -283,7 +283,7 @@ def _is_dtype_compat(self, other) -> Categorical:
 
     @doc(Index.astype)
     def astype(self, dtype: Dtype, copy: bool = True) -> Index:
-        from pandas.core.api import NumericIndex
+        from pandas import NumericIndex
 
         dtype = pandas_dtype(dtype)
 

pandas/tests/api/test_api.py

@@ -68,6 +68,7 @@ class TestPDApi(Base):
         "Index",
         "Int64Index",
         "MultiIndex",
+        "NumericIndex",
         "Period",
         "PeriodIndex",
         "RangeIndex",

pandas/tests/base/test_unique.py

@@ -9,8 +9,8 @@
 )
 
 import pandas as pd
+from pandas import NumericIndex
 import pandas._testing as tm
-from pandas.core.api import NumericIndex
 from pandas.tests.base.common import allow_na_ops
 
 

pandas/tests/indexes/common.py

@@ -26,6 +26,7 @@
     Int64Index,
     IntervalIndex,
     MultiIndex,
+    NumericIndex,
     PeriodIndex,
     RangeIndex,
     Series,
@@ -34,7 +35,6 @@
 )
 from pandas import UInt64Index  # noqa:F401
 import pandas._testing as tm
-from pandas.core.api import NumericIndex
 from pandas.core.indexes.datetimelike import DatetimeIndexOpsMixin
 
 

pandas/tests/indexes/numeric/test_numeric.py

@@ -8,11 +8,11 @@
     Float64Index,
     Index,
     Int64Index,
+    NumericIndex,
     Series,
     UInt64Index,
 )
 import pandas._testing as tm
-from pandas.core.api import NumericIndex
 from pandas.tests.indexes.common import NumericBase
 
 

pandas/tests/indexes/test_common.py

@@ -21,12 +21,12 @@
     CategoricalIndex,
     DatetimeIndex,
     MultiIndex,
+    NumericIndex,
     PeriodIndex,
     RangeIndex,
     TimedeltaIndex,
 )
 import pandas._testing as tm
-from pandas.core.api import NumericIndex
 
 
 class TestCommon:

pandas/tests/indexes/test_numpy_compat.py

@@ -5,11 +5,11 @@
     DatetimeIndex,
     Float64Index,
     Index,
+    NumericIndex,
     PeriodIndex,
     TimedeltaIndex,
 )
 import pandas._testing as tm
-from pandas.core.api import NumericIndex
 from pandas.core.indexes.datetimelike import DatetimeIndexOpsMixin