Deprecate functions in backends

oscargus · oscargus · commit 6902f58cf103 · 2022-04-07T16:50:21.000+02:00
diff --git a/doc/api/next_api_changes/deprecations/22797-OG.rst b/doc/api/next_api_changes/deprecations/22797-OG.rst
@@ -0,0 +1,12 @@
+Deprecation of helper functions in backends
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following functions are considered private and deprecated.
+Vendor the code of the similarly named private functions.
+
+* ``backend_pdf.fill``
+* ``backend_ps.quote_ps_string``
+* ``backend_svg.escape_attrib``
+* ``backend_svg.escape_cdata``
+* ``backend_svg.escape_comment``
+* ``backend_svg.short_float_fmt``
diff --git a/lib/matplotlib/backends/backend_pdf.py b/lib/matplotlib/backends/backend_pdf.py
@@ -93,7 +93,12 @@
 # * draw_quad_mesh
 
 
+@_api.deprecated("3.6", alternative="Vendor the code")
 def fill(strings, linelen=75):
+    return _fill(strings, linelen=linelen)
+
+
+def _fill(strings, linelen=75):
     """
     Make one string from sequence of strings, with whitespace in between.
 
diff --git a/lib/matplotlib/backends/backend_ps.py b/lib/matplotlib/backends/backend_ps.py
@@ -89,7 +89,12 @@ def _nums_to_str(*args):
     return " ".join(f"{arg:1.3f}".rstrip("0").rstrip(".") for arg in args)
 
 
+@_api.deprecated("3.6", "Vendor the code")
 def quote_ps_string(s):
+    return _quote_ps_string(s)
+
+
+def _quote_ps_string(s):
     """
     Quote dangerous characters of S for use in a PostScript string constant.
     """
@@ -738,7 +743,7 @@ def draw_gouraud_triangles(self, gc, points, colors, trans):
         streamarr['flags'] = 0
         streamarr['points'] = (flat_points - points_min) * factor
         streamarr['colors'] = flat_colors[:, :3] * 255.0
-        stream = quote_ps_string(streamarr.tobytes())
+        stream = _quote_ps_string(streamarr.tobytes())
 
         self._pswriter.write(f"""\
 gsave
diff --git a/lib/matplotlib/backends/backend_svg.py b/lib/matplotlib/backends/backend_svg.py
@@ -66,7 +66,12 @@
 # --------------------------------------------------------------------
 
 
+@_api.deprecated("3.6", alternative="Vendor the code")
 def escape_cdata(s):
+    return _escape_cdata(s)
+
+
+def _escape_cdata(s):
     s = s.replace("&", "&amp;")
     s = s.replace("<", "&lt;")
     s = s.replace(">", "&gt;")
@@ -76,12 +81,22 @@ def escape_cdata(s):
 _escape_xml_comment = re.compile(r'-(?=-)')
 
 
+@_api.deprecated("3.6", alternative="Vendor the code")
 def escape_comment(s):
-    s = escape_cdata(s)
+    return _escape_comment.sub(s)
+
+
+def _escape_comment(s):
+    s = _escape_cdata(s)
     return _escape_xml_comment.sub('- ', s)
 
 
+@_api.deprecated("3.6", alternative="Vendor the code")
 def escape_attrib(s):
+    return _escape_attrib(s)
+
+
+def _escape_attrib(s):
     s = s.replace("&", "&amp;")
     s = s.replace("'", "&apos;")
     s = s.replace('"', "&quot;")
@@ -91,12 +106,17 @@ def escape_attrib(s):
 
 
 def _quote_escape_attrib(s):
-    return ('"' + escape_cdata(s) + '"' if '"' not in s else
-            "'" + escape_cdata(s) + "'" if "'" not in s else
-            '"' + escape_attrib(s) + '"')
+    return ('"' + _escape_cdata(s) + '"' if '"' not in s else
+            "'" + _escape_cdata(s) + "'" if "'" not in s else
+            '"' + _escape_attrib(s) + '"')
 
 
+@_api.deprecated("3.6", alternative="Vendor the code")
 def short_float_fmt(x):
+    return _short_float_fmt(x)
+
+
+def _short_float_fmt(x):
     """
     Create a short string representation of a float, which is %f
     formatting with trailing zeros and the decimal point removed.
@@ -130,7 +150,7 @@ def __flush(self, indent=True):
             self.__open = 0
         if self.__data:
             data = ''.join(self.__data)
-            self.__write(escape_cdata(data))
+            self.__write(_escape_cdata(data))
             self.__data = []
 
     def start(self, tag, attrib={}, **extra):
@@ -153,14 +173,14 @@ def start(self, tag, attrib={}, **extra):
         An element identifier.
         """
         self.__flush()
-        tag = escape_cdata(tag)
+        tag = _escape_cdata(tag)
         self.__data = []
         self.__tags.append(tag)
         self.__write(self.__indentation[:len(self.__tags) - 1])
         self.__write("<%s" % tag)
         for k, v in {**attrib, **extra}.items():
             if v:
-                k = escape_cdata(k)
+                k = _escape_cdata(k)
                 v = _quote_escape_attrib(v)
                 self.__write(' %s=%s' % (k, v))
         self.__open = 1
@@ -177,7 +197,7 @@ def comment(self, comment):
         """
         self.__flush()
         self.__write(self.__indentation[:len(self.__tags)])
-        self.__write("<!-- %s -->\n" % escape_comment(comment))
+        self.__write("<!-- %s -->\n" % _escape_comment(comment))
 
     def data(self, text):
         """
@@ -203,7 +223,7 @@ def end(self, tag=None, indent=True):
         """
         if tag:
             assert self.__tags, "unbalanced end(%s)" % tag
-            assert escape_cdata(tag) == self.__tags[-1], \
+            assert _escape_cdata(tag) == self.__tags[-1], \
                 "expected end(%s), got %s" % (self.__tags[-1], tag)
         else:
             assert self.__tags, "unbalanced end()"
