FIX: set_font() should not do full font reset for str arguments

Closes matplotlib#27608

A str is interpreted as a fontconfig pattern and should only update
the specified parts.

This is solution 2 from matplotlib#27608 (comment)

This is a breaking change, but there is no smooth transition path. I'd label this a bug fix and by that justify the immediate change.

Co-authored-by: Ruth Comer <10599679+rcomer@users.noreply.github.com>

Author: timhoffm

doc/api/next_api_changes/behavior/text_set_font_partial_update.rst

@@ -0,0 +1,39 @@
+``Text.set_font`` now performs a partial update for string arguments
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+`.Text.set_font` (and its alias ``font=`` in keyword-argument form) previously
+behaved identically to `.Text.set_fontproperties`: passing a string caused
+**all** font properties to be replaced, resetting size, weight, style, etc. to
+their defaults.  This was surprising given that all other ``set_font*`` methods
+(`~.Text.set_fontfamily`, `~.Text.set_fontsize`, `~.Text.set_fontweight`, ...)
+update only the property they describe.
+
+Starting with this release ``set_font`` performs a *partial* update when given
+a string:
+
+* The string is interpreted as a fontconfig pattern (same syntax as before).
+* Only the properties explicitly named in the pattern are changed.
+* All other font properties (size, weight, style, ...) are preserved.
+
+.. code-block:: python
+
+    import matplotlib.pyplot as plt
+
+    fig, ax = plt.subplots()
+    t = ax.text(0.5, 0.5, "Hello")
+
+    t.set_fontsize(20)
+    t.set_fontweight("bold")
+
+    # Old behaviour: size and weight would be reset to defaults.
+    # New behaviour: only the family is updated; size=20 and bold weight remain.
+    t.set_font("DejaVu Serif")
+
+    # A rich fontconfig pattern updates exactly those properties:
+    t.set_font("DejaVu Serif:italic:size=14")
+
+For a complete replacement of all font properties (the previous behaviour)
+use `.Text.set_fontproperties` ::
+
+    t.set_fontproperties("DejaVu Serif")   # resets all other properties

lib/matplotlib/tests/test_text.py

@@ -776,6 +776,86 @@ def test_fontproperties_kwarg_precedence():
     assert text2.get_size() == 40.0
 
 
+def test_set_font_str_is_partial_update():
+    """set_font(str) must update only the family, preserving size/weight/style."""
+    fig, ax = plt.subplots()
+    t = ax.text(0.5, 0.5, 'hello')
+    t.set_fontsize(20)
+    t.set_fontweight('bold')
+    t.set_fontstyle('italic')
+
+    t.set_font('DejaVu Serif')
+
+    assert t.get_fontfamily() == ['DejaVu Serif']
+    assert t.get_fontsize() == 20, "set_font(str) must not reset the font size"
+    assert t.get_fontweight() == 'bold', "set_font(str) must not reset the font weight"
+    assert t.get_fontstyle() == 'italic', "set_font(str) must not reset the font style"
+
+
+def test_set_font_fontconfig_pattern_is_partial_update():
+    """set_font(fontconfig_pattern) updates only the properties named in the pattern."""
+    fig, ax = plt.subplots()
+    t = ax.text(0.5, 0.5, 'hello')
+    t.set_fontsize(20)
+    t.set_fontweight('bold')
+
+    # Pattern specifies family and size but NOT weight.
+    t.set_font('DejaVu Serif:size=14')
+
+    assert t.get_fontfamily() == ['DejaVu Serif']
+    assert t.get_fontsize() == 14, "set_font(pattern) must update size from pattern"
+    assert t.get_fontweight() == 'bold', (
+        "set_font(pattern) must not reset properties absent from the pattern"
+    )
+
+
+def test_set_fontproperties_str_resets_all():
+    """set_fontproperties(str) must replace ALL font properties (reset to defaults)."""
+    fig, ax = plt.subplots()
+    t = ax.text(0.5, 0.5, 'hello')
+    t.set_fontsize(20)
+    t.set_fontweight('bold')
+
+    default_size = FontProperties().get_size_in_points()
+    default_weight = FontProperties().get_weight()
+
+    t.set_fontproperties('DejaVu Serif')
+
+    assert t.get_fontfamily() == ['DejaVu Serif']
+    assert t.get_fontsize() == default_size, (
+        "set_fontproperties(str) must reset size to the FontProperties default"
+    )
+    assert t.get_fontweight() == default_weight, (
+        "set_fontproperties(str) must reset weight to the FontProperties default"
+    )
+
+
+def test_set_font_with_fontproperties_object_replaces_all():
+    """set_font(FontProperties()) falls through to set_fontproperties (full replace)."""
+    fig, ax = plt.subplots()
+    t = ax.text(0.5, 0.5, 'hello')
+    t.set_fontsize(20)
+    t.set_fontweight('bold')
+
+    fp = FontProperties(family='DejaVu Serif', size=12)
+    t.set_font(fp)
+
+    assert t.get_fontfamily() == ['DejaVu Serif']
+    assert t.get_fontsize() == 12
+    # weight was not set in fp → reset to its default
+    assert t.get_fontweight() == FontProperties().get_weight()
+
+
+def test_set_font_via_kwarg():
+    """The ``font`` keyword argument must reach set_font (partial-update path)."""
+    fig, ax = plt.subplots()
+    t = ax.text(0.5, 0.5, 'hello', fontsize=20, font='DejaVu Serif:bold')
+
+    assert t.get_fontfamily() == ['DejaVu Serif']
+    assert t.get_fontweight() == 'bold'
+    assert t.get_fontsize() == 20, "font= kwarg must not reset size"
+
+
 def test_transform_rotates_text():
     ax = plt.gca()
     transform = mtransforms.Affine2D().rotate_deg(30)

