Deprecate setting text kerning factor to any non-0 value

QuLogic · QuLogic · commit 0483a3d2d7e1 · 2025-07-16T20:43:18.000-04:00
This factor existed only to preserve test images, but as of matplotlib#29816, it is set to 0 (i.e., disabled and providing default behaviour). In the future, with libraqm, it will have no effect no matter its setting (because we won't be applying kerning ourselves at all.)
diff --git a/doc/api/next_api_changes/deprecations/30322-ES.rst b/doc/api/next_api_changes/deprecations/30322-ES.rst
@@ -0,0 +1,7 @@
+Font kerning factor is deprecated
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Due to internal changes to support complex text rendering, the kerning factor on fonts is
+no longer used. Setting the ``text.kerning_factor`` rcParam (which existed only for
+backwards-compatibility) to any value other than 0 is deprecated, and the rcParam will be
+removed in the future.
diff --git a/src/ft2font_wrapper.cpp b/src/ft2font_wrapper.cpp
@@ -432,12 +432,6 @@ const char *PyFT2Font_init__doc__ = R"""(
         .. warning::
             This API is both private and provisional: do not use it directly.
 
-    _kerning_factor : int, optional
-        Used to adjust the degree of kerning.
-
-        .. warning::
-            This API is private: do not use it directly.
-
     _warn_if_used : bool, optional
         Used to trigger missing glyph warnings.
 
@@ -453,6 +447,11 @@ PyFT2Font_init(py::object filename, long hinting_factor = 8,
     if (hinting_factor <= 0) {
         throw py::value_error("hinting_factor must be greater than 0");
     }
+    if (kerning_factor != 0) {
+        auto api = py::module_::import("matplotlib._api");
+        auto warn = api.attr("warn_deprecated");
+        warn("since"_a="3.11", "name"_a="_kerning_factor", "obj_type"_a="parameter");
+    }
 
     PyFT2Font *self = new PyFT2Font();
     self->x = nullptr;
