Fully document PIL.ImageFont

PIL/ImageFont.py

@@ -61,21 +61,6 @@ except ImportError:
 # position according to dx, dy.
 # --------------------------------------------------------------------
 
-##
-# The <b>ImageFont</b> module defines a class with the same name.
-# Instances of this class store bitmap fonts, and are used with the
-# <b>text</b> method of the <b>ImageDraw</b> class.
-# <p>
-# PIL uses it's own font file format to store bitmap fonts. You can
-# use the <b>pilfont</b> utility to convert BDF and PCF font
-# descriptors (X window font formats) to this format.
-# <p>
-# Starting with version 1.1.4, PIL can be configured to support
-# TrueType and OpenType fonts.  For earlier version, TrueType
-# support is only available as part of the imToolkit package
-#
-# @see ImageDraw#ImageDraw.text
-# @see pilfont
 
 class ImageFont:
     "PIL font wrapper"
@@ -197,41 +182,42 @@ class TransposedFont:
             return im.transpose(self.orientation)
         return im
 
-##
-# Load font file.  This function loads a font object from the given
-# bitmap font file, and returns the corresponding font object.
-#
-# @param filename Name of font file.
-# @return A font object.
-# @exception IOError If the file could not be read.
 
 def load(filename):
-    "Load a font file."
+    """
+    Load a font file.  This function loads a font object from the given
+    bitmap font file, and returns the corresponding font object.
+
+    :param filename: Name of font file.
+    :return: A font object.
+    :exception IOError: If the file could not be read.
+    """
     f = ImageFont()
     f._load_pilfont(filename)
     return f
 
-##
-# Load a TrueType or OpenType font file, and create a font object.
-# This function loads a font object from the given file, and creates
-# a font object for a font of the given size.
-# <p>
-# This function requires the _imagingft service.
-#
-# @param filename A truetype font file.  Under Windows, if the file
-#    is not found in this filename, the loader also looks in Windows
-#    <b>fonts</b> directory
-# @param size The requested size, in points.
-# @param index Which font face to load (default is first available face).
-# @param encoding Which font encoding to use (default is Unicode).  Common
-#    encodings are "unic" (Unicode), "symb" (Microsoft Symbol), "ADOB"
-#    (Adobe Standard), "ADBE" (Adobe Expert), and "armn" (Apple Roman).
-#    See the FreeType documentation for more information.
-# @return A font object.
-# @exception IOError If the file could not be read.
 
 def truetype(font=None, size=10, index=0, encoding="", filename=None):
-    "Load a truetype font file."
+    """
+    Load a TrueType or OpenType font file, and create a font object.
+    This function loads a font object from the given file, and creates
+    a font object for a font of the given size.
+
+    This function requires the _imagingft service.
+
+    :param filename: A truetype font file. Under Windows, if the file
+                     is not found in this filename, the loader also looks in
+                     Windows :file:`fonts/` directory.
+    :param size: The requested size, in points.
+    :param index: Which font face to load (default is first available face).
+    :param encoding: Which font encoding to use (default is Unicode). Common
+                     encodings are "unic" (Unicode), "symb" (Microsoft
+                     Symbol), "ADOB" (Adobe Standard), "ADBE" (Adobe Expert),
+                     and "armn" (Apple Roman). See the FreeType documentation
+                     for more information.
+    :return: A font object.
+    :exception IOError: If the file could not be read.
+    """
 
     if filename:
         if warnings:
@@ -251,17 +237,16 @@ def truetype(font=None, size=10, index=0, encoding="", filename=None):
                 return FreeTypeFont(filename, size, index, encoding)
         raise
 
-##
-# Load font file.  Same as load, but searches for a bitmap font along
-# the Python path.
-#
-# @param filename Name of font file.
-# @return A font object.
-# @exception IOError If the file could not be read.
-# @see #load
 
 def load_path(filename):
-    "Load a font file, searching along the Python path."
+    """
+    Load font file. Same as :py:func:`~PIL.ImageFont.load`, but searches for a
+    bitmap font along the Python path.
+
+    :param filename: Name of font file.
+    :return: A font object.
+    :exception IOError: If the file could not be read.
+    """
     for dir in sys.path:
         if isDirectory(dir):
             if not isinstance(filename, str):