lib/matplotlib/text.py

@@ -134,7 +134,7 @@ def _text_metrics(text, fontprop, ismath, dpi):
 @_docstring.interpd
 @_api.define_aliases({
     "color": ["c"],
-    "fontproperties": ["font", "font_properties"],
+    "fontproperties": ["font_properties"],
     "fontfamily": ["family"],
     "fontname": ["name"],
     "fontsize": ["size"],
@@ -1479,6 +1479,9 @@ def set_fontproperties(self, fp):
         """
         Set the font properties that control the text.
 
+        Unlike `set_font`, this method *replaces* all font properties,
+        resetting any unspecified attributes to their defaults.
+
         Parameters
         ----------
         fp : `.font_manager.FontProperties` or `str` or `pathlib.Path`
@@ -1489,6 +1492,42 @@ def set_fontproperties(self, fp):
         self._fontproperties = FontProperties._from_any(fp).copy()
         self.stale = True
 
+    def set_font(self, fp):
+        """
+        Set the font.
+
+        .. versionchanged:: 3.12
+
+            If font is a str, this now only updates aspects of the font that are
+            specified in the pattern. Previously this was equivalent to
+            `.set_fontproperties`, which resets all non-specified aspectes to
+            their default.
+
+            If you want to have the full reset, please use `.set_fontproperties`
+            instead.
+
+        Parameters
+        ----------
+        fp : `.font_manager.FontProperties` or `str` or `pathlib.Path` or dict
+
+            - If a `str`, it is parsed as a fontconfig pattern (see
+              `.FontProperties.set_fontconfig_pattern`).  Only the properties
+              explicitly stated in the pattern are changed; everything else is
+              preserved.
+            - If a `.FontProperties`, `pathlib.Path`, or `dict`, all font
+              properties are replaced (same as `set_fontproperties`).
+
+        See Also
+        --------
+        set_fontproperties : Replace *all* font properties at once.
+        set_fontfamily : Change only the font family.
+        """
+        if isinstance(fp, str):
+            self._fontproperties.set_fontconfig_pattern(fp)
+            self.stale = True
+        else:
+            self.set_fontproperties(fp)
+
     @_docstring.kwarg_doc("bool, default: :rc:`text.usetex`")
     def set_usetex(self, usetex):
         """

lib/matplotlib/text.pyi

@@ -102,6 +102,7 @@ class Text(Artist):
     ) -> None: ...
     def set_text(self, s: Any) -> None: ...
     def set_fontproperties(self, fp: FontProperties | str | Path | None) -> None: ...
+    def set_font(self, fp: FontProperties | str | Path | None) -> None: ...
     def set_usetex(self, usetex: bool | None) -> None: ...
     def get_usetex(self) -> bool: ...
     def set_parse_math(self, parse_math: bool) -> None: ...