Merge pull request #4688 from nulano/featers-docs

Author: hugovk

docs/reference/ImageGrab.rst

@@ -9,7 +9,7 @@ or the clipboard to a PIL image memory.
 
 .. versionadded:: 1.1.3
 
-.. py:function:: PIL.ImageGrab.grab(bbox=None, include_layered_windows=False, all_screens=False, xdisplay=None)
+.. py:function:: grab(bbox=None, include_layered_windows=False, all_screens=False, xdisplay=None)
 
     Take a snapshot of the screen. The pixels inside the bounding box are
     returned as an "RGBA" on macOS, or an "RGB" image otherwise.
@@ -26,12 +26,15 @@ or the clipboard to a PIL image memory.
 
         .. versionadded:: 6.2.0
 
-    :param xdisplay: X11 Display address. Pass ``None`` to grab the default system screen. Pass ``""`` to grab the default X11 screen on Windows or macOS.
+    :param xdisplay:
+        X11 Display address. Pass ``None`` to grab the default system screen. Pass ``""`` to grab the default X11 screen on Windows or macOS.
+
+        You can check X11 support using :py:func:`PIL.features.check_feature` with ``feature="xcb"``.
 
         .. versionadded:: 7.1.0
     :return: An image
 
-.. py:function:: PIL.ImageGrab.grabclipboard()
+.. py:function:: grabclipboard()
 
     Take a snapshot of the clipboard image, if any. Only macOS and Windows are currently supported.
 

docs/reference/features.rst

@@ -0,0 +1,60 @@
+.. py:module:: PIL.features
+.. py:currentmodule:: PIL.features
+
+:py:mod:`features` Module
+==========================
+
+The :py:mod:`PIL.features` module can be used to detect which Pillow features are available on your system.
+
+.. autofunction:: PIL.features.pilinfo
+.. autofunction:: PIL.features.check
+.. autofunction:: PIL.features.get_supported
+
+Modules
+-------
+
+Support for the following modules can be checked:
+
+* ``pil``: The Pillow core module, required for all functionality.
+* ``tkinter``: Tkinter support.
+* ``freetype2``: FreeType font support via :py:func:`PIL.ImageFont.truetype`.
+* ``littlecms2``: LittleCMS 2 support via :py:mod:`PIL.ImageCms`.
+* ``webp``: WebP image support.
+
+.. autofunction:: PIL.features.check_module
+.. autofunction:: PIL.features.get_supported_modules
+
+Codecs
+------
+
+These are only checked during Pillow compilation.
+If the required library was uninstalled from the system, the ``pil`` core module may fail to load instead.
+
+Support for the following codecs can be checked:
+
+* ``jpg``: (compile time) Libjpeg support, required for JPEG based image formats.
+* ``jpg_2000``: (compile time) OpenJPEG support, required for JPEG 2000 image formats.
+* ``zlib``: (compile time) Zlib support, required for zlib compressed formats, such as PNG.
+* ``libtiff``: (compile time) LibTIFF support, required for TIFF based image formats.
+
+.. autofunction:: PIL.features.check_codec
+.. autofunction:: PIL.features.get_supported_codecs
+
+Features
+--------
+
+Some of these are only checked during Pillow compilation.
+If the required library was uninstalled from the system, the relevant module may fail to load instead.
+
+Support for the following features can be checked:
+
+* ``libjpeg_turbo``: (compile time) Whether Pillow was compiled against the libjpeg-turbo version of libjpeg.
+* ``transp_webp``: Support for transparency in WebP images.
+* ``webp_mux``: (compile time) Support for EXIF data in WebP images.
+* ``webp_anim``: (compile time) Support for animated WebP images.
+* ``raqm``: Raqm library, required for ``ImageFont.LAYOUT_RAQM`` in :py:func:`PIL.ImageFont.truetype`.
+* ``libimagequant``: (compile time) ImageQuant quantization support in :py:func:`PIL.Image.Image.quantize`.
+* ``xcb``: (compile time) Support for X11 in :py:func:`PIL.ImageGrab.grab` via the XCB library.
+
+.. autofunction:: PIL.features.check_feature
+.. autofunction:: PIL.features.get_supported_features

docs/reference/index.rst

@@ -30,6 +30,7 @@ Reference
    PSDraw
    PixelAccess
    PyAccess
+   features
    ../PIL
    plugins
    internal_design

src/PIL/Image.py

