API: Add entrypoint for plotting

Libraries, including pandas, register backends via entrypoints. xref #26747
pandas-dev · jreback · Jul 25, 2019 · Jul 19, 2019 · Jul 20, 2019 · Jul 20, 2019
commit 853bd6649fd4080ff900eb071f52bfa3706b5b2a
diff --git a/doc/source/development/extending.rst b/doc/source/development/extending.rst
@@ -441,5 +441,22 @@ This would be more or less equivalent to:
 The backend module can then use other visualization tools (Bokeh, Altair,...)
 to generate the plots.
 
+Libraries implementing the plotting backend should use `entry points <https://setuptools.readthedocs.io/en/latest/setuptools.html#dynamic-discovery-of-services-and-plugins>`__
+to make their backend discoverable to pandas. The key is ``"pandas_plotting_backends"``. For example, pandas
+registers the default "matplotlib" backend as follows.
+
+.. code-block:: python
+
+   # in setup.py
+   setup(
+       ...
+       entry_points={
+           "pandas_plotting_backends": [
+               "matplotlib = pandas:plotting._matplotlib",
+           ],
+       },
+   )
+
+
 More information on how to implement a third-party plotting backend can be found at
 https://github.com/pandas-dev/pandas/blob/master/pandas/plotting/__init__.py#L1.
diff --git a/doc/source/whatsnew/v0.25.1.rst b/doc/source/whatsnew/v0.25.1.rst
@@ -113,7 +113,7 @@ I/O
 Plotting
 ^^^^^^^^
 
--
+- Added a pandas_plotting_backends entrypoint group for registering plot backends. See :ref:`extending.plotting-backends` for more (:issue:`26747`).
 -
 -
 

diff --git a/pandas/plotting/_core.py b/pandas/plotting/_core.py
@@ -1533,7 +1533,10 @@ def hexbin(self, x, y, C=None, reduce_C_function=None, gridsize=None, **kwargs):
         return self(kind="hexbin", x=x, y=y, C=C, **kwargs)
 
 
-def _get_plot_backend(backend=None):
+_backends = {}
+
+
+def _get_plot_backend(backend="matplotlib"):
     """
     Return the plotting backend to use (e.g. `pandas.plotting._matplotlib`).
 
@@ -1546,7 +1549,23 @@ def _get_plot_backend(backend=None):
     The backend is imported lazily, as matplotlib is a soft dependency, and
     pandas can be used without it being installed.
     """
-    backend_str = backend or pandas.get_option("plotting.backend")
-    if backend_str == "matplotlib":
-        backend_str = "pandas.plotting._matplotlib"
-    return importlib.import_module(backend_str)
+    import pkg_resources  # Delay import for performance.
+
+    if backend in _backends:
+        return _backends[backend]
+
+    for entry_point in pkg_resources.iter_entry_points("pandas_plotting_backends"):
+        _backends[entry_point.name] = entry_point.load()
+
+    try:
+        return _backends[backend]
+    except KeyError:
+        try:
+            module = importlib.import_module(backend)
+        except ImportError:
+            pass
+        else:
+            _backends[backend] = module
+            return module
+
+    raise ValueError("No backend {}".format(backend))
diff --git a/pandas/tests/plotting/test_backend.py b/pandas/tests/plotting/test_backend.py
@@ -1,3 +1,7 @@
+import sys
+import types
+
+import pkg_resources
 import pytest
 
 import pandas
@@ -36,3 +40,30 @@ def test_backend_is_correct(monkeypatch):
         pandas.set_option("plotting.backend", "matplotlib")
     except ImportError:
         pass
+
+
+def test_register_entrypoint():
+    mod = types.ModuleType("my_backend")
+    mod.plot = lambda *args, **kwargs: 1
+
+    backends = pkg_resources.get_entry_map("pandas")
    my_entrypoint = pkg_resources.EntryPoint(
+        "pandas_plotting_backend",
+        mod.__name__,
+        dist=pkg_resources.get_distribution("pandas"),
+    )
+    backends["pandas_plotting_backends"]["my_backend"] = my_entrypoint
+    # TODO: the docs recommend importlib.util.module_from_spec. But this works for now.
+    sys.modules["my_backend"] = mod
+
+    result = pandas.plotting._core._get_plot_backend("my_backend")
+    assert result is mod
+
+
+def test_register_import():
+    mod = types.ModuleType("my_backend2")
+    mod.plot = lambda *args, **kwargs: 1
+    sys.modules["my_backend2"] = mod
+
+    result = pandas.plotting._core._get_plot_backend("my_backend2")
+    assert result is mod
diff --git a/setup.py b/setup.py
@@ -830,5 +830,10 @@ def srcpath(name=None, suffix=".pyx", subdir="src"):
             "hypothesis>=3.58",
         ]
     },
+    entry_points={
+        "pandas_plotting_backends": [
+            "matplotlib = pandas:plotting._matplotlib",
+        ],
+    },
     **setuptools_kwargs
 )
-Original file line number
+Diff line change
@@ Expand Up / @@ -113,7 +113,7 @@ I/O @@
     Plotting
     ^^^^^^^^
-    -
+    - Added a pandas_plotting_backends entrypoint group for registering plot backends. See :ref:`extending.plotting-backends` for more (:issue:`26747`).
     -
     -
@@ Expand Down @@