GH1055 Add pandas.api.typing to pandas-stubs

[loicdiridollou]

• Closes Add pandas.api.typing module #1055
• Tests added: Please use assert_type() to assert the type of any return value

[loicdiridollou]

Haven't written tests for every case, I first want to get feedback on the structure and if I am going the right direction.

[Dr-Irv]

If we can't do assert_type on the pandas.api.typing objects, then we may have to change the stubs to support that.

[Dr-Irv]

So this structure is fine. Now you need to add tests for all of the other things in pandas.api.typing

[Dr-Irv]

So I see that your tests failed and I played around with it. The purpose of the types in pandas.api.typing is to allow people to use the types in functions. Because we are doing things with Generic, we have to change the test. E.g., for DataFrameGroupBy:

def test_dataframegroupby():
    df = pd.DataFrame({"a": [1, 2, 3]})
    group = df.groupby("a")

    def f1(gb: DataFrameGroupBy):
        check(group, DataFrameGroupBy)

    f1(group)

We can't use the check(assert_type pattern here because of the Generic. But for this particular part of the API, it would be good to add a test like the one above, because that is the anticipated usage. This will do a typing check via the function call and an isinstance check as a result of the use of check .

You'd only have to do this for the ones that are Generic inside of the stubs. Otherwise the standard check(assert_type(... pattern is fine, like you did with NAType

[loicdiridollou]

Thanks for the trick here!
One issue is that one of the type can only be obtained through a deprecated resampling, not sure what to do about this one.

[Dr-Irv]

one small change to use TypeAlias

[Dr-Irv]

thanks @loicdiridollou