Merge pull request #6220 from nulano/deprecate-fill

Deprecate FreeTypeFont.getmask2 fill parameter

Tests/test_imagefont.py

@@ -977,6 +977,14 @@ class TestImageFont:
 
         assert_image_similar_tofile(im, "Tests/images/colr_bungee_mask.png", 22)
 
+    def test_fill_deprecation(self):
+        font = self.get_font()
+        with pytest.warns(DeprecationWarning):
+            font.getmask2("Hello world", fill=Image.core.fill)
+        with pytest.warns(DeprecationWarning):
+            with pytest.raises(TypeError):
+                font.getmask2("Hello world", fill=None)
+
 
 @skip_unless_feature("raqm")
 class TestImageFont_RaqmLayout(TestImageFont):

docs/deprecations.rst

@@ -149,6 +149,14 @@ PhotoImage.paste box parameter
 
 The ``box`` parameter is unused. It will be removed in Pillow 10.0.0 (2023-07-01).
 
+FreeTypeFont.getmask2 fill parameter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. deprecated:: 9.2.0
+
+The undocumented ``fill`` parameter of :py:meth:`.FreeTypeFont.getmask2` has been
+deprecated and will be removed in Pillow 10 (2023-07-01).
+
 Removed features
 ----------------
 

docs/releasenotes/9.2.0.rst

@@ -0,0 +1,49 @@
+9.2.0
+-----
+
+Backwards Incompatible Changes
+==============================
+
+TODO
+^^^^
+
+Deprecations
+============
+
+FreeTypeFont.getmask2 fill parameter
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The undocumented ``fill`` parameter of :py:meth:`.FreeTypeFont.getmask2`
+has been deprecated and will be removed in Pillow 10 (2023-07-01).
+
+API Changes
+===========
+
+TODO
+^^^^
+
+TODO
+
+API Additions
+=============
+
+TODO
+^^^^
+
+TODO
+
+Security
+========
+
+TODO
+^^^^
+
+TODO
+
+Other Changes
+=============
+
+TODO
+^^^^
+
+TODO

docs/releasenotes/index.rst

@@ -14,6 +14,7 @@ expected to be backported to earlier versions.
 .. toctree::
   :maxdepth: 2
 
+  9.2.0
   9.1.0
   9.0.1
   9.0.0

src/PIL/ImageFont.py

@@ -64,6 +64,9 @@ except ImportError:
     core = _ImagingFtNotInstalled()
 
 
+_UNSPECIFIED = object()
+
+
 # FIXME: add support for pilfont2 format (see FontFile.py)
 
 # --------------------------------------------------------------------
@@ -602,7 +605,7 @@ class FreeTypeFont:
         self,
         text,
         mode="",
-        fill=Image.core.fill,
+        fill=_UNSPECIFIED,
         direction=None,
         features=None,
         language=None,
@@ -627,6 +630,12 @@ class FreeTypeFont:
 
                      .. versionadded:: 1.1.5
 
+        :param fill: Optional fill function. By default, an internal Pillow function
+                     will be used.
+
+                     Deprecated. This parameter will be removed in Pillow 10
+                     (2023-07-01).
+
         :param direction: Direction of the text. It can be 'rtl' (right to
                           left), 'ltr' (left to right) or 'ttb' (top to bottom).
                           Requires libraqm.
@@ -674,6 +683,10 @@ class FreeTypeFont:
                  :py:mod:`PIL.Image.core` interface module, and the text offset, the
                  gap between the starting coordinate and the first marking
         """
+        if fill is _UNSPECIFIED:
+            fill = Image.core.fill
+        else:
+            deprecate("fill", 10)
         size, offset = self.font.getsize(
             text, mode, direction, features, language, anchor
         )