@@ -1051,10 +1051,12 @@ def quantize(self, colors=256, method=None, kmeans=0, palette=None, dither=1):
         of colors.
 
         :param colors: The desired number of colors, <= 256
-        :param method: 0 = median cut
-                       1 = maximum coverage
-                       2 = fast octree
-                       3 = libimagequant
+        :param method: ``Image.MEDIANCUT=0`` (median cut),
+                       ``Image.MAXCOVERAGE=1`` (maximum coverage),
+                       ``Image.FASTOCTREE=2`` (fast octree),
+                       ``Image.LIBIMAGEQUANT=3`` (libimagequant; check support using
+                       :py:func:`PIL.features.check_feature`
+                       with ``feature="libimagequant"``).
         :param kmeans: Integer
         :param palette: Quantize to the palette of given
                         :py:class:`PIL.Image.Image`.

src/PIL/ImageFont.py

@@ -637,6 +637,11 @@ def truetype(font=None, size=10, index=0, encoding="", layout_engine=None):
                      encoding of any text provided in subsequent operations.
     :param layout_engine: Which layout engine to use, if available:
                      `ImageFont.LAYOUT_BASIC` or `ImageFont.LAYOUT_RAQM`.
+
+                     You can check support for Raqm layout using
+                     :py:func:`PIL.features.check_feature` with ``feature="raqm"``.
+
+                     .. versionadded:: 4.2.0
     :return: A font object.
     :exception OSError: If the file could not be read.
     """

src/PIL/features.py

@@ -17,6 +17,13 @@
 
 
 def check_module(feature):
+    """
+    Checks if a module is available.
+
+    :param feature: The module to check for.
+    :returns: ``True`` if available, ``False`` otherwise.
+    :raises ValueError: If the module is not defined in this version of Pillow.
+    """
     if not (feature in modules):
         raise ValueError("Unknown module %s" % feature)
 
@@ -30,13 +37,23 @@ def check_module(feature):
 
 
 def get_supported_modules():
+    """
+    :returns: A list of all supported modules.
+    """
     return [f for f in modules if check_module(f)]
 
 
 codecs = {"jpg": "jpeg", "jpg_2000": "jpeg2k", "zlib": "zip", "libtiff": "libtiff"}
 
 
 def check_codec(feature):
+    """
+    Checks if a codec is available.
+
+    :param feature: The codec to check for.
+    :returns: ``True`` if available, ``False`` otherwise.
+    :raises ValueError: If the codec is not defined in this version of Pillow.
+    """
     if feature not in codecs:
         raise ValueError("Unknown codec %s" % feature)
 
@@ -46,6 +63,9 @@ def check_codec(feature):
 
 
 def get_supported_codecs():
+    """
+    :returns: A list of all supported codecs.
+    """
     return [f for f in codecs if check_codec(f)]
 
 
@@ -61,6 +81,13 @@ def get_supported_codecs():
 
 
 def check_feature(feature):
+    """
+    Checks if a feature is available.
+
+    :param feature: The feature to check for.
+    :returns: ``True`` if available, ``False`` if unavailable, ``None`` if unknown.
+    :raises ValueError: If the feature is not defined in this version of Pillow.
+    """
     if feature not in features:
         raise ValueError("Unknown feature %s" % feature)
 
@@ -74,10 +101,20 @@ def check_feature(feature):
 
 
 def get_supported_features():
+    """
+    :returns: A list of all supported features.
+    """
     return [f for f in features if check_feature(f)]
 
 
 def check(feature):
+    """
+    :param feature: A module, feature, or codec name.
+    :returns:
+        ``True`` if the module, feature, or codec is available,
+        ``False`` or ``None`` otherwise.
+    """
+
     if feature in modules:
         return check_module(feature)
     if feature in codecs:
@@ -89,13 +126,27 @@ def check(feature):
 
 
 def get_supported():
+    """
+    :returns: A list of all supported modules, features, and codecs.
+    """
+
     ret = get_supported_modules()
     ret.extend(get_supported_features())
     ret.extend(get_supported_codecs())
     return ret
 
 
 def pilinfo(out=None, supported_formats=True):
+    """
+    Prints information about this installation of Pillow.
+    This function can be called with ``python -m PIL``.
+
+    :param out:
+        The output stream to print to. Defaults to ``sys.stdout`` if ``None``.
+    :param supported_formats:
+        If ``True``, a list of all supported image file formats will be printed.
+    """
+
     if out is None:
         out = sys.stdout