API: Add pandas.api.typing

[rhshadrach]

Revision 2:

Currently many intermediate classes can only be found in pandas.core, for example DataFrameGroupBy and SeriesGroupBy. These classes should not be instantiated directly, but may be necessary to access for users who use type-hinting. I think we should add these classes to a new API submodule, pandas.api.aux as they are auxiliary classes. Users shouldn't need to know e.g. they are defined in pandas.core.groupby.generic.

Somewhat related: #6944, #19302

cc @pandas-dev/pandas-core @pandas-dev/pandas-triage for feedback.

Original

Currently one cannot run `from pandas import DataFrameGroupBy, SeriesGroupBy`. We should add these classes to the top level as they are particularly important for type-hinting in user code. Users shouldn't need to know they are defined in `pandas.core.groupby.generic`.

Revision 1

Currently one cannot run `from pandas import DataFrameGroupBy, SeriesGroupBy`. We should add these classes to a new API submodule, `pandas.api.trying` as they are particularly important for type-hinting in user code. Users shouldn't need to know they are defined in `pandas.core.groupby.generic`.

[jbrockmendel]

makes sense for typing purposes, but does it make sense for users to use these directly?

[rhshadrach]

I would say no - they should only be invoked via DataFrame.groupby or Series.groupby. We could introduce code that raises when third party code calls their __init__ by inspecting the stack, but I would prefer adding the classes to the API docs with the warning that they should not be instantiated directly.

[topper-123]

I agree this is useful for typing purposes but otherwise not, so I'm -1 on putting them is the main namespace. I suggest they go into pd.api.types namespace, either directly or in a is_groupby function.

[rhshadrach]

Thanks @topper-123. I don't believe is_groupby is sufficient for users when it comes to type-hinting, e.g. def foo(gb: DataFrameGroupBy) -> pd.DataFrame: .... The only downside I see to putting them in pd.api.types is it seems harder for users to discover, but perhaps that will change overtime. I also don't see the benefit of putting them here as opposed to top-level, can you comment on that @topper-123?

[topper-123]

Hi @rhshadrach. I'm positive to adding the groupby classes to the public namespace and my only hesitance is whether to put them in the main namespace or not.

My feeling is that the main namespace is very crowded already and so should be added to only sparingly, and these two classes will not be instantiated directly from the main namespace, so it may be confusing having them there. pd.api.types seems like that kind where we keep specialized typing functionality, so could fit there.

[rhshadrach]

I think the idea of having the main namespace be "objects / functions users should create / use" is a meaningful one, so +1 on putting this somewhere else. Looking through the current entries, the only potential class I see that a user should likely not be constructing themselves is Flags.

Currently, pd.api.types contains classes and functions for working with dtypes. This would be an expansion of that focus which makes me hesitant here. I am wondering if it would be more appropriate to introduce pd.api.typing for type-hinting related objects, namely classes that should not be directly instantiated and aliases.