From 937ba83f9d728520227f02e207f03964ae28d272 Mon Sep 17 00:00:00 2001 From: Antony Lee Date: Mon, 19 Aug 2019 15:25:41 +0200 Subject: [PATCH] Privatize font_manager.JSONEncoder. ... 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. --- doc/api/next_api_changes/2019-08-18-AL.rst | 5 ++++ doc/missing-references.json | 2 +- lib/matplotlib/font_manager.py | 31 +++++++++++++++------- 3 files changed, 27 insertions(+), 11 deletions(-) create mode 100644 doc/api/next_api_changes/2019-08-18-AL.rst diff --git a/doc/api/next_api_changes/2019-08-18-AL.rst b/doc/api/next_api_changes/2019-08-18-AL.rst new file mode 100644 index 000000000000..5d3dd7934919 --- /dev/null +++ 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 index cb5bcb6fd822..6439445a3708 100644 --- a/doc/missing-references.json +++ b/doc/missing-references.json @@ -3504,7 +3504,7 @@ "matplotlib.dviread.Font": [ ":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 index a01c4a7d3ec7..40abd42d69bf 100644 --- 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)