Excel function is partially unknown if optional packages aren't installed

[umichfagan]

Describe the bug
My specific issue was: DataFrame.to_excel() is partially unknown unless the optional Excel packages are installed.

To Reproduce
I am using basedpyright on strict mode. If I don't have all of xlsxwriter, pyxlsb, and odfpy installed, then the function to_excel() is reported as partially unknown.

def streaming_download(
    data: pandas.DataFrame, filename: str, filetype: str
) -> flask.Response:
    headers = {
        "Content-Disposition": f"attachment; filename={filename}.{filetype}",
    }

    def generate():
        stream = io.BytesIO()
        if filetype == "csv":
            data.to_csv(stream, index=False)
        else:
            data.to_excel(stream, index=False)
        yield stream.getvalue()

    return flask.Response(generate(), headers=headers)

error: Type of "to_excel" is partially unknown
Type of "to_excel" is "(excel_writer: str | PathLike[str] | WriteExcelBuffer | ExcelWriter[Workbook | Unknown], sheet_name: str = "Sheet1", na_rep: str = "", float_format: str | None = ..., columns: str | Sequence[str] | None = ..., header: bool | list[str] = True, index: bool = True, index_label: str | Sequence[str] | None = ..., startrow: int = 0, startcol: int = 0, engine: str | None = ..., merge_cells: bool | Literal['columns'] = True, inf_rep: str = "inf", freeze_panes: tuple[int, int] | None = ...) -> None" (reportUnknownMemberType)

Specs:

# MacOS Tahoe
# python 3.14
pandas==3.0.2
openpyxl==3.1.5
basedpyright==1.39.3
pandas-stubs==3.0.3.260530

# to fix...
# xlsxwriter==3.2.9
# pyxlsb==1.0.10
# odfpy==1.4.1

Additional context
I only found the intended fix (adding these three packages) because of this comment on issue #1710.

I think it'd be great to have this behavior documented somewhere (maybe it already is and I couldn't find it?). If there are other optional dependencies, those would be great to have documented too.

I also wonder if this topic could be approached differently -- maybe something like how pandas specifies optional extras (e.g. pandas-stubs[excel] so that it is bundled together? Just an idea. Thanks for the work.

[Dr-Irv]

Well, your code would have failed without those packages installed! Since the packages are optional for pandas, they are optional for pandas-stubs as well. We do our tests with everything installed to support all the use cases.

I don't know of a way that the type checker/stubs can know if a package is installed or not. Open to suggestions.

[umichfagan]

Sorry, maybe I should have written a runnable snippet for this. My code does run, because openpyxl is installed, and pandas will fallback to openpyxl if xlsxwriter isn't available. As for pyxlsb and odfpy, my application doesn't deal with xlsb or OpenDocument files so they're never needed either (but I now see how my function, in isolation, would appear to support any variety of filetype -- oops).

There might not be a better solution, I'll leave that to you all. But I do think it would be great to have this documented somewhere -- it's unexpected that I have to install certain optional pandas packages that I'm not actually using in order for the checks to succeed. Thanks.

[Dr-Irv]

actually, I now see the problem. You wrote:

I am using basedpyright on strict mode.

We do test with strict mode, but we include this option:

reportMissingModuleSource = true

If you did the same, you'd have seen the issue.

I guess we could document that if people want to use strict mode, we could list the dependencies required. Or document that the setting above should be used so you know if you're dependent on a missing module.