DEPR: Int64Index, UInt64Index & Float64Index (pandas-dev#43028)

Author: topper-123

doc/source/user_guide/advanced.rst

@@ -851,12 +851,12 @@ 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.
-    ``RangeIndex`` however, will not be removed, as it represents an optimized version of an integer index.
+    are therefore deprecated and will be removed in a futire version.
+    See :ref:`here <advanced.numericindex>` for more.
+    ``RangeIndex`` 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.
@@ -869,12 +869,12 @@ implementing an ordered, sliceable set.
 Float64Index
 ~~~~~~~~~~~~
 
-.. note::
-
-    In pandas 2.0, :class:`NumericIndex` will become the default index type for numeric types
+.. deprecated:: 1.4.0
+    :class:`NumericIndex` will become the default index type for numeric types in the future
     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.
+    are therefore deprecated and will be removed in a future version of Pandas.
+    See :ref:`here <advanced.numericindex>` for more.
+    ``RangeIndex`` 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
@@ -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 a future version.
+    :class:`RangeIndex` 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:
 
@@ -998,7 +998,7 @@ NumericIndex
 ``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.
+In the future, ``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.).
 

doc/source/whatsnew/v0.20.0.rst

@@ -248,11 +248,12 @@ or purely non-negative, integers. Previously, handling these integers would
 result in improper rounding or data-type casting, leading to incorrect results.
 Notably, a new numerical index, ``UInt64Index``, has been created (:issue:`14937`)
 
-.. ipython:: python
+.. code-block:: ipython
 
-   idx = pd.UInt64Index([1, 2, 3])
-   df = pd.DataFrame({'A': ['a', 'b', 'c']}, index=idx)
-   df.index
+   In [1]: idx = pd.UInt64Index([1, 2, 3])
+   In [2]: df = pd.DataFrame({'A': ['a', 'b', 'c']}, index=idx)
+   In [3]: df.index
+   Out[3]: UInt64Index([1, 2, 3], dtype='uint64')
 
 - Bug in converting object elements of array-like objects to unsigned 64-bit integers (:issue:`4471`, :issue:`14982`)
 - Bug in ``Series.unique()`` in which unsigned 64-bit integers were causing overflow (:issue:`14721`)

doc/source/whatsnew/v0.23.0.rst

@@ -861,21 +861,21 @@ Previous behavior:
 
 Current behavior:
 
-.. ipython:: python
+.. code-block:: ipython
 
-    index = pd.Int64Index([-1, 0, 1])
+    In [12]: index = pd.Int64Index([-1, 0, 1])
     # division by zero gives -infinity where negative,
     # +infinity where positive, and NaN for 0 / 0
-    index / 0
+    In [13]: index / 0
 
     # The result of division by zero should not depend on
     # whether the zero is int or float
-    index / 0.0
+    In [14]: index / 0.0
 
-    index = pd.UInt64Index([0, 1])
-    index / np.array([0, 0], dtype=np.uint64)
+    In [15]: index = pd.UInt64Index([0, 1])
+    In [16]: index / np.array([0, 0], dtype=np.uint64)
 
-    pd.RangeIndex(1, 5) / 0
+    In [17]: pd.RangeIndex(1, 5) / 0
 
 .. _whatsnew_0230.api_breaking.extract:
 

doc/source/whatsnew/v0.25.0.rst

@@ -473,10 +473,12 @@ considered commutative, such that ``A.union(B) == B.union(A)`` (:issue:`23525`).
 
 *New behavior*:
 
-.. ipython:: python
+.. code-block:: python
 
-    pd.period_range('19910905', periods=2).union(pd.Int64Index([1, 2, 3]))
-    pd.Index([], dtype=object).union(pd.Index([1, 2, 3]))
+    In [3]: pd.period_range('19910905', periods=2).union(pd.Int64Index([1, 2, 3]))
+    Out[3]: Index([1991-09-05, 1991-09-06, 1, 2, 3], dtype='object')
+    In [4]: pd.Index([], dtype=object).union(pd.Index([1, 2, 3]))
+    Out[4]: Index([1, 2, 3], dtype='object')
 
 Note that integer- and floating-dtype indexes are considered "compatible". The integer
 values are coerced to floating point, which may result in loss of precision. See

doc/source/whatsnew/v1.4.0.rst

