DEPR: allowing subclass-specific keywords in pd.Index.__new__ (pandas-dev#38597)

Author: jbrockmendel

doc/source/whatsnew/v1.3.0.rst

@@ -143,7 +143,7 @@ Other API changes
 
 Deprecations
 ~~~~~~~~~~~~
-
+- Deprecated allowing subclass-specific keyword arguments in the :class:`Index` constructor, use the specific subclass directly instead (:issue:`14093`,:issue:`21311`,:issue:`22315`,:issue:`26974`)
 -
 -
 

pandas/core/indexes/base.py

@@ -252,6 +252,15 @@ def __new__(
         cls, data=None, dtype=None, copy=False, name=None, tupleize_cols=True, **kwargs
     ) -> "Index":
 
+        if kwargs:
+            warnings.warn(
+                "Passing keywords other than 'data', 'dtype', 'copy', 'name', "
+                "'tupleize_cols' is deprecated and will raise TypeError in a "
+                "future version.  Use the specific Index subclass directly instead",
+                FutureWarning,
+                stacklevel=2,
+            )
+
         from pandas.core.indexes.range import RangeIndex
 
         name = maybe_extract_name(name, data, cls)

pandas/core/indexes/datetimelike.py

@@ -147,7 +147,7 @@ def __array_wrap__(self, result, context=None):
         if not is_period_dtype(self.dtype) and attrs["freq"]:
             # no need to infer if freq is None
             attrs["freq"] = "infer"
-        return Index(result, **attrs)
+        return type(self)(result, **attrs)
 
     # ------------------------------------------------------------------------
 

pandas/core/resample.py

@@ -1966,6 +1966,10 @@ def _asfreq_compat(index, freq):
     new_index: Index
     if isinstance(index, PeriodIndex):
         new_index = index.asfreq(freq=freq)
-    else:
-        new_index = Index([], dtype=index.dtype, freq=freq, name=index.name)
+    elif isinstance(index, DatetimeIndex):
+        new_index = DatetimeIndex([], dtype=index.dtype, freq=freq, name=index.name)
+    elif isinstance(index, TimedeltaIndex):
+        new_index = TimedeltaIndex([], dtype=index.dtype, freq=freq, name=index.name)
+    else:  # pragma: no cover
+        raise TypeError(type(index))
     return new_index

pandas/io/pytables.py

@@ -12,6 +12,7 @@
 from typing import (
     TYPE_CHECKING,
     Any,
+    Callable,
     Dict,
     List,
     Optional,
@@ -2045,15 +2046,19 @@ def convert(self, values: np.ndarray, nan_rep, encoding: str, errors: str):
         if self.freq is not None:
             kwargs["freq"] = _ensure_decoded(self.freq)
 
+        factory: Union[Type[Index], Type[DatetimeIndex]] = Index
+        if is_datetime64_dtype(values.dtype) or is_datetime64tz_dtype(values.dtype):
+            factory = DatetimeIndex
+
         # making an Index instance could throw a number of different errors
         try:
-            new_pd_index = Index(values, **kwargs)
+            new_pd_index = factory(values, **kwargs)
         except ValueError:
             # if the output freq is different that what we recorded,
             # it should be None (see also 'doc example part 2')
             if "freq" in kwargs:
                 kwargs["freq"] = None
-            new_pd_index = Index(values, **kwargs)
+            new_pd_index = factory(values, **kwargs)
 
         new_pd_index = _set_tz(new_pd_index, self.tz)
         return new_pd_index, new_pd_index
@@ -2736,8 +2741,14 @@ def _alias_to_class(self, alias):
             return alias
         return self._reverse_index_map.get(alias, Index)
 
-    def _get_index_factory(self, klass):
-        if klass == DatetimeIndex:
+    def _get_index_factory(self, attrs):
+        index_class = self._alias_to_class(
+            _ensure_decoded(getattr(attrs, "index_class", ""))
+        )
+
+        factory: Callable
+
+        if index_class == DatetimeIndex:
 
             def f(values, freq=None, tz=None):
                 # data are already in UTC, localize and convert if tz present
@@ -2747,16 +2758,34 @@ def f(values, freq=None, tz=None):
                     result = result.tz_localize("UTC").tz_convert(tz)
                 return result
 
-            return f
-        elif klass == PeriodIndex:
+            factory = f
+        elif index_class == PeriodIndex:
 
             def f(values, freq=None, tz=None):
                 parr = PeriodArray._simple_new(values, freq=freq)
                 return PeriodIndex._simple_new(parr, name=None)
 
-            return f
+            factory = f
+        else:
+            factory = index_class
+
+        kwargs = {}
+        if "freq" in attrs:
+            kwargs["freq"] = attrs["freq"]
+            if index_class is Index:
+                # DTI/PI would be gotten by _alias_to_class
+                factory = TimedeltaIndex
+
+        if "tz" in attrs:
+            if isinstance(attrs["tz"], bytes):
+                # created by python2
+                kwargs["tz"] = attrs["tz"].decode("utf-8")
+            else:
+                # created by python3
+                kwargs["tz"] = attrs["tz"]
+            assert index_class is DatetimeIndex  # just checking
 
-        return klass
+        return factory, kwargs
 
     def validate_read(self, columns, where):
         """
@@ -2928,22 +2957,8 @@ def read_index_node(
             name = _ensure_str(node._v_attrs.name)
             name = _ensure_decoded(name)
 
-        index_class = self._alias_to_class(
-            _ensure_decoded(getattr(node._v_attrs, "index_class", ""))
-        )
-        factory = self._get_index_factory(index_class)
-
-        kwargs = {}
-        if "freq" in node._v_attrs:
-            kwargs["freq"] = node._v_attrs["freq"]
-
-        if "tz" in node._v_attrs:
-            if isinstance(node._v_attrs["tz"], bytes):
-                # created by python2
-                kwargs["tz"] = node._v_attrs["tz"].decode("utf-8")
-            else:
-                # created by python3
-                kwargs["tz"] = node._v_attrs["tz"]
+        attrs = node._v_attrs
+        factory, kwargs = self._get_index_factory(attrs)
 
         if kind == "date":
             index = factory(

pandas/tests/groupby/test_grouping.py

@@ -254,7 +254,8 @@ def test_grouper_creation_bug(self):
         )
         result = s.groupby(pd.Grouper(level="three", freq="M")).sum()
         expected = Series(
-            [28], index=Index([Timestamp("2013-01-31")], freq="M", name="three")
+            [28],
+            index=pd.DatetimeIndex([Timestamp("2013-01-31")], freq="M", name="three"),
         )
         tm.assert_series_equal(result, expected)
 

pandas/tests/groupby/test_quantile.py

@@ -271,7 +271,7 @@ def test_columns_groupby_quantile():
             [9.6, 8.4, 10.6, 9.4],
         ],
         index=list("XYZ"),
-        columns=Index(
+        columns=pd.MultiIndex.from_tuples(
             [("A", 0.8), ("A", 0.2), ("B", 0.8), ("B", 0.2)], names=["col", None]
         ),
     )

pandas/tests/indexes/base_class/test_constructors.py

@@ -2,6 +2,7 @@
 import pytest
 
 from pandas import Index, MultiIndex
+import pandas._testing as tm
 
 
 class TestIndexConstructor:
@@ -29,7 +30,8 @@ def test_construction_list_mixed_tuples(self, index_vals):
     def test_constructor_wrong_kwargs(self):
         # GH #19348
         with pytest.raises(TypeError, match="Unexpected keyword arguments {'foo'}"):
-            Index([], foo="bar")
+            with tm.assert_produces_warning(FutureWarning):
+                Index([], foo="bar")
 
     @pytest.mark.xfail(reason="see GH#21311: Index doesn't enforce dtype argument")
     def test_constructor_cast(self):

pandas/tests/indexes/categorical/test_constructors.py

@@ -129,10 +129,14 @@ def test_construction_with_categorical_dtype(self):
             CategoricalIndex(data, categories=cats, dtype=dtype)
 
         with pytest.raises(ValueError, match=msg):
-            Index(data, categories=cats, dtype=dtype)
+            with tm.assert_produces_warning(FutureWarning):
+                # passing subclass-specific kwargs to pd.Index
+                Index(data, categories=cats, dtype=dtype)
 
         with pytest.raises(ValueError, match=msg):
             CategoricalIndex(data, ordered=ordered, dtype=dtype)
 
         with pytest.raises(ValueError, match=msg):
-            Index(data, ordered=ordered, dtype=dtype)
+            with tm.assert_produces_warning(FutureWarning):
+                # passing subclass-specific kwargs to pd.Index
+                Index(data, ordered=ordered, dtype=dtype)

pandas/tests/indexes/datetimes/test_constructors.py

@@ -374,7 +374,9 @@ def test_construction_index_with_mixed_timezones_with_NaT(self):
         assert result.tz is None
 
         # all NaT with tz
-        result = Index([pd.NaT, pd.NaT], tz="Asia/Tokyo", name="idx")
+        with tm.assert_produces_warning(FutureWarning):
+            # subclass-specific kwargs to pd.Index
+            result = Index([pd.NaT, pd.NaT], tz="Asia/Tokyo", name="idx")
         exp = DatetimeIndex([pd.NaT, pd.NaT], tz="Asia/Tokyo", name="idx")
 
         tm.assert_index_equal(result, exp, exact=True)
@@ -462,16 +464,18 @@ def test_construction_dti_with_mixed_timezones(self):
         with pytest.raises(ValueError, match=msg):
             # passing tz should results in DatetimeIndex, then mismatch raises
             # TypeError
-            Index(
-                [
-                    pd.NaT,
-                    Timestamp("2011-01-01 10:00"),
-                    pd.NaT,
-                    Timestamp("2011-01-02 10:00", tz="US/Eastern"),
-                ],
-                tz="Asia/Tokyo",
-                name="idx",
-            )
+            with tm.assert_produces_warning(FutureWarning):
+                # subclass-specific kwargs to pd.Index
+                Index(
+                    [
+                        pd.NaT,
+                        Timestamp("2011-01-01 10:00"),
+                        pd.NaT,
+                        Timestamp("2011-01-02 10:00", tz="US/Eastern"),
+                    ],
+                    tz="Asia/Tokyo",
+                    name="idx",
+                )
 
     def test_construction_base_constructor(self):
         arr = [Timestamp("2011-01-01"), pd.NaT, Timestamp("2011-01-03")]