@@ -275,13 +260,14 @@ def load_path(filename):
                 pass
     raise IOError("cannot find font file")
 
-##
-# Load a (probably rather ugly) default font.
-#
-# @return A font object.
 
 def load_default():
-    "Load a default font."
+    """Load a "better than nothing" default font.
+
+    .. versionadded:: 1.1.4
+
+    :return: A font object.
+    """
     from io import BytesIO
     import base64
     f = ImageFont()
@@ -406,6 +392,7 @@ w7IkEbzhVQAAAABJRU5ErkJggg==
 '''))))
     return f
 
+
 if __name__ == "__main__":
     # create font data chunk for embedding
     import base64, os, sys

docs/reference/ImageEnhance.rst

@@ -7,11 +7,8 @@
 The :py:mod:`ImageEnhance` module contains a number of classes that can be used
 for image enhancement.
 
-Example
+Example: Vary the sharpness of an image
--------
+---------------------------------------
-
-Vary the Sharpness of an Image
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. code-block:: python
 

docs/reference/ImageFilter.rst

@@ -5,15 +5,15 @@
 =========================
 
 The :py:mod:`ImageFilter` module contains definitions for a pre-defined set of
-filters, which can be be used with :py:meth:`Image.filter()
+filters, which can be be used with the :py:meth:`Image.filter()
-<PIL.Image.Image.filter>`.
+<PIL.Image.Image.filter>` method.
 
-Example Filter an image
+Example: Filter an image
------------------------
+------------------------
 
 .. code-block:: python
 
-    import ImageFilter
+    from PIL import ImageFilter
 
     im1 = im.filter(ImageFilter.BLUR)
 

docs/reference/ImageFont.rst

@@ -0,0 +1,69 @@
+.. py:module:: PIL.ImageFont
+.. py:currentmodule:: PIL.ImageFont
+
+:mod:`ImageFont` Module
+=======================
+
+The :py:mod:`ImageFont` module defines a class with the same name. Instances of
+this class store bitmap fonts, and are used with the
+:py:meth:`PIL.ImageDraw.Draw.text` method.
+
+PIL uses its own font file format to store bitmap fonts. You can use the
+:command`pilfont` utility to convert BDF and PCF font descriptors (X window
+font formats) to this format.
+
+Starting with version 1.1.4, PIL can be configured to support TrueType and
+OpenType fonts (as well as other font formats supported by the FreeType
+library). For earlier versions, TrueType support is only available as part of
+the imToolkit package
+
+Example
+-------
+
+.. code-block:: python
+
+    from PIL import ImageFont, ImageDraw
+
+    draw = ImageDraw.Draw(image)
+
+    # use a bitmap font
+    font = ImageFont.load("arial.pil")
+
+    draw.text((10, 10), "hello", font=font)
+
+    # use a truetype font
+    font = ImageFont.truetype("arial.ttf", 15)
+
+    draw.text((10, 25), "world", font=font)
+
+Functions
+---------
+
+.. autofunction:: PIL.ImageFont.load
+.. autofunction:: PIL.ImageFont.load_path
+.. autofunction:: PIL.ImageFont.truetype
+.. autofunction:: PIL.ImageFont.load_default
+
+Methods
+-------
+
+.. py:method:: PIL.ImageFont.ImageFont.getsize(text)
+
+    :return: (width, height)
+
+.. py:method:: PIL.ImageFont.ImageFont.getmask(text, mode='')
+
+    Create a bitmap for the text.
+
+    If the font uses antialiasing, the bitmap should have mode “L” and use a
+    maximum value of 255. Otherwise, it should have mode “1”.
+
+    :param text: Text to render.
+    :param mode: Used by some graphics drivers to indicate what mode the
+                 driver prefers; if empty, the renderer may return either
+                 mode. Note that the mode is always a string, to simplify
+                 C-level implementations.
+
+                 .. versionadded:: 1.1.5
+    :return: An internal PIL storage memory instance as defined by the
+             :py:mod:`PIL.Image.core` interface module.

docs/reference/index.rst

@@ -11,4 +11,5 @@ Reference
    ImageEnhance
    ImageFile
    ImageFilter
+   ImageFont
    ../PIL