BUG : Add Deprecation FutureWarning for parse function call in read_excel

doc/source/whatsnew/v2.0.0.rst

@@ -1342,6 +1342,7 @@ I/O
 - Bug in :func:`read_xml` where file-like objects failed when iterparse is used (:issue:`50641`)
 - Bug in :func:`read_xml` ignored repeated elements when iterparse is used (:issue:`51183`)
 - Bug in :class:`ExcelWriter` leaving file handles open if an exception occurred during instantiation (:issue:`51443`)
+- Bug in :func:`read_excel` where passing invalid argument name ``headers`` to :meth:`parse` doesn't raise error (:issue:`50953`)
 
 Period
 ^^^^^^

pandas/io/excel/_base.py

@@ -21,6 +21,7 @@
     cast,
     overload,
 )
+import warnings
 import zipfile
 
 from pandas._config import (
@@ -47,6 +48,7 @@
     Appender,
     doc,
 )
+from pandas.util._exceptions import find_stack_level
 
 from pandas.core.dtypes.common import (
     is_bool,
@@ -1528,28 +1530,16 @@ def __fspath__(self):
     def parse(
         self,
         sheet_name: str | int | list[int] | list[str] | None = 0,
-        header: int | Sequence[int] | None = 0,
-        names=None,
-        index_col: int | Sequence[int] | None = None,
-        usecols=None,
-        converters=None,
-        true_values: Iterable[Hashable] | None = None,
-        false_values: Iterable[Hashable] | None = None,
-        skiprows: Sequence[int] | int | Callable[[int], object] | None = None,
-        nrows: int | None = None,
-        na_values=None,
-        parse_dates: list | dict | bool = False,
-        date_parser: Callable | lib.NoDefault = lib.no_default,
-        date_format: str | dict[Hashable, str] | None = None,
-        thousands: str | None = None,
-        comment: str | None = None,
-        skipfooter: int = 0,
-        use_nullable_dtypes: bool = False,
+        *args,
         **kwds,
     ) -> DataFrame | dict[str, DataFrame] | dict[int, DataFrame]:
         """
         Parse specified sheet(s) into a DataFrame.
 
+        .. deprecated:: 2.0.0
+            Specifying arguments other than sheet_name by position is deprecated.
+            Specify arguments by keyword name instead.
+
         Equivalent to read_excel(ExcelFile, ...)  See the read_excel
         docstring for more info on accepted parameters.
 
@@ -1558,25 +1548,41 @@ def parse(
         DataFrame or dict of DataFrames
             DataFrame from the passed in Excel file.
         """
+        allowed_kwargs = [
+            "header",
+            "names",
+            "index_col",
+            "usecols",
+            "squeeze",
+            "dtype",
+            "engine",
+            "converters",
+            "true_values",
+            "false_values",
+            "skiprows",
+            "nrows",
+            "na_values",
+            "keep_default_na",
+            "na_filter",
+            "verbose",
+            "parse_dates",
+            "date_parser",
+            "thousands",
+            "decimal",
+            "comment",
+            "skipfooter",
+            "convert_float",
+        ]
+        if any(key in allowed_kwargs for key in kwds):
+            warnings.warn(
+                "Specifying arguments other than sheet_name by position is deprecated."
+                "Specify arguments by keyword name instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
         return self._reader.parse(
-            sheet_name=sheet_name,
-            header=header,
-            names=names,
-            index_col=index_col,
-            usecols=usecols,
-            converters=converters,
-            true_values=true_values,
-            false_values=false_values,
-            skiprows=skiprows,
-            nrows=nrows,
-            na_values=na_values,
-            parse_dates=parse_dates,
-            date_parser=date_parser,
-            date_format=date_format,
-            thousands=thousands,
-            comment=comment,
-            skipfooter=skipfooter,
-            use_nullable_dtypes=use_nullable_dtypes,
+            sheet_name,
+            *args,
             **kwds,
         )
 

pandas/tests/io/excel/test_readers.py

@@ -1676,3 +1676,11 @@ def test_corrupt_files_closed(self, engine, read_ext):
                     pd.ExcelFile(file, engine=engine)
                 except errors:
                     pass
+
+    def test_read_excel_parse_warning(self, read_ext):
+        # GH50953
+        msg = "Specifying arguments other than sheet_name by position is deprecated."
+        "Specify arguments by keyword name instead."
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            with pd.ExcelFile("test1" + read_ext) as excel:
+                excel.parse("Sheet1", header=[0, 1, 2])