DEPR: passing an int to read_excel use_cols (#29795)

Author: jbrockmendel

doc/source/whatsnew/v1.0.0.rst

@@ -391,6 +391,7 @@ or ``matplotlib.Axes.plot``. See :ref:`plotting.formatters` for more.
 - Removed the previously deprecated :meth:`ExtensionArray._formatting_values`. Use :attr:`ExtensionArray._formatter` instead. (:issue:`23601`)
 - Removed support for legacy HDF5 formats (:issue:`29787`)
 - :func:`read_excel` removed support for "skip_footer" argument, use "skipfooter" instead (:issue:`18836`)
+- :func:`read_excel` no longer allows an integer value for the parameter ``usecols``, instead pass a list of integers from 0 to ``usecols`` inclusive (:issue:`23635`)
 - :meth:`DataFrame.to_records` no longer supports the argument "convert_datetime64" (:issue:`18902`)
 - Removed the previously deprecated ``IntervalIndex.from_intervals`` in favor of the :class:`IntervalIndex` constructor (:issue:`19263`)
 - Changed the default value for the "keep_tz" argument in :meth:`DatetimeIndex.to_series` to ``True`` (:issue:`23739`)

pandas/io/excel/_util.py

@@ -1,5 +1,3 @@
-import warnings
-
 from pandas.compat._optional import import_optional_dependency
 
 from pandas.core.dtypes.common import is_integer, is_list_like
@@ -136,16 +134,11 @@ def _maybe_convert_usecols(usecols):
         return usecols
 
     if is_integer(usecols):
-        warnings.warn(
-            (
-                "Passing in an integer for `usecols` has been "
-                "deprecated. Please pass in a list of int from "
-                "0 to `usecols` inclusive instead."
-            ),
-            FutureWarning,
-            stacklevel=2,
+        raise ValueError(
+            "Passing an integer for `usecols` is no longer supported.  "
+            "Please pass in a list of int from 0 to `usecols` "
+            "inclusive instead."
         )
-        return list(range(usecols + 1))
 
     if isinstance(usecols, str):
         return _range2cols(usecols)

pandas/tests/io/excel/test_readers.py

@@ -88,27 +88,18 @@ def test_usecols_int(self, read_ext, df_ref):
         df_ref = df_ref.reindex(columns=["A", "B", "C"])
 
         # usecols as int
-        with tm.assert_produces_warning(
-            FutureWarning, check_stacklevel=False, raise_on_extra_warnings=False
-        ):
+        msg = "Passing an integer for `usecols`"
+        with pytest.raises(ValueError, match=msg):
             with ignore_xlrd_time_clock_warning():
-                df1 = pd.read_excel(
-                    "test1" + read_ext, "Sheet1", index_col=0, usecols=3
-                )
+                pd.read_excel("test1" + read_ext, "Sheet1", index_col=0, usecols=3)
 
         # usecols as int
-        with tm.assert_produces_warning(
-            FutureWarning, check_stacklevel=False, raise_on_extra_warnings=False
-        ):
+        with pytest.raises(ValueError, match=msg):
             with ignore_xlrd_time_clock_warning():
-                df2 = pd.read_excel(
+                pd.read_excel(
                     "test1" + read_ext, "Sheet2", skiprows=[1], index_col=0, usecols=3
                 )
 
-        # TODO add index to xls file)
-        tm.assert_frame_equal(df1, df_ref, check_names=False)
-        tm.assert_frame_equal(df2, df_ref, check_names=False)
-
     def test_usecols_list(self, read_ext, df_ref):
 
         df_ref = df_ref.reindex(columns=["B", "C"])