DEPR: Int64Index, UInt64Index & Float64Index

Author: topper-123

doc/source/user_guide/advanced.rst

@@ -851,11 +851,11 @@ values **not** in the categories, similarly to how you can reindex **any** panda
 Int64Index and RangeIndex
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. note::
-
+.. deprecated:: 1.4.0
     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.
+    are therefore deprecated and will be removed in Pandas 2.0.
+    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
@@ -869,11 +869,11 @@ implementing an ordered, sliceable set.
 Float64Index
 ~~~~~~~~~~~~
 
-.. note::
-
+.. deprecated:: 1.4.0
     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.
+    are therefore deprecated and will be removed in Pandas 2.0.
+    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.
@@ -981,9 +981,9 @@ NumericIndex
 .. 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.
+    instead of :class:`Int64Index`, :class:`Float64Index` and :class:`UInt64Index` and those index types
+    are therefore deprecated and will be removed in Pandas 2.0.
+    :class:`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:
 

doc/source/whatsnew/v1.4.0.rst

@@ -38,19 +38,18 @@ For example, the code below returns an ``Int64Index`` with dtype ``int64``:
     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``:
+More generally, for the duration of Pandas 1.x, 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:
+Instead, if you want to use a ``NumericIndex`` in Pandas 1.x, you should do:
 
 .. ipython:: python
 
@@ -59,7 +58,8 @@ Instead if you want to use a ``NumericIndex``, you should do:
     ser.index
 
 In Pandas 2.0, :class:`NumericIndex` will become the default numeric index type and
-``Int64Index``, ``UInt64Index`` and ``Float64Index`` will be removed.
+``Int64Index``, ``UInt64Index`` and ``Float64Index`` are therefore deprecated and will
+be removed in pandas 2.0.
 
 See :ref:`here <advanced.numericindex>` for more.
 
@@ -199,6 +199,9 @@ Other API changes
 
 Deprecations
 ~~~~~~~~~~~~
+- Deprecated :class:`Int64Index` (:issue:`xxxxx`).
+- Deprecated :class:`UInt64Index` (:issue:`xxxxx`).
+- Deprecated :class:`Float64Index` (:issue:`xxxxx`).
 - Deprecated :meth:`Index.is_type_compatible` (:issue:`42113`)
 - Deprecated ``method`` argument in :meth:`Index.get_loc`, use ``index.get_indexer([label], method=...)`` instead (:issue:`42269`)
 - Deprecated treating integer keys in :meth:`Series.__setitem__` as positional when the index is a :class:`Float64Index` not containing the key, a :class:`IntervalIndex` with no entries containing the key, or a :class:`MultiIndex` with leading :class:`Float64Index` level not containing the key (:issue:`33469`)

pandas/core/indexes/base.py

@@ -276,9 +276,10 @@ class Index(IndexOpsMixin, PandasObject):
     DatetimeIndex : Index of datetime64 data.
     TimedeltaIndex : Index of timedelta64 data.
     PeriodIndex : Index of Period data.
-    Int64Index : A special case of :class:`Index` with purely integer labels.
-    UInt64Index : A special case of :class:`Index` with purely unsigned integer labels.
-    Float64Index : A special case of :class:`Index` with purely float labels.
+    NumericIndex : Index of numpy int/uint/float data.
+    Int64Index : Index of purely int64 labels (deprecated).
+    UInt64Index : Index of purely uint64 labels (deprecated).
+    Float64Index : Index of  purely float64 labels (deprecated).
 
     Notes
     -----

pandas/core/indexes/numeric.py

@@ -42,51 +42,44 @@
     maybe_extract_name,
 )
 
-_num_index_shared_docs = {}
-
 
-_num_index_shared_docs[
-    "class_descr"
-] = """
+class NumericIndex(Index):
+    """
     Immutable sequence used for indexing and alignment. The basic object
-    storing axis labels for all pandas objects. %(klass)s is a special case
-    of `Index` with purely %(ltype)s labels. %(extra)s.
+    storing axis labels for all pandas objects. NumericIndex is a special case
+    of `Index` with purely numpy int/uint/float labels.
+
+    .. versionadded:: 1.4.0
+
+    Notes
+    -----
+    An NumericIndex instance can **only** contain numpy int64/32/16/8, uint64/32/16/8 or
+    float64/32/16 dtype. In Particulat, ``NumericIndex`` *can not* hold Pandas numeric
+    dtypes (:class:`Int64Dtype`, :class:`Int32Dtype` etc.).
 
     Parameters
     ----------
     data : array-like (1-dimensional)
-    dtype : NumPy dtype (default: %(dtype)s)
+    dtype : NumPy dtype (default: None)
     copy : bool
         Make a copy of input ndarray.
     name : object
         Name to be stored in the index.
 
-    Attributes
-    ----------
-    None
-
-    Methods
-    -------
-    None
-
     See Also
     --------
     Index : The base pandas Index type.
+    Int64Index : Index of purely int64 labels (deprecated).
+    UInt64Index : Index of purely uint64 labels (deprecated).
+    Float64Index : Index of  purely float64 labels (deprecated).
 
-    Notes
-    -----
-    An Index instance can **only** contain hashable objects.
-"""
-
-
-class NumericIndex(Index):
-    _index_descr_args = {
-        "klass": "NumericIndex",
-        "ltype": "integer or float",
-        "dtype": "inferred",
-        "extra": "",
-    }
-    __doc__ = _num_index_shared_docs["class_descr"] % _index_descr_args
+    Examples
+    --------
+    >>> pd.NumericIndex([1, 2, 3])
+    NumericIndex([1, 2, 3], dtype='int32')
+    >>> pd.NumericIndex([1, 2, 3], dtype="int8")
+    NumericIndex([1, 2, 3], dtype='int8')
+    """
 
     _typ = "numericindex"
     _values: np.ndarray
@@ -360,6 +353,40 @@ def _format_native_types(
         )
 
 
+_num_index_shared_docs = {}
+
+
+_num_index_shared_docs[
+    "class_descr"
+] = """
+    Immutable sequence used for indexing and alignment. The basic object
+    storing axis labels for all pandas objects. %(klass)s is a special case
+    of `Index` with purely %(ltype)s labels. %(extra)s.
+
+    .. deprecated:: 1.4.0
+        In pandas v2.0 %(klass)s will be removed and :class:`NumericIndex` used instead.
+        %(klass)s will remain fully functional for the duration of pandas 1.x.
+
+    Parameters
+    ----------
+    data : array-like (1-dimensional)
+    dtype : NumPy dtype (default: %(dtype)s)
+    copy : bool
+        Make a copy of input ndarray.
+    name : object
+        Name to be stored in the index.
+
+    See Also
+    --------
+    Index : The base pandas Index type.
+    NumericIndex : Index of numpy int/uint/float data.
+
+    Notes
+    -----
+    An Index instance can **only** contain hashable objects.
+"""
+
+
 class IntegerIndex(NumericIndex):
     """
     This is an abstract class for Int64Index, UInt64Index.