The signature of `pandas.ExcelFile(...)` in stubs is not consistent with the run-time signature.

[cainmagi]

Describe the bug

In the stubs, the signature of pandas.io.excel.ExcelFile(...) in pandas==2.2.3 supposes to be

ExcelFile(
    path_or_buffer,
    engine: str | None = None,
    storage_options: StorageOptions | None = None,
    engine_kwargs: dict | None = None,
) -> None:

However, the actual implementation in stubs is

pandas-stubs/pandas-stubs/io/excel/_base.pyi

Lines 246 to 251 in 4976e11

	def __init__(
	self,
	io: FilePath | ReadBuffer[bytes] | bytes,
	engine: ExcelReadEngine | None = ...,
	storage_options: StorageOptions = ...,
	) -> None: ...

where

• the first argument name should be path_or_buffer, not io.
• the keyword engine_kwargs is missing.
• the keyword storage_options should allow a None value. Sorry, I found that None case has been included here.

To Reproduce

The following codes will work in run time, but show typing issues by Pylance:

def load_group_data(data_path):
    with ExcelFile(
        path_or_buffer=data_path,
        engine="openpyxl",
        storage_options=None,
        engine_kwargs={"read_only": True, "data_only": True}
    ) as fobj:
        pass

Pyright (with stubs) reports:

Argument missing for parameter "io"
Pylance[reportCallIssue](https://github.com/microsoft/pyright/blob/main/docs/configuration.md#reportCallIssue)
No parameter named "path_or_buffer"
Pylance[reportCallIssue](https://github.com/microsoft/pyright/blob/main/docs/configuration.md#reportCallIssue)
No parameter named "engine_kwargs"
Pylance[reportCallIssue](https://github.com/microsoft/pyright/blob/main/docs/configuration.md#reportCallIssue)

Please complete the following information:

• OS: Linux in Docker
• OS Version: Debain 12
• OS of the native device: Windows 11 Enterprise 24H2, Build 26100.3037
• Docker image: python:3.10-slim
• Docker Version: Docker Desktop 4.38.0 (181591)
• python version: Python 3.10.14
• version of type checker: Pylance language server 2025.2.1 (pyright version 1.1.393, commit 3763156f)
• version of installed pandas-stubs: v2.2.3.241126

[Dr-Irv]

Thanks for the report. PR with tests welcome.

It appears this was not documented in pandas prior to version 2.0, and the release notes never indicated that it became documented.

[cainmagi]

Thank you! I will try to make a PR later.