DOC: NumericIndex

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

@@ -851,6 +851,13 @@ values **not** in the categories, similarly to how you can reindex **any** panda
 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.
 
@@ -862,6 +869,13 @@ implementing an ordered, sliceable set.
 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]
 
+
+.. _indexing.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. See :ref:`here <advanced.numericindex>` for more.
+    ``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
+
+   index = pd.NumericIndex([1, 2, 4, 5], dtype="int8")
+   index
+   ser = pd.Series(range(5), index=index)
+   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/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,
+but not with lower bit sizes (int32, int8, uint32, uint8 etc). It is now possible to create
+an index of any numpy dtype using the new :class:`NumericIndex` (: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, notice that 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 it explicitly. For example:
+
+.. 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:
+
+.. code-block:: ipython
+
+    In [2]: ser = pd.Series([1, 2, 3], index=pd.NumericIndex([1, 2, 3], dtype="int8"))
+    In [3]: ser.index
+     NumericIndex([1, 2, 3], dtype='int8')
+
+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: