Added documentation

python-pillow · Oct 14, 2023 · c2d5088 · c2d5088
1 parent 0da7ad7
commit c2d5088
Show file tree

Hide file tree

Showing 3 changed files with 66 additions and 14 deletions.
diff --git a/docs/reference/ImageDraw.rst b/docs/reference/ImageDraw.rst
@@ -351,7 +351,7 @@ Methods
 
     Draw a shape.
 
-.. py:method:: ImageDraw.text(xy, text, fill=None, font=None, anchor=None, spacing=4, align="left", direction=None, features=None, language=None, stroke_width=0, stroke_fill=None, embedded_color=False)
+.. py:method:: ImageDraw.text(xy, text, fill=None, font=None, anchor=None, spacing=4, align="left", direction=None, features=None, language=None, stroke_width=0, stroke_fill=None, embedded_color=False, font_size=None)
 
     Draws the string at the given position.
 
@@ -416,8 +416,14 @@ Methods
 
                     .. versionadded:: 8.0.0
 
+    :param font_size: If ``font`` is not provided, then the size to use for the default
+                      font.
+                      Keyword-only argument.
 
-.. py:method:: ImageDraw.multiline_text(xy, text, fill=None, font=None, anchor=None, spacing=4, align="left", direction=None, features=None, language=None, stroke_width=0, stroke_fill=None, embedded_color=False)
+                    .. versionadded:: 10.1.0
+
+
+.. py:method:: ImageDraw.multiline_text(xy, text, fill=None, font=None, anchor=None, spacing=4, align="left", direction=None, features=None, language=None, stroke_width=0, stroke_fill=None, embedded_color=False, font_size=None)
 
     Draws the string at the given position.
 
@@ -477,7 +483,13 @@ Methods
 
                      .. versionadded:: 8.0.0
 
-.. py:method:: ImageDraw.textlength(text, font=None, direction=None, features=None, language=None, embedded_color=False)
+    :param font_size: If ``font`` is not provided, then the size to use for the default
+                      font.
+                      Keyword-only argument.
+
+                    .. versionadded:: 10.1.0
+
+.. py:method:: ImageDraw.textlength(text, font=None, direction=None, features=None, language=None, embedded_color=False, font_size=None)
 
     Returns length (in pixels with 1/64 precision) of given text when rendered
     in font with provided direction, features, and language.
@@ -538,9 +550,15 @@ Methods
                      It should be a `BCP 47 language code`_.
                      Requires libraqm.
     :param embedded_color: Whether to use font embedded color glyphs (COLR, CBDT, SBIX).
+    :param font_size: If ``font`` is not provided, then the size to use for the default
+                      font.
+                      Keyword-only argument.
+
+                    .. versionadded:: 10.1.0
+
     :return: Either width for horizontal text, or height for vertical text.
 
-.. py:method:: ImageDraw.textbbox(xy, text, font=None, anchor=None, spacing=4, align="left", direction=None, features=None, language=None, stroke_width=0, embedded_color=False)
+.. py:method:: ImageDraw.textbbox(xy, text, font=None, anchor=None, spacing=4, align="left", direction=None, features=None, language=None, stroke_width=0, embedded_color=False, font_size=None)
 
     Returns bounding box (in pixels) of given text relative to given anchor
     when rendered in font with provided direction, features, and language.
@@ -588,9 +606,15 @@ Methods
                      Requires libraqm.
     :param stroke_width: The width of the text stroke.
     :param embedded_color: Whether to use font embedded color glyphs (COLR, CBDT, SBIX).
+    :param font_size: If ``font`` is not provided, then the size to use for the default
+                      font.
+                      Keyword-only argument.
+
+                    .. versionadded:: 10.1.0
+
     :return: ``(left, top, right, bottom)`` bounding box
 
-.. py:method:: ImageDraw.multiline_textbbox(xy, text, font=None, anchor=None, spacing=4, align="left", direction=None, features=None, language=None, stroke_width=0, embedded_color=False)
+.. py:method:: ImageDraw.multiline_textbbox(xy, text, font=None, anchor=None, spacing=4, align="left", direction=None, features=None, language=None, stroke_width=0, embedded_color=False, font_size=None)
 
     Returns bounding box (in pixels) of given text relative to given anchor
     when rendered in font with provided direction, features, and language.
@@ -632,6 +656,12 @@ Methods
                      Requires libraqm.
     :param stroke_width: The width of the text stroke.
     :param embedded_color: Whether to use font embedded color glyphs (COLR, CBDT, SBIX).
+    :param font_size: If ``font`` is not provided, then the size to use for the default
+                      font.
+                      Keyword-only argument.
+
+                    .. versionadded:: 10.1.0
+
     :return: ``(left, top, right, bottom)`` bounding box
 
 .. py:method:: getdraw(im=None, hints=None)

diff --git a/docs/releasenotes/10.1.0.rst b/docs/releasenotes/10.1.0.rst
@@ -41,15 +41,6 @@ to be specified, rather than a single number for both dimensions. ::
 API Additions
 =============
 
-ImageOps.cover
-^^^^^^^^^^^^^^
-
-Returns a resized version of the image, so that the requested size is covered,
-while maintaining the original aspect ratio.
-
-See :ref:`relative-resize` for a comparison between this and similar ``ImageOps``
-methods.
-
 EpsImagePlugin.gs_binary
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -69,6 +60,33 @@ channel, a palette with an alpha channel, or a "transparency" key in the
 Even if this attribute is true, the image might still appear solid, if all of
 the values shown within are opaque.
 
+ImageOps.cover
+^^^^^^^^^^^^^^
+
+Returns a resized version of the image, so that the requested size is covered,
+while maintaining the original aspect ratio.
+
+See :ref:`relative-resize` for a comparison between this and similar ``ImageOps``
+methods.
+
+size and font_size arguments when using default font
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Pillow has had a "better than nothing" default font, which can only be drawn at
+one font size. Now, if FreeType support is available, a version of
+`Aileron Regular <https://dotcolon.net/font/aileron>`_ is loaded, which can be
+drawn at chosen font sizes.
+
+The following ``size`` and ``font_size`` arguments can now be used to specify a
+font size for this new builtin font::
+
+    ImageFont.load_default(size=24)
+    draw.text((0, 0), "test", font_size=24)
+    draw.textlength((0, 0), "test", font_size=24)
+    draw.textbbox((0, 0), "test", font_size=24)
+    draw.multiline_text((0, 0), "test", font_size=24)
+    draw.multiline_textbbox((0, 0), "test", font_size=24)
+
 Other Changes
 =============
 

diff --git a/src/PIL/ImageFont.py b/src/PIL/ImageFont.py
@@ -869,6 +869,10 @@ def load_default(size=None):
 
     .. versionadded:: 1.1.4
 
+    :param size: The font size of Aileron Regular.
+
+        .. versionadded:: 10.1.0
+
     :return: A font object.
     """
     if core.__class__.__name__ == "module" or size is not None: