Merge pull request #15082 from anntzer/jsonencoder

dstansby · web-flow · commit c634e63ce65b · 2019-08-23T10:34:25.000+01:00
Privatize font_manager.JSONEncoder.
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
@@ -3365,7 +3365,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
@@ -859,7 +859,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')
@@ -877,6 +877,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:
@@ -897,26 +902,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)
