From ea07ac2647bd6e1d6d651b609c3d87f3b72fc0d0 Mon Sep 17 00:00:00 2001
From: Antony Lee <anntzer.lee@gmail.com>
Date: Tue, 7 Sep 2021 23:47:57 +0200
Subject: [PATCH] Prepare for rcParams.copy() returning a new RcParams instance
 in the future.

This would then allow
`rcParams.update(<previously-copied-rcParams-instance>)` to *not* emit
a deprecation warning (by checking the type of the input) even if the
copied RcParams instance contains a deprecated rc entry, because we'll
know that it will already have gone through the validator when being set
on the copied rcParams instance.
---
 doc/api/next_api_changes/deprecations/YYYYY-AL.rst | 6 ++++++
 lib/matplotlib/__init__.py                         | 8 +++++++-
 lib/matplotlib/pyplot.py                           | 3 ++-
 lib/matplotlib/tests/test_style.py                 | 2 +-
 4 files changed, 16 insertions(+), 3 deletions(-)
 create mode 100644 doc/api/next_api_changes/deprecations/YYYYY-AL.rst

diff --git a/doc/api/next_api_changes/deprecations/YYYYY-AL.rst b/doc/api/next_api_changes/deprecations/YYYYY-AL.rst
new file mode 100644
index 000000000000..64453205d252
--- /dev/null
+++ b/doc/api/next_api_changes/deprecations/YYYYY-AL.rst
@@ -0,0 +1,6 @@
+rcParams.copy() will return a new RcParams instance in the future
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+During the transition period, ``rcParams.copy()`` will emit a
+DeprecationWarning.  Either use ``dict.copy(rcParams)`` to copy rcParams as
+a plain dict, or ``copy.copy(rcParams)`` to copy rcParams as a new RcParams
+instance.
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
index ac84e82c30f6..238447adf6e0 100644
--- a/lib/matplotlib/__init__.py
+++ b/lib/matplotlib/__init__.py
@@ -708,6 +708,11 @@ def find_all(self, pattern):
                         if pattern_re.search(key))
 
     def copy(self):
+        _api.warn_deprecated(
+            "3.6", message="In the future, rcParams.copy() will return a new "
+            "RcParams instance.  During the deprecation period, either use "
+            "dict.copy(rcParams) to copy rcParams as a plain dict, or "
+            "copy.copy(rcParams) to copy rcParams as a new RcParams instance.")
         return {k: dict.__getitem__(self, k) for k in self}
 
 
@@ -1076,7 +1081,8 @@ def rc_context(rc=None, fname=None):
              plt.plot(x, y)  # uses 'print.rc'
 
     """
-    orig = rcParams.copy()
+    with _api.suppress_matplotlib_deprecation_warning():
+        orig = rcParams.copy()
     try:
         if fname:
             rc_file(fname)
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
index b222466dda45..2c1341e50bb4 100644
--- a/lib/matplotlib/pyplot.py
+++ b/lib/matplotlib/pyplot.py
@@ -613,7 +613,8 @@ class _xkcd:
     # work as a non-contextmanager too.
 
     def __init__(self, scale, length, randomness):
-        self._orig = rcParams.copy()
+        with _api.suppress_matplotlib_deprecation_warning():
+            self._orig = rcParams.copy()
 
         if rcParams['text.usetex']:
             raise RuntimeError(
diff --git a/lib/matplotlib/tests/test_style.py b/lib/matplotlib/tests/test_style.py
index 5ed115abb68f..264581b525dd 100644
--- a/lib/matplotlib/tests/test_style.py
+++ b/lib/matplotlib/tests/test_style.py
@@ -154,7 +154,7 @@ def test_alias(equiv_styles):
     rc_dicts = []
     for sty in equiv_styles:
         with style.context(sty):
-            rc_dicts.append(mpl.rcParams.copy())
+            rc_dicts.append(dict.copy(mpl.rcParams))
 
     rc_base = rc_dicts[0]
     for nm, rc in zip(equiv_styles[1:], rc_dicts[1:]):