Deprecate "U" mode passed to cbook.to_filehandle().

It has had no effect ever since transition to Py3, and the corresponding
feature in open() is being removed in cpython 3.9.

Author: anntzer

doc/api/next_api_changes/deprecations.rst

@@ -35,3 +35,9 @@ with locator classes defined in :mod:`matplotlib.ticker`.
 ``backend_pgf.LatexManager.latex`` is now created with ``encoding="utf-8"``, so
 its ``stdin`` attribute is already utf8-encoded; the ``latex_stdin_utf8``
 attribute is thus deprecated.
+
+Flags containing "U" passed to `.cbook.to_filehandle` and `.cbook.open_file_cm`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Please remove "U" from flags passed to `.cbook.to_filehandle` and
+`.cbook.open_file_cm`.  This is consistent with their removal from `open` in
+Python 3.9.

lib/matplotlib/cbook/__init__.py

@@ -427,17 +427,18 @@ def to_filehandle(fname, flag='r', return_opened=False, encoding=None):
     """
     if isinstance(fname, os.PathLike):
         fname = os.fspath(fname)
+    if "U" in flag:
+        warn_deprecated("3.3", message="Passing a flag containing 'U' to "
+                        "to_filehandle() is deprecated since %(since)s and "
+                        "will be removed %(removal)s.")
+        flag = flag.replace("U", "")
     if isinstance(fname, str):
         if fname.endswith('.gz'):
-            # get rid of 'U' in flag for gzipped files.
-            flag = flag.replace('U', '')
             fh = gzip.open(fname, flag)
         elif fname.endswith('.bz2'):
             # python may not be complied with bz2 support,
             # bury import until we need it
             import bz2
-            # get rid of 'U' in flag for bz2 files
-            flag = flag.replace('U', '')
             fh = bz2.BZ2File(fname, flag)
         else:
             fh = open(fname, flag, encoding=encoding)