Make sharex, etc. args of subplots() keyword-only.

anntzer · anntzer · commit 3d4400b242fa · 2020-05-05T19:48:01.000+02:00
Currently subplots() has a specific codepath to check whether one typed
`subplots(1, 1, 1)` and warn in that case because the user likely meant
`subplot(1, 1, 1)` (no "s") but will instead get
`subplots(1, 1, sharex=1)`.  Making *sharex* keyword-only will remove
this trap; moreover `subplots(1, 1, sharex=True)` is anyways much more
legible than `subplots(1, 1, True)`.

If this makes it to 3.3 then GridSpec.subplots() won't need a
deprecation period as that API is new.
diff --git a/doc/api/api_changes_3.3/deprecations.rst b/doc/api/api_changes_3.3/deprecations.rst
@@ -438,6 +438,11 @@ The qt4agg and qt4cairo backends are deprecated.
 *fontdict* and *minor* parameters of `.Axes.set_xticklabels` and `.Axes.set_yticklabels` will become keyword-only
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+All parameters of `.Figure.subplots` except *nrows* and *ncols* will become keyword-only
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This avoids typing e.g. ``subplots(1, 1, 1)`` when meaning ``subplot(1, 1, 1)``,
+but actually getting ``subplots(1, 1, sharex=1)``.
+
 ``RendererWx.get_gc``
 ~~~~~~~~~~~~~~~~~~~~~
 This method is deprecated.  Access the ``gc`` attribute directly instead.
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -1430,6 +1430,7 @@ def _add_axes_internal(self, key, ax):
         ax.stale_callback = _stale_figure_callback
         return ax
 
+    @cbook._make_keyword_only("3.3", "sharex")
     def subplots(self, nrows=1, ncols=1, sharex=False, sharey=False,
                  squeeze=True, subplot_kw=None, gridspec_kw=None):
         """
diff --git a/lib/matplotlib/gridspec.py b/lib/matplotlib/gridspec.py
@@ -235,7 +235,7 @@ def _normalize(key, size, axis):  # Includes last index.
 
         return SubplotSpec(self, num1, num2)
 
-    def subplots(self, sharex=False, sharey=False, squeeze=True,
+    def subplots(self, *, sharex=False, sharey=False, squeeze=True,
                  subplot_kw=None):
         """
         Add all subplots specified by this `GridSpec` to its parent figure.
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -1084,6 +1084,7 @@ def subplot(*args, **kwargs):
     return ax
 
 
+@cbook._make_keyword_only("3.3", "sharex")
 def subplots(nrows=1, ncols=1, sharex=False, sharey=False, squeeze=True,
              subplot_kw=None, gridspec_kw=None, **fig_kw):
     """
