Merge branch 'main' into pan-zoom-3d

scottshambaugh · scottshambaugh · commit 1cdc5aa37b47 · 2022-09-05T20:49:05.000-06:00
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -153,7 +153,12 @@ commands:
     steps:
       - run:
           name: Bundle sphinx-gallery documentation artifacts
-          command: tar cf doc/build/sphinx-gallery-files.tar.gz doc/api/_as_gen doc/gallery doc/tutorials
+          command: >
+            tar cf doc/build/sphinx-gallery-files.tar.gz
+            doc/api/_as_gen
+            doc/gallery
+            doc/plot_types
+            doc/tutorials
           when: always
       - store_artifacts:
           path: doc/build/sphinx-gallery-files.tar.gz
diff --git a/.github/workflows/nightlies.yml b/.github/workflows/nightlies.yml
@@ -49,7 +49,7 @@ jobs:
 
         # N.B. anaconda-client is only maintained on the main channel
       - name: Install anaconda-client
-        uses: mamba-org/provision-with-micromamba@v12
+        uses: mamba-org/provision-with-micromamba@v13
         with:
           environment-file: false
           environment-name: nightlies
diff --git a/doc/conf.py b/doc/conf.py
@@ -16,6 +16,7 @@
 import shutil
 import subprocess
 import sys
+from urllib.parse import urlsplit, urlunsplit
 import warnings
 
 import matplotlib
