Merge remote-tracking branch 'upstream/master' into add_doc

AkM-2018 · AkM-2018 · commit c8435e572b04 · 2021-05-07T11:14:53.000+05:30
diff --git a/doc/api/next_api_changes/behavior/20150-TAC.rst b/doc/api/next_api_changes/behavior/20150-TAC.rst
@@ -0,0 +1,10 @@
+Rename fist arg to subplot_mosaic
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Both `.FigureBase.subplot_mosaic`, and `.pyplot.subplot_mosaic` have had the
+first position argument renamed from *layout* to *mosaic*.  This is because we
+are considering to consolidate *constrained_layout* and *tight_layout* keyword
+arguments in the Figure creation functions of `.pyplot` into a single *layout*
+keyword argument which would collide.
+
+As this API is provisional, we are changing this with no deprecation period.
diff --git a/doc/contents.rst b/doc/contents.rst
@@ -18,7 +18,7 @@ Overview
    faq/index.rst
    api/index.rst
    resources/index.rst
-   thirdpartypackages/index.rst
+   Third-party packages <https://matplotlib.org/mpl-third-party/>
    devel/index.rst
 
 .. only:: html
diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
@@ -290,12 +290,12 @@ Including figures and files
 ---------------------------
 
 Image files can directly included in pages with the ``image::`` directive.
-e.g., :file:`thirdpartypackages/index.rst` displays the images for the third-party
-packages as static images::
+e.g., :file:`tutorials/intermediate/constrainedlayout_guide.py` displays 
+a couple of static images::
 
-    .. image:: /_static/toolbar.png
+  # .. image:: /_static/constrained_layout_1b.png
+  #    :align: center
 
-as rendered on the page: :ref:`thirdparty-index`.
 
 Files can be included verbatim.  For instance the ``LICENSE`` file is included
 at :ref:`license-agreement` using ::
diff --git a/doc/index.rst b/doc/index.rst
@@ -63,7 +63,7 @@ Matplotlib makes easy things easy and hard things possible.
       Extend
 
       - Explore tailored functionality provided by
-        :doc:`third party packages <thirdpartypackages/index>`
+        `third party packages <https://matplotlib.org/mpl-third-party/>`_
       - Learn more about Matplotlib through the many
         :doc:`external learning resources <resources/index>`
 
@@ -162,7 +162,8 @@ helpers in `.axisartist`.
 Third party packages
 ====================
 
-A large number of :doc:`third party packages <thirdpartypackages/index>`
+A large number of 
+`third party packages <https://matplotlib.org/mpl-third-party/>`_
 extend and build on Matplotlib functionality, including several higher-level
 plotting interfaces (seaborn_, HoloViews_, ggplot_, ...), and a projection
 and mapping toolkit (Cartopy_).
diff --git a/doc/thirdpartypackages/index.rst b/doc/thirdpartypackages/index.rst
@@ -1,4 +1,10 @@
-.. _thirdparty-index:
+:orphan:
+
+.. note:: 
+
+    This page has been moved to <https://matplotlib.org/mpl-third-party>, 
+    where you will find an up-to-date list of packages.  
+
 
 ********************
 Third party packages
diff --git a/lib/matplotlib/axis.py b/lib/matplotlib/axis.py
@@ -786,6 +786,18 @@ def get_children(self):
         return [self.label, self.offsetText,
                 *self.get_major_ticks(), *self.get_minor_ticks()]
 