@@ -29,39 +29,41 @@ It is now possible to create an index of any numpy int/uint/float dtype using th
     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`.
+In order to maintain backwards compatibility, calls to the base :class:`Index` will currently
+return :class:`Int64Index`, :class:`UInt64Index` and :class:`Float64Index`, where relevant.
 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``:
+but will in a future version return a :class:`NumericIndex` with dtype ``int8``.
+
+More generally, currently, 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`` in the current version, 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``, 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.
+In a future version of Pandas, :class:`NumericIndex` will become the default numeric index type and
+``Int64Index``, ``UInt64Index`` and ``Float64Index`` are therefore deprecated and will
+be removed in the future, see :ref:`here <whatsnew_140.deprecations.int64_uint64_float64index>` for more.
 
-See :ref:`here <advanced.numericindex>` for more.
+See :ref:`here <advanced.numericindex>` for more about :class:`NumericIndex`.
 
 .. _whatsnew_140.enhancements.styler:
 
@@ -224,6 +226,41 @@ Other API changes
 
 Deprecations
 ~~~~~~~~~~~~
+
+.. _whatsnew_140.deprecations.int64_uint64_float64index:
+
+Deprecated Int64Index, UInt64Index & Float64Index
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+:class:`Int64Index`, :class:`UInt64Index` and :class:`Float64Index` have been deprecated
+in favor of the new :class:`NumericIndex` and will be removed in Pandas 2.0 (:issue:`43028`).
+
+Currently, in order to maintain backward compatibility, calls to
+:class:`Index` will continue to return :class:`Int64Index`, :class:`UInt64Index` and :class:`Float64Index`
+when given numeric data, but in the future, a :class:`NumericIndex` will be returned.
+
+*Current behavior*:
+
+.. code-block:: ipython
+
+    In [1]: pd.Index([1, 2, 3], dtype="int32")
+    Out [1]: Int64Index([1, 2, 3], dtype='int64')
+    In [1]: pd.Index([1, 2, 3], dtype="uint64")
+    Out [1]: UInt64Index([1, 2, 3], dtype='uint64')
+
+*Future behavior*:
+
+.. code-block:: ipython
+
+    In [3]: pd.Index([1, 2, 3], dtype="int32")
+    Out [3]: NumericIndex([1, 2, 3], dtype='int32')
+    In [4]: pd.Index([1, 2, 3], dtype="uint64")
+    Out [4]: NumericIndex([1, 2, 3], dtype='uint64')
+
+
+.. _whatsnew_140.deprecations.other:
+
+Other Deprecations
+^^^^^^^^^^^^^^^^^^
 - 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/__init__.py

@@ -70,10 +70,7 @@
     # indexes
     Index,
     CategoricalIndex,
-    Int64Index,
-    UInt64Index,
     RangeIndex,
-    Float64Index,
     NumericIndex,
     MultiIndex,
     IntervalIndex,
@@ -186,10 +183,35 @@
 
 
 # GH 27101
+__deprecated_num_index_names = ["Float64Index", "Int64Index", "UInt64Index"]
+
+
+def __dir__():
+    # GH43028
+    # Int64Index etc. are deprecated, but we still want them to be available in the dir.
+    # Remove in Pandas 2.0, when we remove Int64Index etc. from the code base.
+    return list(globals().keys()) + __deprecated_num_index_names
+
+
 def __getattr__(name):
     import warnings
 
-    if name == "datetime":
+    if name in __deprecated_num_index_names:
+        warnings.warn(
+            f"pandas.{name} is deprecated "
+            "and will be removed from pandas in a future version. "
+            "Use pandas.NumericIndex with the appropriate dtype instead.",
+            FutureWarning,
+            stacklevel=2,
+        )
+        from pandas.core.api import Float64Index, Int64Index, UInt64Index
+
+        return {
+            "Float64Index": Float64Index,
+            "Int64Index": Int64Index,
+            "UInt64Index": UInt64Index,
+        }[name]
+    elif name == "datetime":
         warnings.warn(
             "The pandas.datetime class is deprecated "
             "and will be removed from pandas in a future version. "

pandas/_testing/__init__.py

@@ -45,15 +45,12 @@
     CategoricalIndex,
     DataFrame,
     DatetimeIndex,
-    Float64Index,
     Index,
-    Int64Index,
     IntervalIndex,
     MultiIndex,
     NumericIndex,
     RangeIndex,
     Series,
-    UInt64Index,
     bdate_range,
 )
 from pandas._testing._io import (  # noqa:F401
@@ -106,6 +103,11 @@
     use_numexpr,
     with_csv_dialect,
 )
+from pandas.core.api import (
+    Float64Index,
+    Int64Index,
+    UInt64Index,
+)
 from pandas.core.arrays import (
     DatetimeArray,
     PandasArray,

pandas/core/algorithms.py

@@ -1334,7 +1334,7 @@ def __init__(self, obj, n: int, keep: str, columns):
 
     def compute(self, method: str) -> DataFrame:
 
-        from pandas import Int64Index
+        from pandas.core.api import Int64Index
 
         n = self.n
         frame = self.obj

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
     -----
@@ -571,15 +572,15 @@ def _dtype_to_subclass(cls, dtype: DtypeObj):
             return TimedeltaIndex
 
         elif is_float_dtype(dtype):
-            from pandas import Float64Index
+            from pandas.core.api import Float64Index
 
             return Float64Index
         elif is_unsigned_integer_dtype(dtype):
-            from pandas import UInt64Index
+            from pandas.core.api import UInt64Index
 
             return UInt64Index
         elif is_signed_integer_dtype(dtype):
-            from pandas import Int64Index
+            from pandas.core.api import Int64Index
 
             return Int64Index