Load style files from third-party packages.

anntzer · anntzer · commit 94e7b03b3ab7 · 2022-10-23T14:21:20.000+02:00
diff --git a/doc/users/next_whats_new/styles_from_packages.rst b/doc/users/next_whats_new/styles_from_packages.rst
@@ -0,0 +1,10 @@
+Style files can be imported from third-party packages
+-----------------------------------------------------
+
+Third-party packages can now distribute style files that are globally available
+as follows.  Assume that a package is importable as ``import my.package``, with
+a ``my/package/__init__.py`` module.  Then a
+``my/package/presentation.mplstyle`` style sheet can be used as
+``plt.style.use("my.package.presentation")``.  (Note that the implementation
+does not actually import ``my.package``, making this process safe against
+possible import-time side effects.)
diff --git a/lib/matplotlib/style/core.py b/lib/matplotlib/style/core.py
@@ -12,6 +12,7 @@
 """
 
 import contextlib
+import importlib.resources
 import logging
 import os
 from pathlib import Path
@@ -63,20 +64,27 @@ def use(style):
     Parameters
     ----------
     style : str, dict, Path or list
-        A style specification. Valid options are:
 
-        +------+-------------------------------------------------------------+
-        | str  | The name of a style or a path/URL to a style file. For a    |
-        |      | list of available style names, see `.style.available`.      |
-        +------+-------------------------------------------------------------+
-        | dict | Dictionary with valid key/value pairs for                   |
-        |      | `matplotlib.rcParams`.                                      |
-        +------+-------------------------------------------------------------+
-        | Path | A path-like object which is a path to a style file.         |
-        +------+-------------------------------------------------------------+
-        | list | A list of style specifiers (str, Path or dict) applied from |
-        |      | first to last in the list.                                  |
-        +------+-------------------------------------------------------------+
+        A style specification.
+
+        - If a str, this can be one of the style names in `.style.available`
+          (a builtin style or a style installed in the user library path).
+
+          This can also be a dotted name of the form "package.name.style_name";
+          in that case, "package.name" should be an importable Python package
+          name, e.g. at ``/path/to/package/name/__init__.py``; the loaded style
+          file is ``/path/to/package/name/style_name.mplstyle``.
+
+          This can also be the path or URL to a style file, which gets loaded
+          by `.rc_params_from_file`.
+
+        - If a dict, this is a mapping of key/value pairs for `.rcParams`.
+
+        - If a Path, this is the path to a style file, which gets loaded by
+          `.rc_params_from_file`.
+
+        - If a list, this is a a list of style specifiers (str, Path or dict),
+          which get applied from first to last in the list.
 
     Notes
     -----
@@ -130,6 +138,20 @@ def use(style):
                              if k not in STYLE_BLACKLIST}
             elif style in library:
                 style = library[style]
+            elif "." in style:
+                pkg, name = style.rsplit(".")
+                try:
+                    with importlib.resources.path(
+                            pkg, f"{name}.{STYLE_EXTENSION}") as path:
+                        style = _rc_params_in_file(path)
+                except (ModuleNotFoundError, IOError):
+                    # There is an ambiguity whether a dotted name refers to a
+                    # package.style_name or to a dotted file path.  Currently,
+                    # we silently try the first form and then the second one;
+                    # in the future, we may consider forcing file paths to
+                    # either use Path objects or be prepended with "./" and use
+                    # the slash as marker for file paths.
+                    pass
         if isinstance(style, (str, Path)):
             try:
                 style = _rc_params_in_file(style)
diff --git a/lib/matplotlib/tests/test_style.py b/lib/matplotlib/tests/test_style.py
@@ -188,3 +188,13 @@ def test_deprecated_seaborn_styles():
 
 def test_up_to_date_blacklist():
     assert mpl.style.core.STYLE_BLACKLIST <= {*mpl.rcsetup._validators}
+
+
+def test_style_from_module(tmp_path, monkeypatch):
+    monkeypatch.syspath_prepend(tmp_path)
+    pkg_path = tmp_path / "mpl_test_style_pkg"
+    pkg_path.mkdir()
+    (pkg_path / "test_style.mplstyle").write_text(
+        f"{PARAM}: {VALUE}", encoding="utf-8")
+    mpl.style.use("mpl_test_style_pkg.test_style")
+    assert mpl.rcParams[PARAM] == VALUE
diff --git a/tutorials/introductory/customizing.py b/tutorials/introductory/customizing.py
@@ -137,6 +137,12 @@ def plotting_function():
 #    >>> import matplotlib.pyplot as plt
 #    >>> plt.style.use('./images/presentation.mplstyle')
 #
+# You can include style sheets into standard importable Python packages (which
+# can be e.g. distributed on PyPI).  If your package is importable as
+# ``import my.package``, with a ``my/package/__init__.py`` module, and you add
+# a ``my/package/presentation.mplstyle`` style sheet, then in can be used as
+# ``plt.style.use("my.package.presentation")``.
+#
 # Alternatively, you can make your style known to Matplotlib by placing
 # your ``<style-name>.mplstyle`` file into ``mpl_configdir/stylelib``.  You
 # can then load your custom style sheet with a call to
@@ -156,6 +162,9 @@ def plotting_function():
 #    >>> import matplotlib.pyplot as plt
 #    >>> plt.style.use(<style-name>)
 #
+# The approach of using ``mpl_configdir`` should be considered legacy, as it
+# does not allow distribution on PyPI.
+#
 #
 # Composing styles
 # ----------------
