API: Add pandas.api.typing

Author: rhshadrach

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

@@ -600,6 +600,7 @@ Other API changes
 - Disallow computing ``cumprod`` for :class:`Timedelta` object; previously this returned incorrect values (:issue:`50246`)
 - Loading a JSON file with duplicate columns using ``read_json(orient='split')`` renames columns to avoid duplicates, as :func:`read_csv` and the other readers do (:issue:`50370`)
 - :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,42 @@
+"""
+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,
+)
+
+# TODO: Can't import Styler without impacting registered matplotlib converters
+# 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",
+    # See TODO above
+    # "Styler",
+    "TimeGrouper",
+    "Window",
+]

pandas/io/formats/style.py

@@ -52,9 +52,6 @@
 from pandas.core.shared_docs import _shared_docs
 
 from pandas.io.formats.format import save_to_buffer
-
-jinja2 = import_optional_dependency("jinja2", extra="DataFrame.style requires jinja2.")
-
 from pandas.io.formats.style_render import (
     CSSProperties,
     CSSStyles,
@@ -71,20 +68,15 @@
 if TYPE_CHECKING:
     from matplotlib.colors import Colormap
 
-try:
-    import matplotlib as mpl
-    import matplotlib.pyplot as plt
-
-    has_mpl = True
-except ImportError:
-    has_mpl = False
-
 
 @contextmanager
 def _mpl(func: Callable) -> Generator[tuple[Any, Any], None, None]:
-    if has_mpl:
+    try:
+        import matplotlib as mpl
+        import matplotlib.pyplot as plt
+
         yield plt, mpl
-    else:
+    except ImportError:
         raise ImportError(f"{func.__name__} requires matplotlib.")
 
 
@@ -3420,6 +3412,9 @@ def from_custom_template(
             Has the correct ``env``,``template_html``, ``template_html_table`` and
             ``template_html_style`` class attributes set.
         """
+        jinja2 = import_optional_dependency(
+            "jinja2", extra="DataFrame.style requires jinja2."
+        )
         loader = jinja2.ChoiceLoader([jinja2.FileSystemLoader(searchpath), cls.loader])
 
         # mypy doesn't like dynamically-defined classes

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)