MNT: Cleanup FontProperties __init__ API

timhoffm · timhoffm · commit de3b37a5d709 · 2024-09-19T13:55:25.000+02:00
The cleanup approach is to not modify
code logic during a deprecation period,
but only detect deprecated call patterns
through a decorator and warn on them.
diff --git a/lib/matplotlib/font_manager.py b/lib/matplotlib/font_manager.py
@@ -29,6 +29,7 @@
 
 from base64 import b64encode
 from collections import namedtuple
+from collections.abc import Iterable
 import copy
 import dataclasses
 from functools import lru_cache
@@ -536,6 +537,56 @@ def afmFontProperty(fontpath, font):
     return FontEntry(fontpath, name, style, variant, weight, stretch, size)
 
 
+def _cleanup_fontproperties_init(init_method):
+    """
+    A decorator to limit the call signature to single a positional argument
+    or alternatively only keyword arguments.
+
+    We still accept but deprecate all other call signatures.
+
+    When the deprecation expires we can switch the signature to::
+
+        __init__(self, pattern=None, /, *, family=None, style=None, ...)
+
+    plus a runtime check that pattern is not used alongside with the
+    keyword arguments. This results eventually in the two possible
+    call signatures::
+
+        FontProperties(pattern)
+        FontProperties(family=..., size=..., ...)
+
+    """
+    @functools.wraps(init_method)
+    def warpper(*args, **kwargs):
+        # multiple args with at least some positional ones
+        if len(args) > 1 or len(args) == 1 and kwargs:
+            # Note: Both cases were previously handled as individual properties.
+            # Therefore, we do not mention the case of font properties here.
+            _api.warn_deprecated(
+                "3.10",
+                messsage="Passing individual properties to FontProperties() "
+                         "positionally is deprecated. Please pass all properties "
+                         "via keyword arguments."
+            )
+        # single non-string arg -> clearly a family not a pattern
+        if (len(args) == 1 and not kwargs
+                and isinstance(pattern, Iterable) and not isinstance(pattern, str)):
+            # Case font-family list passed as single argument
+            _api.warn_deprecated(
+                "3.10",
+                messsage="Passing family as positional argument to FontProperties() "
+                         "is deprecated. Please pass family names as keyword"
+                         "argument."
+            )
+        # Note on single string arg:
+        # This has been interpreted as pattern so far. We are already raising if a
+        # non-pattern compatible family string was given. Therefore, we do not need
+        # to warn for this case.
+        return init_method(*args, **kwargs)
+
+    return wrapper
+
+
 class FontProperties:
     """
     A class for storing and manipulating font properties.
@@ -585,9 +636,14 @@ class FontProperties:
     approach allows all text sizes to be made larger or smaller based
     on the font manager's default font size.
 
-    This class will also accept a fontconfig_ pattern_, if it is the only
-    argument provided.  This support does not depend on fontconfig; we are
-    merely borrowing its pattern syntax for use here.
+    This class accepts a single positional string as fontconfig_ pattern_,
+    or alternatively individual properties as keyword arguments::
+
+        FontProperties(pattern)
+        FontProperties(*, family=None, style=None, variant=None, ...)
+
+    This support does not depend on fontconfig; we are merely borrowing its
+    pattern syntax for use here.
 
     .. _fontconfig: https://www.freedesktop.org/wiki/Software/fontconfig/
     .. _pattern:
@@ -599,6 +655,7 @@ class FontProperties:
     fontconfig.
     """
 
+    @_cleanup_fontproperties_init
     def __init__(self, family=None, style=None, variant=None, weight=None,
                  stretch=None, size=None,
                  fname=None,  # if set, it's a hardcoded filename to use