@@ -248,10 +249,6 @@ def matplotlib_reduced_latex_scraper(block, block_vars, gallery_conf,
 except (subprocess.CalledProcessError, FileNotFoundError):
     SHA = matplotlib.__version__
 
-html_context = {
-    "sha": SHA,
-}
-
 project = 'Matplotlib'
 copyright = (
     '2002–2012 John Hunter, Darren Dale, Eric Firing, Michael Droettboom '
@@ -312,16 +309,50 @@ def matplotlib_reduced_latex_scraper(block, block_vars, gallery_conf,
 
 github_project_url = "https://github.com/matplotlib/matplotlib/"
 
+
 # Options for HTML output
 # -----------------------
 
+def add_html_cache_busting(app, pagename, templatename, context, doctree):
+    """
+    Add cache busting query on CSS and JavaScript assets.
+
+    This adds the Matplotlib version as a query to the link reference in the
+    HTML, if the path is not absolute (i.e., it comes from the `_static`
+    directory) and doesn't already have a query.
+    """
+    from sphinx.builders.html import Stylesheet, JavaScript
+
+    css_tag = context['css_tag']
+    js_tag = context['js_tag']
+
+    def css_tag_with_cache_busting(css):
+        if isinstance(css, Stylesheet) and css.filename is not None:
+            url = urlsplit(css.filename)
+            if not url.netloc and not url.query:
+                url = url._replace(query=SHA)
+                css = Stylesheet(urlunsplit(url), priority=css.priority,
+                                 **css.attributes)
+        return css_tag(css)
+
+    def js_tag_with_cache_busting(js):
+        if isinstance(js, JavaScript) and js.filename is not None:
+            url = urlsplit(js.filename)
+            if not url.netloc and not url.query:
+                url = url._replace(query=SHA)
+                js = JavaScript(urlunsplit(url), priority=js.priority,
+                                **js.attributes)
+        return js_tag(js)
+
+    context['css_tag'] = css_tag_with_cache_busting
+    context['js_tag'] = js_tag_with_cache_busting
+
+
 # The style sheet to use for HTML and HTML Help pages. A file of that name
 # must exist either in Sphinx' static/ path, or in one of the custom paths
 # given in html_static_path.
-# html_style = 'matplotlib.css'
-# html_style = f"mpl.css?{SHA}"
 html_css_files = [
-    f"mpl.css?{SHA}",
+    "mpl.css",
 ]
 
 html_theme = "mpl_sphinx_theme"
@@ -574,14 +605,6 @@ def matplotlib_reduced_latex_scraper(block, block_vars, gallery_conf,
 # https://github.com/sphinx-doc/sphinx/issues/3176
 # graphviz_output_format = 'svg'
 
-
-def setup(app):
-    if any(st in version for st in ('post', 'alpha', 'beta')):
-        bld_type = 'dev'
-    else:
-        bld_type = 'rel'
-    app.add_config_value('releaselevel', bld_type, 'env')
-
 # -----------------------------------------------------------------------------
 # Source code links
 # -----------------------------------------------------------------------------
@@ -649,3 +672,15 @@ def linkcode_resolve(domain, info):
                 f"/{tag}/lib/{fn}{linespec}")
 else:
     extensions.append('sphinx.ext.viewcode')
+
+
+# -----------------------------------------------------------------------------
+# Sphinx setup
+# -----------------------------------------------------------------------------
+def setup(app):
+    if any(st in version for st in ('post', 'dev', 'alpha', 'beta')):
+        bld_type = 'dev'
+    else:
+        bld_type = 'rel'
+    app.add_config_value('releaselevel', bld_type, 'env')
+    app.connect('html-page-context', add_html_cache_busting, priority=1000)
diff --git a/doc/users/explain/backends.rst b/doc/users/explain/backends.rst
@@ -107,7 +107,7 @@ allows both interactive work and plotting from scripts, with output to the
 screen and/or to a file, so at least initially, you will not need to worry
 about the backend.  The most common exception is if your Python distribution
 comes without :mod:`tkinter` and you have no other GUI toolkit installed.
-This happens on certain Linux distributions, where you need to install a
+This happens with certain Linux distributions, where you need to install a
 Linux package named ``python-tk`` (or similar).
 
 If, however, you want to write graphical user interfaces, or a web
diff --git a/doc/users/explain/interactive.rst b/doc/users/explain/interactive.rst
@@ -169,7 +169,7 @@ and run the GUI event loop for the specified period of time.
 
 The GUI event loop being integrated with your command prompt and
 the figures being in interactive mode are independent of each other.
-If you use `pyplot.ion` but have not arranged for the event loop integration,
+If you try to use `pyplot.ion` without arranging for the event-loop integration,
 your figures will appear but will not be interactive while the prompt is waiting for input.
 You will not be able to pan/zoom and the figure may not even render
 (the window might appear black, transparent, or as a snapshot of the
diff --git a/doc/users/faq/troubleshooting_faq.rst b/doc/users/faq/troubleshooting_faq.rst
@@ -157,7 +157,7 @@ the tracker so the issue doesn't get lost.
 Problems with recent git versions
 =================================
 
-First make sure you have a clean build and install (see :ref:`clean-install`),
+First, make sure you have a clean build and install (see :ref:`clean-install`),
 get the latest git update, install it and run a simple test script in debug
 mode::
 
diff --git a/doc/users/next_whats_new/3d_plot_aspects.rst b/doc/users/next_whats_new/3d_plot_aspects.rst
@@ -27,6 +27,7 @@ Users can set the aspect ratio for the X, Y, Z axes of a 3D plot to be 'equal',
     for i, ax in enumerate(axs):
         ax.set_box_aspect((3, 4, 5))
         ax.set_aspect(aspects[i])
-        ax.set_title("set_aspect('{aspects[i]}')")
+        ax.set_title(f"set_aspect('{aspects[i]}')")
 
+    fig.set_size_inches(13, 3)
     plt.show()
diff --git a/doc/users/next_whats_new/3d_plot_aspects_adjustable_keyword.rst b/doc/users/next_whats_new/3d_plot_aspects_adjustable_keyword.rst
@@ -0,0 +1,34 @@
+*adjustable* keyword argument for setting equal aspect ratios in 3D
+-------------------------------------------------------------------
+
+While setting equal aspect ratios for 3D plots, users can choose to modify
+either the data limits or the bounding box.
+
+.. plot::
+    :include-source: true
+
+    import matplotlib.pyplot as plt
+    import numpy as np
+    from itertools import combinations, product
+
+    aspects = ('auto', 'equal', 'equalxy', 'equalyz', 'equalxz')
+    fig, axs = plt.subplots(1, len(aspects), subplot_kw={'projection': '3d'},
+                            figsize=(12, 6))
+
+    # Draw rectangular cuboid with side lengths [4, 3, 5]
+    r = [0, 1]
+    scale = np.array([4, 3, 5])
+    pts = combinations(np.array(list(product(r, r, r))), 2)
+    for start, end in pts:
+        if np.sum(np.abs(start - end)) == r[1] - r[0]:
+            for ax in axs:
+                ax.plot3D(*zip(start*scale, end*scale), color='C0')
+
+    # Set the aspect ratios
+    for i, ax in enumerate(axs):
+        ax.set_aspect(aspects[i], adjustable='datalim')
+        # Alternatively: ax.set_aspect(aspects[i], adjustable='box')
+        # which will change the box aspect ratio instead of axis data limits.
+        ax.set_title(f"set_aspect('{aspects[i]}')")
+
+    plt.show()
diff --git a/doc/users/next_whats_new/3d_plot_focal_length.rst b/doc/users/next_whats_new/3d_plot_focal_length.rst
@@ -19,13 +19,13 @@ The focal length can be calculated from a desired FOV via the equation:
 
     from mpl_toolkits.mplot3d import axes3d
     import matplotlib.pyplot as plt
-    fig, axs = plt.subplots(1, 3, subplot_kw={'projection': '3d'},
-                            constrained_layout=True)
+    from numpy import inf
+    fig, axs = plt.subplots(1, 3, subplot_kw={'projection': '3d'})
     X, Y, Z = axes3d.get_test_data(0.05)
-    focal_lengths = [0.25, 1, 4]
+    focal_lengths = [0.2, 1, inf]
     for ax, fl in zip(axs, focal_lengths):
         ax.plot_wireframe(X, Y, Z, rstride=10, cstride=10)
         ax.set_proj_type('persp', focal_length=fl)
         ax.set_title(f"focal_length = {fl}")
-    plt.tight_layout()
+    fig.set_size_inches(10, 4)
     plt.show()
diff --git a/doc/users/next_whats_new/3d_plot_roll_angle.rst b/doc/users/next_whats_new/3d_plot_roll_angle.rst
@@ -18,4 +18,5 @@ existing 3D plots.
     X, Y, Z = axes3d.get_test_data(0.05)
     ax.plot_wireframe(X, Y, Z, rstride=10, cstride=10)
     ax.view_init(elev=0, azim=0, roll=30)
+    ax.set_title('elev=0, azim=0, roll=30')
     plt.show()
diff --git a/doc/users/next_whats_new/font_fallback.rst b/doc/users/next_whats_new/font_fallback.rst
@@ -1,7 +1,7 @@
-Font fallback in Agg
---------------------
+Font fallback
+-------------
 
-It is now possible to specify a list of fonts families and the Agg renderer
+It is now possible to specify a list of fonts families and Matplotlib
 will try them in order to locate a required glyph.
 
 .. plot::
@@ -23,5 +23,5 @@ will try them in order to locate a required glyph.
    plt.show()
 
 
-This currently only works with the Agg backend, but support for the vector
-backends is planned for Matplotlib 3.7.
+This currently works with the Agg (and all of the GUI embeddings), svg, pdf,
+ps, and inline backends.
diff --git a/examples/animation/animation_demo.py b/examples/animation/animation_demo.py
@@ -20,9 +20,9 @@
 
 fig, ax = plt.subplots()
 
-for i in range(len(data)):
-    ax.cla()
-    ax.imshow(data[i])
-    ax.set_title("frame {}".format(i))
+for i, img in enumerate(data):
+    ax.clear()
+    ax.imshow(img)
+    ax.set_title(f"frame {i}")
     # Note that using time.sleep does *not* work here!
     plt.pause(0.1)
diff --git a/examples/event_handling/data_browser.py b/examples/event_handling/data_browser.py
@@ -75,7 +75,7 @@ def update(self):
 
         dataind = self.lastind
 
-        ax2.cla()
+        ax2.clear()
         ax2.plot(X[dataind])
 
         ax2.text(0.05, 0.9, f'mu={xs[dataind]:1.3f}\nsigma={ys[dataind]:1.3f}',
diff --git a/lib/matplotlib/cm.py b/lib/matplotlib/cm.py
@@ -701,6 +701,8 @@ def _ensure_cmap(cmap):
     """
     if isinstance(cmap, colors.Colormap):
         return cmap
-    return mpl.colormaps[
-        cmap if cmap is not None else mpl.rcParams['image.cmap']
-    ]
+    cmap_name = cmap if cmap is not None else mpl.rcParams["image.cmap"]
+    # use check_in_list to ensure type stability of the exception raised by
+    # the internal usage of this (ValueError vs KeyError)
+    _api.check_in_list(sorted(_colormaps), cmap=cmap_name)
+    return mpl.colormaps[cmap_name]
diff --git a/lib/matplotlib/dates.py b/lib/matplotlib/dates.py
@@ -525,8 +525,7 @@ def num2date(x, tz=None):
 
     Notes
     -----
-    The addition of one here is a historical artifact. Also, note that the
-    Gregorian calendar is assumed; this is not universal practice.
+    The Gregorian calendar is assumed; this is not universal practice.
     For details, see the module docstring.
     """
     tz = _get_tzinfo(tz)
@@ -866,13 +865,13 @@ class AutoDateFormatter(ticker.Formatter):
     defaults to ::
 
         self.scaled = {
-            DAYS_PER_YEAR: rcParams['date.autoformat.year'],
-            DAYS_PER_MONTH: rcParams['date.autoformat.month'],
-            1: rcParams['date.autoformat.day'],
-            1 / HOURS_PER_DAY: rcParams['date.autoformat.hour'],
-            1 / MINUTES_PER_DAY: rcParams['date.autoformat.minute'],
-            1 / SEC_PER_DAY: rcParams['date.autoformat.second'],
-            1 / MUSECONDS_PER_DAY: rcParams['date.autoformat.microsecond'],
+            DAYS_PER_YEAR: rcParams['date.autoformatter.year'],
+            DAYS_PER_MONTH: rcParams['date.autoformatter.month'],
+            1: rcParams['date.autoformatter.day'],
+            1 / HOURS_PER_DAY: rcParams['date.autoformatter.hour'],
+            1 / MINUTES_PER_DAY: rcParams['date.autoformatter.minute'],
+            1 / SEC_PER_DAY: rcParams['date.autoformatter.second'],
+            1 / MUSECONDS_PER_DAY: rcParams['date.autoformatter.microsecond'],
         }
 
     The formatter uses the format string corresponding to the lowest key in
diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py
@@ -1140,7 +1140,7 @@ def _get_legend_handles(axs, legend_handler_map=None):
         label = handle.get_label()
         if label != '_nolegend_' and has_handler(handler_map, handle):
             yield handle
-        elif (label not in ['_nolegend_', ''] and
+        elif (label and not label.startswith('_') and
                 not has_handler(handler_map, handle)):
             _api.warn_external(
                              "Legend does not support handles for {0} "
diff --git a/lib/matplotlib/tests/test_colors.py b/lib/matplotlib/tests/test_colors.py
@@ -1543,3 +1543,11 @@ def test_color_sequences():
     plt.color_sequences.unregister('rgb')  # multiple unregisters are ok
     with pytest.raises(ValueError, match="Cannot unregister builtin"):
         plt.color_sequences.unregister('tab10')
+
+
+def test_cm_set_cmap_error():
+    sm = cm.ScalarMappable()
+    # Pick a name we are pretty sure will never be a colormap name
+    bad_cmap = 'AardvarksAreAwkward'
+    with pytest.raises(ValueError, match=bad_cmap):
+        sm.set_cmap(bad_cmap)
diff --git a/lib/matplotlib/tests/test_legend.py b/lib/matplotlib/tests/test_legend.py
@@ -1,6 +1,7 @@
 import collections
 import platform
 from unittest import mock
+import warnings
 
 import numpy as np
 import pytest
@@ -515,6 +516,13 @@ def test_text_nohandler_warning():
         ax.legend()
     assert len(record) == 1
 
+    # this should _not_ warn:
+    f, ax = plt.subplots()
+    ax.pcolormesh(np.random.uniform(0, 1, (10, 10)))
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")
+        ax.get_legend_handles_labels()
+
 
 def test_empty_bar_chart_with_legend():
     """Test legend when bar chart is empty with a label."""
diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py
diff --git a/lib/mpl_toolkits/tests/baseline_images/test_mplot3d/aspects_adjust_box.png b/lib/mpl_toolkits/tests/baseline_images/test_mplot3d/aspects_adjust_box.png
diff --git a/lib/mpl_toolkits/tests/test_mplot3d.py b/lib/mpl_toolkits/tests/test_mplot3d.py
