From 572e4eb95d56ffb7725b1416d04952f1d9a926fb Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Tue, 10 Dec 2019 01:39:56 +0100
Subject: [PATCH] Deprecate passing Type1Font effects as dict

---
 doc/api/next_api_changes/deprecations.rst |  5 ++
 lib/matplotlib/type1font.py               | 62 ++++++++++++++++-------
 2 files changed, 50 insertions(+), 17 deletions(-)

diff --git a/doc/api/next_api_changes/deprecations.rst b/doc/api/next_api_changes/deprecations.rst
index 70e1b8522b6f..355abac69cdc 100644
--- a/doc/api/next_api_changes/deprecations.rst
+++ b/doc/api/next_api_changes/deprecations.rst
@@ -59,3 +59,8 @@ Passing raw data via parameters *data* and *lut* to `.register_cmap()` is
 deprecated. Instead, explicitly create a `.LinearSegmentedColormap` and pass
 it via the *cmap* parameter:
 ``register_cmap(cmap=LinearSegmentedColormap(name, data, lut))``.
+
+``Type1Font.transform`` effect parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Passing effect parameters to `.Type1Font.transform` as dict is deprecated.
+Use the respective keyword arguments instead.
diff --git a/lib/matplotlib/type1font.py b/lib/matplotlib/type1font.py
index 01caf460d15b..70ea9281b521 100644
--- a/lib/matplotlib/type1font.py
+++ b/lib/matplotlib/type1font.py
@@ -10,8 +10,8 @@
 
    >>> font = Type1Font(filename)
    >>> clear_part, encrypted_part, finale = font.parts
-   >>> slanted_font = font.transform({'slant': 0.167})
-   >>> extended_font = font.transform({'extend': 1.2})
+   >>> slanted_font = font.transform(slant=0.167)
+   >>> extended_font = font.transform(extend=1.2)
 
 Sources:
 
@@ -30,6 +30,8 @@
 
 import numpy as np
 
+from matplotlib import cbook
+
 
 # token types
 _TokenType = enum.Enum('_TokenType',
@@ -54,8 +56,13 @@ class Type1Font:
 
     def __init__(self, input):
         """
-        Initialize a Type-1 font. *input* can be either the file name of
-        a pfb file or a 3-tuple of already-decoded Type-1 font parts.
+        Initialize a Type-1 font.
+
+        Parameters
+        ----------
+        input : str or 3-tuple
+            Either a pfb file name, or a 3-tuple of already-decoded Type-1
+            font `~Type1Font.parts`.
         """
         if isinstance(input, tuple) and len(input) == 3:
             self.parts = input
@@ -67,9 +74,7 @@ def __init__(self, input):
         self._parse()
 
     def _read(self, file):
-        """
-        Read the font from a file, decoding into usable parts.
-        """
+        """Read the font from a file, decoding into usable parts."""
         rawdata = file.read()
         if not rawdata.startswith(b'\x80'):
             return rawdata
@@ -304,17 +309,40 @@ def suppress(tokens):
             else:
                 yield value
 
-    def transform(self, effects):
+    def transform(self, effects=None, *, slant=0, extend=1):
         """
-        Transform the font by slanting or extending. *effects* should
-        be a dict where ``effects['slant']`` is the tangent of the
-        angle that the font is to be slanted to the right (so negative
-        values slant to the left) and ``effects['extend']`` is the
-        multiplier by which the font is to be extended (so values less
-        than 1.0 condense). Returns a new :class:`Type1Font` object.
+        Return a new font that is slanted or extended.
+
+        Parameters
+        ----------
+        effects : dict
+            *Deprecated*. Use the keyword arguments *slanted* and *extended*
+            instead.
+
+            A dict with optional keys 'slant' and 'extend'. The effect is the
+            same as for the respective keyword arguments. If given, the
+            keyword arguments take precedence over the dict values.
+        slant : float, default: 0
+            Tangent of the angle that the font is to be slanted to the right.
+            Negative values slant to the left.
+        extend : float, default: 1
+            Scaling factor for the font width. Values less than 1 condense the
+            glyphs.
+
+        Returns
+        -------
+        font : `Type1Font`
         """
+        if effects is not None:
+            cbook.warn_deprecated(
+                "3.3",
+                message="The passing effects as a dict is deprecated. Use "
+                        "keyword arguments slant and extend instead.")
+        if slant == 0 and effects is not None:
+            slant = effects.get('slant', slant)
+        if extend == 1 and effects is not None:
+            extend = effects.get('extend', slant)
+
         tokenizer = self._tokens(self.parts[0])
-        transformed = self._transformer(tokenizer,
-                                        slant=effects.get('slant', 0.0),
-                                        extend=effects.get('extend', 1.0))
+        transformed = self._transformer(tokenizer, slant=slant, extend=extend)
         return Type1Font((b"".join(transformed), self.parts[1], self.parts[2]))