+    def _reset_major_tick_kw(self):
+        self._major_tick_kw.clear()
+        self._major_tick_kw['gridOn'] = (
+                mpl.rcParams['axes.grid'] and
+                mpl.rcParams['axes.grid.which'] in ('both', 'major'))
+
+    def _reset_minor_tick_kw(self):
+        self._minor_tick_kw.clear()
+        self._minor_tick_kw['gridOn'] = (
+                mpl.rcParams['axes.grid'] and
+                mpl.rcParams['axes.grid.which'] in ('both', 'minor'))
+
     def clear(self):
         """
         Clear the axis.
@@ -807,14 +819,8 @@ def clear(self):
         # Clear the callback registry for this axis, or it may "leak"
         self.callbacks = cbook.CallbackRegistry()
 
-        # whether the grids are on
-        self._major_tick_kw['gridOn'] = (
-                mpl.rcParams['axes.grid'] and
-                mpl.rcParams['axes.grid.which'] in ('both', 'major'))
-        self._minor_tick_kw['gridOn'] = (
-                mpl.rcParams['axes.grid'] and
-                mpl.rcParams['axes.grid.which'] in ('both', 'minor'))
-
+        self._reset_major_tick_kw()
+        self._reset_minor_tick_kw()
         self.reset_ticks()
 
         self.converter = None
@@ -861,10 +867,10 @@ def set_tick_params(self, which='major', reset=False, **kw):
         # future new ticks will automatically get them
         if reset:
             if which in ['major', 'both']:
-                self._major_tick_kw.clear()
+                self._reset_major_tick_kw()
                 self._major_tick_kw.update(kwtrans)
             if which in ['minor', 'both']:
-                self._minor_tick_kw.clear()
+                self._reset_minor_tick_kw()
                 self._minor_tick_kw.update(kwtrans)
             self.reset_ticks()
         else:
@@ -1413,35 +1419,40 @@ def grid(self, b=None, which='major', **kwargs):
 
                 grid(color='r', linestyle='-', linewidth=2)
         """
-        if b is not None:
-            if 'visible' in kwargs and bool(b) != bool(kwargs['visible']):
+        TOGGLE = object()
+        UNSET = object()
+        visible = kwargs.pop('visible', UNSET)
+
+        if b is None:
+            if visible is UNSET:
+                if kwargs:  # grid(color='r')
+                    b = True
+                else:  # grid()
+                    b = TOGGLE
+            else:  # grid(visible=v)
+                b = visible
+        else:
+            if visible is not UNSET and bool(b) != bool(visible):
+                # grid(True, visible=False), grid(False, visible=True)
                 raise ValueError(
                     "'b' and 'visible' specify inconsistent grid visibilities")
             if kwargs and not b:  # something false-like but not None
+                # grid(0, visible=True)
                 _api.warn_external('First parameter to grid() is false, '
                                    'but line properties are supplied. The '
                                    'grid will be enabled.')
                 b = True
+
         which = which.lower()
         _api.check_in_list(['major', 'minor', 'both'], which=which)
         gridkw = {'grid_' + item[0]: item[1] for item in kwargs.items()}
-        if 'grid_visible' in gridkw:
-            forced_visibility = True
-            gridkw['gridOn'] = gridkw.pop('grid_visible')
-        else:
-            forced_visibility = False
-
         if which in ['minor', 'both']:
-            if b is None and not forced_visibility:
-                gridkw['gridOn'] = not self._minor_tick_kw['gridOn']
-            elif b is not None:
-                gridkw['gridOn'] = b
+            gridkw['gridOn'] = (not self._minor_tick_kw['gridOn']
+                                if b is TOGGLE else b)
             self.set_tick_params(which='minor', **gridkw)
         if which in ['major', 'both']:
-            if b is None and not forced_visibility:
-                gridkw['gridOn'] = not self._major_tick_kw['gridOn']
-            elif b is not None:
-                gridkw['gridOn'] = b
+            gridkw['gridOn'] = (not self._major_tick_kw['gridOn']
+                                if b is TOGGLE else b)
             self.set_tick_params(which='major', **gridkw)
         self.stale = True
 
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -1649,7 +1649,7 @@ def _normalize_grid_string(layout):
             layout = inspect.cleandoc(layout)
             return [list(ln) for ln in layout.strip('\n').split('\n')]
 
