restore and document previous getsize behaviour

see discussion in issue 4789

Tests/test_imagefont.py

@@ -37,18 +37,21 @@ class TestImageFont:
         (">=2.3", "<2.4"): {
             "multiline": 30,
             "textsize": 12,
+            "getters": (13, 16),
             "multiline-anchor": 6,
             "getlength": (36, 27, 27, 33),
         },
         (">=2.7",): {
             "multiline": 6.2,
             "textsize": 2.5,
+            "getters": (12, 16),
             "multiline-anchor": 4,
             "getlength": (36, 21, 24, 33),
         },
         "Default": {
             "multiline": 0.5,
             "textsize": 0.5,
+            "getters": (12, 16),
             "multiline-anchor": 4,
             "getlength": (36, 24, 24, 33),
         },
@@ -624,7 +627,7 @@ class TestImageFont:
         assert t.font.glyphs == 4177
         assert t.getsize("A") == (12, 16)
         assert t.getsize("AB") == (24, 16)
-        assert t.getsize("M") == (12, 16)
+        assert t.getsize("M") == self.metrics["getters"]
         assert t.getsize("y") == (12, 20)
         assert t.getsize("a") == (12, 16)
         assert t.getsize_multiline("A") == (12, 16)

docs/reference/ImageDraw.rst

@@ -386,6 +386,15 @@ Methods
 
     Return the size of the given string, in pixels.
 
+    You can use :meth:`.FreeTypeFont.getlength` to measure text length
+    with 1/64 pixel precision.
+
+    .. note:: For historical reasons this function measures text height from
+        the ascender line instead of the top, see :ref:`text-anchors`.
+        If you wish to measure text height from the top, it is recommended
+        to use :meth:`.FreeTypeFont.getbbox` with `anchor='lt'` instead.
+
+
     :param text: Text to be measured. If it contains any newline characters,
                  the text is passed on to :py:meth:`~PIL.ImageDraw.ImageDraw.multiline_textsize`.
     :param font: An :py:class:`~PIL.ImageFont.ImageFont` instance.

src/PIL/ImageFont.py

@@ -217,8 +217,8 @@ class FreeTypeFont:
 
     def getlength(self, text, mode="", direction=None, features=None, language=None):
         """
-        Returns length (in pixels) of given text if rendered in font with
+        Returns length (in pixels with 1/64 precision) of given text if rendered
-        provided direction, features, and language.
+        in font with provided direction, features, and language.
 
         This is the amount by which following text should be offset.
         Text bounding box may extend past the length in some fonts,
@@ -275,8 +275,9 @@ class FreeTypeFont:
         Returns bounding box (in pixels) of given text relative to given anchor
         if rendered in font with provided direction, features, and language.
 
-        Use :py:func`getlength()` to get the offset of following text. The bounding
+        Use :py:meth`getlength()` to get the offset of following text with
-        box includes extra margins for some fonts, e.g. italics or accents.
+        1/64 pixel precision. The bounding box includes extra margins for
+        some fonts, e.g. italics or accents.
 
         :param text: Text to render.
         :param mode: Used by some graphics drivers to indicate what mode the
@@ -329,8 +330,14 @@ class FreeTypeFont:
         Returns width and height (in pixels) of given text if rendered in font with
         provided direction, features, and language.
 
-        Use :py:func:`getlength()` to measure the offset of following text.
+        Use :py:meth:`getlength()` to measure the offset of following text with
-        Use :py:func:`getbbox()` to get the exact bounding box based on an anchor.
+        1/64 pixel precision.
+        Use :py:meth:`getbbox()` to get the exact bounding box based on an anchor.
+
+        .. note:: For historical reasons this function measures text height from
+            the ascender line instead of the top, see :ref:`text-anchors`.
+            If you wish to measure text height from the top, it is recommended
+            to use :meth:`getbbox` with `anchor='lt'` instead.
 
         :param text: Text to measure.
 
@@ -369,9 +376,10 @@ class FreeTypeFont:
 
         :return: (width, height)
         """
+        # vertical offset is added for historical reasons, see discussion in #4789
         size, offset = self.font.getsize(text, False, direction, features, language)
         return (
-            size[0] + stroke_width * 2 + offset[0],
+            size[0] + stroke_width * 2,
             size[1] + stroke_width * 2 + offset[1],
         )