API: hide NumericIndex from public top-level namespace in favor of pd.Index (#44819)

Author: jorisvandenbossche

doc/source/reference/indexing.rst

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

doc/source/user_guide/advanced.rst

@@ -852,10 +852,9 @@ Int64Index and RangeIndex
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. deprecated:: 1.4.0
-    In pandas 2.0, :class:`NumericIndex` will become the default index type for numeric types
+    In pandas 2.0, :class:`Index` will become the default index type for numeric types
     instead of ``Int64Index``, ``Float64Index`` and ``UInt64Index`` and those index types
     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
@@ -870,10 +869,9 @@ Float64Index
 ~~~~~~~~~~~~
 
 .. deprecated:: 1.4.0
-    :class:`NumericIndex` will become the default index type for numeric types in the future
+    :class:`Index` will become the default index type for numeric types in the future
     instead of ``Int64Index``, ``Float64Index`` and ``UInt64Index`` and those index types
     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.
@@ -971,37 +969,6 @@ 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 :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:
-
-.. 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 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.).
-
 .. _advanced.intervalindex:
 
 IntervalIndex

doc/source/whatsnew/v0.16.2.rst

@@ -62,6 +62,7 @@ When the function you wish to apply takes its data anywhere other than the first
 of ``(function, keyword)`` indicating where the DataFrame should flow. For example:
 
 .. ipython:: python
+   :okwarning:
 
    import statsmodels.formula.api as sm
 

doc/source/whatsnew/v1.4.0.rst

@@ -40,55 +40,6 @@ This made it difficult to determine where the warning was being generated from.
     A value is trying to be set on a copy of a slice from a DataFrame.
 
 
-.. _whatsnew_140.enhancements.numeric_index:
-
-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 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')
-
-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:
-
-.. ipython:: python
-
-    idx = pd.NumericIndex([1, 2, 3], dtype="int8")
-    ser = pd.Series([1, 2, 3], index=idx)
-    ser.index
-
-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 about :class:`NumericIndex`.
 
 
 .. _whatsnew_140.enhancements.ExtensionIndex:
@@ -541,12 +492,33 @@ Deprecations
 
 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`).
+in favor of the base :class:`Index` class and will be removed in Pandas 2.0 (:issue:`43028`).
+
+For constructing a numeric index, you can use the base :class:`Index` class instead
+specifying the data type (which will also work on older pandas releases):
+
+.. code-block:: python
+
+    # replace
+    pd.Int64Index([1, 2, 3])
+    # with
+    pd.Index([1, 2, 3], dtype="int64")
+
+For checking the data type of an index object, you can replace ``isinstance``
+checks with checking the ``dtype``:
+
+.. code-block:: python
+
+    # replace
+    isinstance(idx, pd.Int64Index)
+    # with
+    idx.dtype == "int64"
 
 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.
+when given numeric data, but in the future, an :class:`Index` will be returned.
 
 *Current behavior*:
 
@@ -562,9 +534,9 @@ when given numeric data, but in the future, a :class:`NumericIndex` will be retu
 .. code-block:: ipython
 
     In [3]: pd.Index([1, 2, 3], dtype="int32")
-    Out [3]: NumericIndex([1, 2, 3], dtype='int32')
+    Out [3]: Index([1, 2, 3], dtype='int32')
     In [4]: pd.Index([1, 2, 3], dtype="uint64")
-    Out [4]: NumericIndex([1, 2, 3], dtype='uint64')
+    Out [4]: Index([1, 2, 3], dtype='uint64')
 
 
 .. _whatsnew_140.deprecations.frame_series_append:

pandas/__init__.py

@@ -73,7 +73,6 @@
     Index,
     CategoricalIndex,
     RangeIndex,
-    NumericIndex,
     MultiIndex,
     IntervalIndex,
     TimedeltaIndex,
@@ -199,7 +198,7 @@ def __getattr__(name):
         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.",
+            "Use pandas.Index with the appropriate dtype instead.",
             FutureWarning,
             stacklevel=2,
         )
@@ -335,7 +334,6 @@ def __getattr__(name):
     "NA",
     "NaT",
     "NamedAgg",
-    "NumericIndex",
     "Period",
     "PeriodDtype",
     "PeriodIndex",

pandas/_testing/__init__.py

@@ -44,7 +44,6 @@
     Index,
     IntervalIndex,
     MultiIndex,
-    NumericIndex,
     RangeIndex,
     Series,
     bdate_range,
@@ -107,6 +106,7 @@
 from pandas.core.api import (
     Float64Index,
     Int64Index,
+    NumericIndex,
     UInt64Index,
 )
 from pandas.core.arrays import (

pandas/core/indexes/category.py

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

pandas/core/indexes/numeric.py

@@ -82,13 +82,6 @@ class NumericIndex(Index):
     An NumericIndex instance can **only** contain numpy int64/32/16/8, uint64/32/16/8 or
     float64/32/16 dtype. In particular, ``NumericIndex`` *can not* hold Pandas numeric
     dtypes (:class:`Int64Dtype`, :class:`Int32Dtype` etc.).
-
-    Examples
-    --------
-    >>> pd.NumericIndex([1, 2, 3], dtype="int8")
-    NumericIndex([1, 2, 3], dtype='int8')
-    >>> pd.NumericIndex([1, 2, 3], dtype="float32")
-    NumericIndex([1.0, 2.0, 3.0], dtype='float32')
     """
 
     _typ = "numericindex"

pandas/tests/api/test_api.py

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

pandas/tests/base/test_unique.py

@@ -4,8 +4,8 @@
 from pandas.core.dtypes.common import is_datetime64tz_dtype
 
 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

@@ -21,7 +21,6 @@
     Index,
     IntervalIndex,
     MultiIndex,
-    NumericIndex,
     PeriodIndex,
     RangeIndex,
     Series,
@@ -32,6 +31,7 @@
 from pandas.core.api import (  # noqa:F401
     Float64Index,
     Int64Index,
+    NumericIndex,
     UInt64Index,
 )
 from pandas.core.arrays import BaseMaskedArray

pandas/tests/indexes/multi/test_names.py

@@ -148,7 +148,7 @@ def test_setting_names_from_levels_raises():
         new.index.name = "bar"
 
     assert pd.Index._no_setting_name is False
-    assert pd.NumericIndex._no_setting_name is False
+    assert pd.core.api.NumericIndex._no_setting_name is False
     assert pd.RangeIndex._no_setting_name is False
 
 

pandas/tests/indexes/numeric/test_numeric.py

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

pandas/tests/indexes/test_base.py

@@ -16,7 +16,6 @@
     DataFrame,
     DatetimeIndex,
     IntervalIndex,
-    NumericIndex,
     PeriodIndex,
     RangeIndex,
     Series,
@@ -28,6 +27,7 @@
 from pandas.core.api import (
     Float64Index,
     Int64Index,
+    NumericIndex,
     UInt64Index,
 )
 from pandas.core.indexes.api import (

pandas/tests/indexes/test_common.py

@@ -20,12 +20,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,13 +5,15 @@
     CategoricalIndex,
     DatetimeIndex,
     Index,
-    NumericIndex,
     PeriodIndex,
     TimedeltaIndex,
     isna,
 )
 import pandas._testing as tm
-from pandas.core.api import Float64Index
+from pandas.core.api import (
+    Float64Index,
+    NumericIndex,
+)
 from pandas.core.arrays import BooleanArray
 from pandas.core.indexes.datetimelike import DatetimeIndexOpsMixin