-    def subplot_mosaic(self, layout, *, sharex=False, sharey=False,
+    def subplot_mosaic(self, mosaic, *, sharex=False, sharey=False,
                        subplot_kw=None, gridspec_kw=None, empty_sentinel='.'):
         """
         Build a layout of Axes based on ASCII art or nested lists.
@@ -1663,7 +1663,7 @@ def subplot_mosaic(self, layout, *, sharex=False, sharey=False,
 
         Parameters
         ----------
-        layout : list of list of {hashable or nested} or str
+        mosaic : list of list of {hashable or nested} or str
 
             A visual layout of how you want your Axes to be arranged
             labeled as strings.  For example ::
@@ -1728,8 +1728,8 @@ def subplot_mosaic(self, layout, *, sharex=False, sharey=False,
         subplot_kw = subplot_kw or {}
         gridspec_kw = gridspec_kw or {}
         # special-case string input
-        if isinstance(layout, str):
-            layout = self._normalize_grid_string(layout)
+        if isinstance(mosaic, str):
+            mosaic = self._normalize_grid_string(mosaic)
         # Only accept strict bools to allow a possible future API expansion.
         _api.check_isinstance(bool, sharex=sharex, sharey=sharey)
 
@@ -1749,10 +1749,10 @@ def _make_array(inp):
             """
             r0, *rest = inp
             if isinstance(r0, str):
-                raise ValueError('List layout specification must be 2D')
+                raise ValueError('List mosaic specification must be 2D')
             for j, r in enumerate(rest, start=1):
                 if isinstance(r, str):
-                    raise ValueError('List layout specification must be 2D')
+                    raise ValueError('List mosaic specification must be 2D')
                 if len(r0) != len(r):
                     raise ValueError(
                         "All of the rows must be the same length, however "
@@ -1765,24 +1765,24 @@ def _make_array(inp):
                     out[j, k] = v
             return out
 
-        def _identify_keys_and_nested(layout):
+        def _identify_keys_and_nested(mosaic):
             """
-            Given a 2D object array, identify unique IDs and nested layouts
+            Given a 2D object array, identify unique IDs and nested mosaics
 
             Parameters
             ----------
-            layout : 2D numpy object array
+            mosaic : 2D numpy object array
 
             Returns
             -------
             unique_ids : tuple
-                The unique non-sub layout entries in this layout
+                The unique non-sub mosaic entries in this mosaic
             nested : dict[tuple[int, int]], 2D object array
             """
             # make sure we preserve the user supplied order
             unique_ids = cbook._OrderedSet()
             nested = {}
-            for j, row in enumerate(layout):
+            for j, row in enumerate(mosaic):
                 for k, v in enumerate(row):
                     if v == empty_sentinel:
                         continue
@@ -1793,102 +1793,102 @@ def _identify_keys_and_nested(layout):
 
             return tuple(unique_ids), nested
 
-        def _do_layout(gs, layout, unique_ids, nested):
+        def _do_layout(gs, mosaic, unique_ids, nested):
             """
-            Recursively do the layout.
+            Recursively do the mosaic.
 
             Parameters
             ----------
             gs : GridSpec
-            layout : 2D object array
+            mosaic : 2D object array
                 The input converted to a 2D numpy array for this level.
             unique_ids : tuple
                 The identified scalar labels at this level of nesting.
             nested : dict[tuple[int, int]], 2D object array
-                The identified nested layouts, if any.
+                The identified nested mosaics, if any.
 
             Returns
             -------
             dict[label, Axes]
                 A flat dict of all of the Axes created.
             """
-            rows, cols = layout.shape
+            rows, cols = mosaic.shape
             output = dict()
 
             # we need to merge together the Axes at this level and the axes
-            # in the (recursively) nested sub-layouts so that we can add
+            # in the (recursively) nested sub-mosaics so that we can add
             # them to the figure in the "natural" order if you were to
             # ravel in c-order all of the Axes that will be created
             #
             # This will stash the upper left index of each object (axes or
-            # nested layout) at this level
+            # nested mosaic) at this level
             this_level = dict()
 
             # go through the unique keys,
             for name in unique_ids:
                 # sort out where each axes starts/ends
-                indx = np.argwhere(layout == name)
+                indx = np.argwhere(mosaic == name)
                 start_row, start_col = np.min(indx, axis=0)
                 end_row, end_col = np.max(indx, axis=0) + 1
                 # and construct the slice object
                 slc = (slice(start_row, end_row), slice(start_col, end_col))
                 # some light error checking
-                if (layout[slc] != name).any():
+                if (mosaic[slc] != name).any():
                     raise ValueError(
-                        f"While trying to layout\n{layout!r}\n"
+                        f"While trying to layout\n{mosaic!r}\n"
                         f"we found that the label {name!r} specifies a "
                         "non-rectangular or non-contiguous area.")
                 # and stash this slice for later
                 this_level[(start_row, start_col)] = (name, slc, 'axes')
 
-            # do the same thing for the nested layouts (simpler because these
+            # do the same thing for the nested mosaics (simpler because these
             # can not be spans yet!)
-            for (j, k), nested_layout in nested.items():
-                this_level[(j, k)] = (None, nested_layout, 'nested')
+            for (j, k), nested_mosaic in nested.items():
+                this_level[(j, k)] = (None, nested_mosaic, 'nested')
 
             # now go through the things in this level and add them
             # in order left-to-right top-to-bottom
             for key in sorted(this_level):
                 name, arg, method = this_level[key]
                 # we are doing some hokey function dispatch here based
                 # on the 'method' string stashed above to sort out if this
-                # element is an axes or a nested layout.
+                # element is an axes or a nested mosaic.
                 if method == 'axes':
                     slc = arg
                     # add a single axes
                     if name in output:
                         raise ValueError(f"There are duplicate keys {name} "
-                                         f"in the layout\n{layout!r}")
+                                         f"in the layout\n{mosaic!r}")
                     ax = self.add_subplot(
                         gs[slc], **{'label': str(name), **subplot_kw}
                     )
                     output[name] = ax
                 elif method == 'nested':
-                    nested_layout = arg
+                    nested_mosaic = arg
                     j, k = key
-                    # recursively add the nested layout
-                    rows, cols = nested_layout.shape
+                    # recursively add the nested mosaic
+                    rows, cols = nested_mosaic.shape
                     nested_output = _do_layout(
                         gs[j, k].subgridspec(rows, cols, **gridspec_kw),
-                        nested_layout,
-                        *_identify_keys_and_nested(nested_layout)
+                        nested_mosaic,
+                        *_identify_keys_and_nested(nested_mosaic)
                     )
                     overlap = set(output) & set(nested_output)
                     if overlap:
                         raise ValueError(
                             f"There are duplicate keys {overlap} "
-                            f"between the outer layout\n{layout!r}\n"
-                            f"and the nested layout\n{nested_layout}"
+                            f"between the outer layout\n{mosaic!r}\n"
+                            f"and the nested layout\n{nested_mosaic}"
                         )
                     output.update(nested_output)
                 else:
                     raise RuntimeError("This should never happen")
             return output
 
-        layout = _make_array(layout)
-        rows, cols = layout.shape
+        mosaic = _make_array(mosaic)
+        rows, cols = mosaic.shape
         gs = self.add_gridspec(rows, cols, **gridspec_kw)
-        ret = _do_layout(gs, layout, *_identify_keys_and_nested(layout))
+        ret = _do_layout(gs, mosaic, *_identify_keys_and_nested(mosaic))
         ax0 = next(iter(ret.values()))
         for ax in ret.values():
             if sharex:
diff --git a/lib/matplotlib/gridspec.py b/lib/matplotlib/gridspec.py
@@ -308,12 +308,13 @@ def subplots(self, *, sharex=False, sharey=False, squeeze=True,
                     self[row, col], **subplot_kw)
 
         # turn off redundant tick labeling
-        if sharex in ["col", "all"]:
-            for ax in axarr.flat:
-                ax._label_outer_xaxis()
-        if sharey in ["row", "all"]:
-            for ax in axarr.flat:
-                ax._label_outer_yaxis()
+        if all(ax.name == "rectilinear" for ax in axarr.flat):
+            if sharex in ["col", "all"]:
+                for ax in axarr.flat:
+                    ax._label_outer_xaxis()
+            if sharey in ["row", "all"]:
+                for ax in axarr.flat:
+                    ax._label_outer_yaxis()
 
         if squeeze:
             # Discarding unneeded dimensions that equal 1.  If we only have one
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
diff --git a/lib/matplotlib/tests/test_polar.py b/lib/matplotlib/tests/test_polar.py
diff --git a/tutorials/provisional/mosaic.py b/tutorials/provisional/mosaic.py
