Deprecate automatic papersize in PostScript

This automation is not very good, and just saving at the figure size is
better for EPS.

Closes matplotlib#7551

Author: QuLogic

doc/api/next_api_changes/deprecations/25784-ES.rst

@@ -0,0 +1,6 @@
+Automatic papersize selection in PostScript
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Setting :rc:`ps.papersize` to ``'auto'`` or passing ``papersize='auto'`` to
+`.Figure.savefig` is deprecated. Either pass an explicit paper type name, or
+omit this parameter to use the default from the rcParam.

lib/matplotlib/backends/backend_ps.py

@@ -867,8 +867,10 @@ def _print_figure(
         # find the appropriate papertype
         width, height = self.figure.get_size_inches()
         if papertype == 'auto':
-            papertype = _get_papertype(
-                *orientation.swap_if_landscape((width, height)))
+            _api.warn_deprecated("3.8", name="papertype='auto'",
+                                 addendum="Pass an explicit paper type, or omit the "
+                                 "*papertype* argument entirely.")
+            papertype = _get_papertype(*orientation.swap_if_landscape((width, height)))
 
         if is_eps:
             paper_width, paper_height = width, height
@@ -1059,6 +1061,9 @@ def _print_figure_tex(
                     self.figure.get_size_inches())
             else:
                 if papertype == 'auto':
+                    _api.warn_deprecated("3.8", name="papertype='auto'",
+                                         addendum="Pass an explicit paper type, or "
+                                         "omit the *papertype* argument entirely.")
                     papertype = _get_papertype(width, height)
                 paper_width, paper_height = papersize[papertype]
 

lib/matplotlib/rcsetup.py

@@ -438,6 +438,19 @@ def validate_ps_distiller(s):
         return ValidateInStrings('ps.usedistiller', ['ghostscript', 'xpdf'])(s)
 
 
+def _validate_papersize(s):
+    # Re-inline this validator when the 'auto' deprecation expires.
+    s = ValidateInStrings("ps.papersize",
+                          ["auto", "letter", "legal", "ledger",
+                           *[f"{ab}{i}" for ab in "ab" for i in range(11)]],
+                          ignorecase=True)(s)
+    if s == "auto":
+        _api.warn_deprecated("3.8", name="ps.papersize='auto'",
+                             addendum="Pass an explicit paper type, or omit the "
+                             "*ps.papersize* rcParam entirely.")
+    return s
+
+
 # A validator dedicated to the named line styles, based on the items in
 # ls_mapper, and a list of possible strings read from Line2D.set_linestyle
 _validate_named_linestyle = ValidateInStrings(
@@ -1180,9 +1193,7 @@ def _convert_validator_spec(key, conv):
     "tk.window_focus": validate_bool,  # Maintain shell focus for TkAgg
 
     # Set the papersize/type
-    "ps.papersize":       _ignorecase(["auto", "letter", "legal", "ledger",
-                                      *[f"{ab}{i}"
-                                        for ab in "ab" for i in range(11)]]),
+    "ps.papersize":       _validate_papersize,
     "ps.useafm":          validate_bool,
     # use ghostscript or xpdf to distill ps output
     "ps.usedistiller":    validate_ps_distiller,

lib/matplotlib/tests/test_backend_ps.py

@@ -336,3 +336,12 @@ def test_colorbar_shift(tmp_path):
     norm = mcolors.BoundaryNorm([-1, -0.5, 0.5, 1], cmap.N)
     plt.scatter([0, 1], [1, 1], c=[0, 1], cmap=cmap, norm=norm)
     plt.colorbar()
+
+
+def test_auto_papersize_deprecation():
+    fig = plt.figure()
+    with pytest.warns(mpl.MatplotlibDeprecationWarning):
+        fig.savefig(io.BytesIO(), format='eps', papertype='auto')
+
+    with pytest.warns(mpl.MatplotlibDeprecationWarning):
+        mpl.rcParams['ps.papersize'] = 'auto'