API: Add pandas.api.typing

doc/source/reference/index.rst

@@ -9,11 +9,24 @@ API reference
 This page gives an overview of all public pandas objects, functions and
 methods. All classes and functions exposed in ``pandas.*`` namespace are public.
 
-Some subpackages are public which include ``pandas.errors``,
-``pandas.plotting``, and ``pandas.testing``. Public functions in
-``pandas.io`` and ``pandas.tseries`` submodules are mentioned in
-the documentation. ``pandas.api.types`` subpackage holds some
-public functions related to data types in pandas.
+The following subpackages are public.
+
+ - ``pandas.errors``: Custom exception and warnings classes that are raised by pandas.
+ - ``pandas.plotting``: Plotting public API.
+ - ``pandas.testing``: Functions that are useful for writing tests involving pandas objects.
+ - ``pandas.api.extensions``: Functions and classes for extending pandas objects.
+ - ``pandas.api.indexers``: Functions and classes for rolling window indexers.
+ - ``pandas.api.interchange``: DataFrame interchange protocol.
+ - ``pandas.api.types``: Datatype classes and functions.
+ - ``pandas.api.typing``: Classes that may be necessary for type-hinting. These are
+   classes that are encountered as intermediates results but should not be
+   instantiated  directly by users. These classes are not to be confused with
+   classes from the `pandas-stubs <https://github.com/pandas-dev/pandas-stubs>`_
+   package which has classes in addition to those that occur in pandas for type-hinting.
+
+In addition, public functions in ``pandas.io`` and ``pandas.tseries`` submodules
+are mentioned in the documentation.
+
 
 .. warning::
 

doc/source/whatsnew/v2.0.0.rst

@@ -497,6 +497,7 @@ Other API changes
   methods to get a full slice (for example ``df.loc[:]`` or ``df[:]``) (:issue:`49469`)
 - Disallow computing ``cumprod`` for :class:`Timedelta` object; previously this returned incorrect values (:issue:`50246`)
 - :func:`to_datetime` with ``unit`` of either "Y" or "M" will now raise if a sequence contains a non-round ``float`` value, matching the ``Timestamp`` behavior (:issue:`50301`)
+- Classes that are useful for type-hinting have been added to the public API in the new submodule ``pandas.api.typing`` (:issue:`48577`)
 -
 
 .. ---------------------------------------------------------------------------

pandas/api/__init__.py

@@ -4,11 +4,13 @@
     indexers,
     interchange,
     types,
+    typing,
 )
 
 __all__ = [
     "interchange",
     "extensions",
     "indexers",
     "types",
+    "typing",
 ]

pandas/api/typing/__init__.py

@@ -0,0 +1,40 @@
+"""
+Public API classes that store intermediate results useful for type-hinting.
+"""
+
+from pandas.core.groupby import (
+    DataFrameGroupBy,
+    SeriesGroupBy,
+)
+from pandas.core.resample import (
+    Resampler,
+    TimeGrouper,
+)
+from pandas.core.window import (
+    Expanding,
+    ExponentialMovingWindow,
+    Rolling,
+    Window,
+)
+
+from pandas.io.formats.style import Styler
+from pandas.io.json._json import JsonReader
+from pandas.io.stata import (
+    StataReader,
+    StataWriter,
+)
+
+__all__ = [
+    "DataFrameGroupBy",
+    "Expanding",
+    "ExponentialMovingWindow",
+    "JsonReader",
+    "Resampler",
+    "Rolling",
+    "SeriesGroupBy",
+    "StataWriter",
+    "StataReader",
+    "Styler",
+    "TimeGrouper",
+    "Window",
+]

pandas/tests/api/test_api.py

@@ -235,7 +235,7 @@ def test_depr(self):
 
 
 class TestApi(Base):
-    allowed = ["types", "extensions", "indexers", "interchange"]
+    allowed = ["types", "extensions", "indexers", "interchange", "typing"]
 
     def test_api(self):
         self.check(api, self.allowed)

pandas/tests/plotting/test_converter.py

@@ -48,6 +48,7 @@ def test_registry_mpl_resets():
     code = (
         "import matplotlib.units as units; "
         "import matplotlib.dates as mdates; "
+        "import matplotlib.pyplot as plt; "
         "n_conv = len(units.registry); "
         "import pandas as pd; "
         "pd.plotting.register_matplotlib_converters(); "