Privatize font_manager.JSONEncoder.

anntzer · anntzer · commit 937ba83f9d72 · 2019-08-19T17:17:47.000+02:00
... with the usual deprecation dance.

End users can still use json_dump, which provides the necessary
functionality (the docstring was slightly updated at the same time); the
point is to hide the (lengthy) docs of JSONEncoder from the docs.
diff --git a/doc/api/next_api_changes/2019-08-18-AL.rst b/doc/api/next_api_changes/2019-08-18-AL.rst
@@ -0,0 +1,5 @@
+Deprecations
+````````````
+
+``font_manager.JSONEncoder`` is deprecated.  Use `.font_manager.json_dump` to
+dump a `.FontManager` instance.
diff --git a/doc/missing-references.json b/doc/missing-references.json
@@ -3504,7 +3504,7 @@
     "matplotlib.dviread.Font": [
       "<unknown>:1"
     ],
-    "json.encoder.JSONEncoder": [
+    "matplotlib.font_manager._JSONEncoder": [
       "lib/matplotlib/font_manager.py:docstring of matplotlib.font_manager.JSONEncoder:1"
     ],
     "font_manager.FontProperties": [
diff --git a/lib/matplotlib/font_manager.py b/lib/matplotlib/font_manager.py
@@ -858,7 +858,7 @@ def copy(self):
         return new
 
 
-class JSONEncoder(json.JSONEncoder):
+class _JSONEncoder(json.JSONEncoder):
     def default(self, o):
         if isinstance(o, FontManager):
             return dict(o.__dict__, __class__='FontManager')
@@ -876,6 +876,11 @@ def default(self, o):
             return super().default(o)
 
 
+@cbook.deprecated("3.2", alternative="json_dump")
+class JSONEncoder(_JSONEncoder):
+    pass
+
+
 def _json_decode(o):
     cls = o.pop('__class__', None)
     if cls is None:
@@ -896,26 +901,32 @@ def _json_decode(o):
 
 def json_dump(data, filename):
     """
-    Dumps a data structure as JSON in the named file.
+    Dump `FontManager` *data* as JSON to the file named *filename*.
+
+    Notes
+    -----
+    File paths that are children of the Matplotlib data path (typically, fonts
+    shipped with Matplotlib) are stored relative to that data path (to remain
+    valid across virtualenvs).
 
-    Handles FontManager and its fields.  File paths that are children of the
-    Matplotlib data path (typically, fonts shipped with Matplotlib) are stored
-    relative to that data path (to remain valid across virtualenvs).
+    See Also
+    --------
+    json_load
     """
     with open(filename, 'w') as fh:
         try:
-            json.dump(data, fh, cls=JSONEncoder, indent=2)
+            json.dump(data, fh, cls=_JSONEncoder, indent=2)
         except OSError as e:
             _log.warning('Could not save font_manager cache {}'.format(e))
 
 
 def json_load(filename):
     """
-    Loads a data structure as JSON from the named file.
+    Load a `FontManager` from the JSON file named *filename*.
 
-    Handles FontManager and its fields.  Relative file paths are interpreted
-    as being relative to the Matplotlib data path, and transformed into
-    absolute paths.
+    See Also
+    --------
+    json_dump
     """
     with open(filename, 'r') as fh:
         return json.load(fh, object_hook=_json_decode)
