Add pandas.api.typing module

[jamesdow21]

The pandas.api.typing module was added in pandas 2.1, but is not present in pandas-stubs

To Reproduce

from pandas.api.typing import NAType

mypy gives error: Library stubs not installed for "pandas.api.typing" [import-untyped]

Please complete the following information:

• OS: Windows
• OS Version 10
• Python version 3.12.6
• mypy version 1.13.0
• pandas-stubs version 2.2.3.241009

[loicdiridollou]

I am unable to reproduce the issue on my end, normally mypy should resolve to go to the pandas and not pandas-stubs.
Can you add more detail about where you ran that command (in a library, or just a file)?

[Dr-Irv]

@loicdiridollou See https://pandas.pydata.org/pandas-docs/stable/reference/index.html

About a 18 months ago, we added pandas.api.typing to make it clear what kinds of objects are returned by certain methods. So we need to add that to the stubs. See
https://github.com/pandas-dev/pandas/blob/main/pandas/api/typing/__init__.py

[loicdiridollou]

Okay I am able to reproduce, I was trying to reproduce the issue in the pandas-stubs env, once done in an external dir it is indeed correct.

[loicdiridollou]

@Dr-Irv for context, does that mean doing a similar job to what is in https://github.com/pandas-dev/pandas-stubs/blob/main/pandas-stubs/api/indexers/__init__.pyi where we export the classes?
Happy to take a look and understand how this is done!

[Dr-Irv]

@Dr-Irv for context, does that mean doing a similar job to what is in https://github.com/pandas-dev/pandas-stubs/blob/main/pandas-stubs/api/indexers/__init__.pyi where we export the classes? Happy to take a look and understand how this is done!

Yes, I think this is as simple as copying over the code at https://github.com/pandas-dev/pandas/blob/main/pandas/api/typing/__init__.py, make it a .pyi file, and remove the __all__ = { ... part.

Testing it is another story. I think the tests should be a runtime test that uses each of those types against a runtime object, e.g., assert_type(pd.NA, pandas.api.typing.NAType) (after a suitable import) or for DataFrameGroupBy, something like:

from pandas.api.typing import DataFrameGroupBy

def test_typing():
    df = pd.DataFrame({"a":[1,2,3]})
    check(assert_type(df.groupby("a"), DataFrameGroupBy), DataFrameGroupBy)