From 097104278b762277ff6f05df50556139a12d20c1 Mon Sep 17 00:00:00 2001 From: nulano Date: Sat, 13 Jun 2020 04:01:38 +0200 Subject: [PATCH 1/2] add docs for features module --- docs/reference/ImageGrab.rst | 9 ++++-- docs/reference/features.rst | 59 ++++++++++++++++++++++++++++++++++++ docs/reference/index.rst | 1 + src/PIL/Image.py | 10 +++--- src/PIL/ImageFont.py | 5 +++ src/PIL/features.py | 50 ++++++++++++++++++++++++++++++ 6 files changed, 127 insertions(+), 7 deletions(-) create mode 100644 docs/reference/features.rst diff --git a/docs/reference/ImageGrab.rst b/docs/reference/ImageGrab.rst index ff4646a5f..943fdf69b 100644 --- a/docs/reference/ImageGrab.rst +++ b/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. diff --git a/docs/reference/features.rst b/docs/reference/features.rst new file mode 100644 index 000000000..3a10d6201 --- /dev/null +++ b/docs/reference/features.rst @@ -0,0 +1,59 @@ +.. 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``: LittleCMS2 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``: 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 diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 8c09e7b67..91cde0400 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -30,6 +30,7 @@ Reference PSDraw PixelAccess PyAccess + features ../PIL plugins internal_design diff --git a/src/PIL/Image.py b/src/PIL/Image.py index 930252023..9d94bce0e 100644 --- a/src/PIL/Image.py +++ b/src/PIL/Image.py @@ -1051,10 +1051,12 @@ class Image: 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`. diff --git a/src/PIL/ImageFont.py b/src/PIL/ImageFont.py index 25ceaa16a..79c161713 100644 --- a/src/PIL/ImageFont.py +++ b/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. """ diff --git a/src/PIL/features.py b/src/PIL/features.py index ac06c0f71..74952545a 100644 --- a/src/PIL/features.py +++ b/src/PIL/features.py @@ -17,6 +17,13 @@ modules = { 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,6 +37,9 @@ 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)] @@ -37,6 +47,13 @@ codecs = {"jpg": "jpeg", "jpg_2000": "jpeg2k", "zlib": "zip", "libtiff": "libtif 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 @@ features = { 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,19 @@ 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,6 +125,10 @@ 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()) @@ -96,6 +136,16 @@ def get_supported(): 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 From d05a08a298657d65233fdafbdca3403fe9fe3311 Mon Sep 17 00:00:00 2001 From: nulano Date: Sun, 14 Jun 2020 00:45:29 +0200 Subject: [PATCH 2/2] formatting improvements Co-authored-by: Hugo --- docs/reference/features.rst | 13 +++++++------ src/PIL/features.py | 13 +++++++------ 2 files changed, 14 insertions(+), 12 deletions(-) diff --git a/docs/reference/features.rst b/docs/reference/features.rst index 3a10d6201..196f938ed 100644 --- a/docs/reference/features.rst +++ b/docs/reference/features.rst @@ -1,3 +1,4 @@ +.. py:module:: PIL.features .. py:currentmodule:: PIL.features :py:mod:`features` Module @@ -17,7 +18,7 @@ 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``: LittleCMS2 support via :py:mod:`PIL.ImageCms`. +* ``littlecms2``: LittleCMS 2 support via :py:mod:`PIL.ImageCms`. * ``webp``: WebP image support. .. autofunction:: PIL.features.check_module @@ -31,10 +32,10 @@ If the required library was uninstalled from the system, the ``pil`` core module 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. +* ``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 @@ -47,7 +48,7 @@ If the required library was uninstalled from the system, the relevant module may Support for the following features can be checked: -* ``libjpeg_turbo``: Whether Pillow was compiled against the libjpeg-turbo version of libjpeg. +* ``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. diff --git a/src/PIL/features.py b/src/PIL/features.py index 74952545a..33e89cf24 100644 --- a/src/PIL/features.py +++ b/src/PIL/features.py @@ -21,7 +21,7 @@ def check_module(feature): Checks if a module is available. :param feature: The module to check for. - :returns: True if available, False otherwise. + :returns: ``True`` if available, ``False`` otherwise. :raises ValueError: If the module is not defined in this version of Pillow. """ if not (feature in modules): @@ -51,7 +51,7 @@ def check_codec(feature): Checks if a codec is available. :param feature: The codec to check for. - :returns: True if available, False otherwise. + :returns: ``True`` if available, ``False`` otherwise. :raises ValueError: If the codec is not defined in this version of Pillow. """ if feature not in codecs: @@ -85,7 +85,7 @@ 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. + :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: @@ -111,7 +111,8 @@ 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. + ``True`` if the module, feature, or codec is available, + ``False`` or ``None`` otherwise. """ if feature in modules: @@ -141,9 +142,9 @@ def pilinfo(out=None, supported_formats=True): This function can be called with ``python -m PIL``. :param out: - The output stream to print to. Defaults to ``sys.stdout`` if None. + 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 ``True``, a list of all supported image file formats will be printed. """ if out is None: