From 0083ebb3d49c580cb606ebec8a9e37062ef147d2 Mon Sep 17 00:00:00 2001 From: nulano Date: Thu, 9 Jul 2020 19:48:04 +0200 Subject: [PATCH 1/8] fix various reference typos --- docs/handbook/image-file-formats.rst | 2 +- docs/handbook/tutorial.rst | 4 ++-- docs/handbook/writing-your-own-file-decoder.rst | 2 +- docs/reference/ImageFont.rst | 2 +- src/PIL/Image.py | 10 +++++----- src/PIL/ImageChops.py | 4 ++-- 6 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/handbook/image-file-formats.rst b/docs/handbook/image-file-formats.rst index 3daa75c96..d7fa89b2d 100644 --- a/docs/handbook/image-file-formats.rst +++ b/docs/handbook/image-file-formats.rst @@ -473,7 +473,7 @@ image formats, EXIF data is not guaranteed to be present in :py:attr:`~PIL.Image.Image.info` until :py:meth:`~PIL.Image.Image.load` has been called. -The :py:meth:`~PIL.Image.Image.open` method sets the following +The :py:func:`~PIL.Image.open` function sets the following :py:attr:`~PIL.Image.Image.info` properties, when appropriate: **chromaticity** diff --git a/docs/handbook/tutorial.rst b/docs/handbook/tutorial.rst index 76c0fa83f..b24a6eb4b 100644 --- a/docs/handbook/tutorial.rst +++ b/docs/handbook/tutorial.rst @@ -453,8 +453,8 @@ If everything goes well, the result is an :py:class:`PIL.Image.Image` object. Otherwise, an :exc:`OSError` exception is raised. You can use a file-like object instead of the filename. The object must -implement :py:meth:`~file.read`, :py:meth:`~file.seek` and -:py:meth:`~file.tell` methods, and be opened in binary mode. +implement ``file.read``, ``file.seek`` and ``file.tell`` methods, +and be opened in binary mode. Reading from an open file ^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/handbook/writing-your-own-file-decoder.rst b/docs/handbook/writing-your-own-file-decoder.rst index 2a546b0c6..c73ad9cab 100644 --- a/docs/handbook/writing-your-own-file-decoder.rst +++ b/docs/handbook/writing-your-own-file-decoder.rst @@ -175,7 +175,7 @@ The fields are used as follows: The **raw mode** field is used to determine how the data should be unpacked to match PIL’s internal pixel layout. PIL supports a large set of raw modes; for a -complete list, see the table in the :py:mod:`Unpack.c` module. The following +complete list, see the table in the :file:`Unpack.c` module. The following table describes some commonly used **raw modes**: +-----------+-----------------------------------------------------------------+ diff --git a/docs/reference/ImageFont.rst b/docs/reference/ImageFont.rst index b3c3cce57..fc61cac13 100644 --- a/docs/reference/ImageFont.rst +++ b/docs/reference/ImageFont.rst @@ -6,7 +6,7 @@ The :py:mod:`~PIL.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. +:py:meth:`PIL.ImageDraw.ImageDraw.text` method. PIL uses its own font file format to store bitmap fonts. You can use the :command:`pilfont` utility from diff --git a/src/PIL/Image.py b/src/PIL/Image.py index c1419744a..7c1fb0cb8 100644 --- a/src/PIL/Image.py +++ b/src/PIL/Image.py @@ -717,7 +717,7 @@ class Image: :param encoder_name: What encoder to use. The default is to use the standard "raw" encoder. :param args: Extra arguments to the encoder. - :rtype: A bytes object. + :returns: A :py:class:`bytes` object. """ # may pass tuple instead of argument list @@ -2352,10 +2352,10 @@ class Image: object:: class Example(Image.ImageTransformHandler): - def transform(size, method, data, resample, fill=1): + def transform(self, size, data, resample, fill=1): # Return result - It may also be an object with a :py:meth:`~method.getdata` method + It may also be an object with a ``method.getdata`` method that returns a tuple supplying new **method** and **data** values:: class Example: @@ -2847,8 +2847,8 @@ def open(fp, mode="r"): :py:func:`~PIL.Image.new`. See :ref:`file-handling`. :param fp: A filename (string), pathlib.Path object or a file object. - The file object must implement :py:meth:`~file.read`, - :py:meth:`~file.seek`, and :py:meth:`~file.tell` methods, + The file object must implement ``file.read``, + ``file.seek`, and ``file.tell`` methods, and be opened in binary mode. :param mode: The mode. If given, this argument must be "r". :returns: An :py:class:`~PIL.Image.Image` object. diff --git a/src/PIL/ImageChops.py b/src/PIL/ImageChops.py index c1a2574e4..9fccedcb2 100644 --- a/src/PIL/ImageChops.py +++ b/src/PIL/ImageChops.py @@ -293,7 +293,7 @@ def logical_xor(image1, image2): def blend(image1, image2, alpha): """Blend images using constant transparency weight. Alias for - :py:meth:`PIL.Image.Image.blend`. + :py:func:`PIL.Image.blend`. :rtype: :py:class:`~PIL.Image.Image` """ @@ -303,7 +303,7 @@ def blend(image1, image2, alpha): def composite(image1, image2, mask): """Create composite using transparency mask. Alias for - :py:meth:`PIL.Image.Image.composite`. + :py:func:`PIL.Image.composite`. :rtype: :py:class:`~PIL.Image.Image` """ From 73c5dffb5aad8fc4ffbacecf9902920ba31ca031 Mon Sep 17 00:00:00 2001 From: nulano Date: Thu, 9 Jul 2020 19:48:42 +0200 Subject: [PATCH 2/8] fix ImageTransformHandler and ImagePointHandler references --- docs/reference/Image.rst | 10 ++++++++-- src/PIL/Image.py | 19 +++++++++++++++++-- 2 files changed, 25 insertions(+), 4 deletions(-) diff --git a/docs/reference/Image.rst b/docs/reference/Image.rst index 347c57688..b3f4b2b8e 100644 --- a/docs/reference/Image.rst +++ b/docs/reference/Image.rst @@ -268,8 +268,8 @@ This flips the input image by using the :data:`FLIP_LEFT_RIGHT` method. .. automethod:: PIL.Image.Image.load .. automethod:: PIL.Image.Image.close -Attributes ----------- +Image Attributes +---------------- Instances of the :py:class:`Image` class have the following attributes: @@ -330,6 +330,12 @@ Instances of the :py:class:`Image` class have the following attributes: Unless noted elsewhere, this dictionary does not affect saving files. +Classes +------- + +.. autoclass:: PIL.Image.ImagePointHandler +.. autoclass:: PIL.Image.ImageTransformHandler + Constants --------- diff --git a/src/PIL/Image.py b/src/PIL/Image.py index 7c1fb0cb8..0d35d861d 100644 --- a/src/PIL/Image.py +++ b/src/PIL/Image.py @@ -1577,6 +1577,13 @@ class Image: single argument. The function is called once for each possible pixel value, and the resulting table is applied to all bands of the image. + + It may also be an :py:class:`~PIL.Image.ImagePointHandler` + object:: + + class Example(Image.ImagePointHandler): + def point(self, data): + # Return result :param mode: Output mode (default is same as input). In the current version, this can only be used if the source image has mode "L" or "P", and the output has mode "1" or the @@ -2534,12 +2541,20 @@ class Image: class ImagePointHandler: - # used as a mixin by point transforms (for use with im.point) + """ + Used as a mixin by point transforms + (for use with :py:meth:`~PIL.Image.Image.point`) + """ + pass class ImageTransformHandler: - # used as a mixin by geometry transforms (for use with im.transform) + """ + Used as a mixin by geometry transforms + (for use with :py:meth:`~PIL.Image.Image.transform`) + """ + pass From ec2b549a4da70d4af511108d3699d4e00606bcf9 Mon Sep 17 00:00:00 2001 From: nulano Date: Thu, 9 Jul 2020 19:48:58 +0200 Subject: [PATCH 3/8] fix _imaging and Image.core references --- docs/porting.rst | 3 ++- docs/reference/internal_modules.rst | 9 +++++++++ 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/porting.rst b/docs/porting.rst index d962e9330..2943d72fd 100644 --- a/docs/porting.rst +++ b/docs/porting.rst @@ -19,7 +19,8 @@ to this:: from PIL import Image -The :py:mod:`~PIL._imaging` module has been moved. You can now import it like this:: +The :py:mod:`PIL._imaging` module has been moved to :py:mod:`PIL.Image.core`. +You can now import it like this:: from PIL.Image import core as _imaging diff --git a/docs/reference/internal_modules.rst b/docs/reference/internal_modules.rst index 288a049ee..1105ff76e 100644 --- a/docs/reference/internal_modules.rst +++ b/docs/reference/internal_modules.rst @@ -36,3 +36,12 @@ Internal Modules This is the master version number for Pillow, all other uses reference this module. + +:mod:`PIL.Image.core` Module +---------------------------- + +.. module:: PIL._imaging +.. module:: PIL.Image.core + +An internal interface module previously known as :mod:`~PIL._imaging`, +implemented in :file:`_imaging.c`. From f6b4c3f7410fe740e708a5a627aed400a465389a Mon Sep 17 00:00:00 2001 From: nulano Date: Thu, 9 Jul 2020 20:19:34 +0200 Subject: [PATCH 4/8] don't link to removed methods --- docs/releasenotes/4.1.0.rst | 6 +++--- docs/releasenotes/4.2.0.rst | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/releasenotes/4.1.0.rst b/docs/releasenotes/4.1.0.rst index dc5d73479..4d6598d8e 100644 --- a/docs/releasenotes/4.1.0.rst +++ b/docs/releasenotes/4.1.0.rst @@ -10,9 +10,9 @@ Several deprecated items have been removed. resolution', 'resolution unit', and 'date time' has been removed. Underscores should be used instead. -* The methods :py:meth:`PIL.ImageDraw.ImageDraw.setink`, - :py:meth:`PIL.ImageDraw.ImageDraw.setfill`, and - :py:meth:`PIL.ImageDraw.ImageDraw.setfont` have been removed. +* The methods ``PIL.ImageDraw.ImageDraw.setink``, + ``PIL.ImageDraw.ImageDraw.setfill``, and + ``PIL.ImageDraw.ImageDraw.setfont`` have been removed. Closing Files When Opening Images diff --git a/docs/releasenotes/4.2.0.rst b/docs/releasenotes/4.2.0.rst index 906eeab8d..aee93bef6 100644 --- a/docs/releasenotes/4.2.0.rst +++ b/docs/releasenotes/4.2.0.rst @@ -34,9 +34,9 @@ Removed Deprecated Items Several deprecated items have been removed. -* The methods :py:meth:`PIL.ImageWin.Dib.fromstring`, - :py:meth:`PIL.ImageWin.Dib.tostring` and - :py:meth:`PIL.TiffImagePlugin.ImageFileDirectory_v2.as_dict` have +* The methods ``PIL.ImageWin.Dib.fromstring``, + ``PIL.ImageWin.Dib.tostring`` and + ``PIL.TiffImagePlugin.ImageFileDirectory_v2.as_dict`` have been removed. * Before Pillow 4.2.0, attempting to save an RGBA image as JPEG would From 885ca9bb03f23b3bb11ed880148d758dd557c36c Mon Sep 17 00:00:00 2001 From: nulano Date: Thu, 9 Jul 2020 20:23:19 +0200 Subject: [PATCH 5/8] add omitted ImageFilter types --- docs/reference/ImageFilter.rst | 26 ++++++++++++++++++++++++++ docs/releasenotes/4.3.0.rst | 2 +- 2 files changed, 27 insertions(+), 1 deletion(-) diff --git a/docs/reference/ImageFilter.rst b/docs/reference/ImageFilter.rst index 1b93c53e7..fc879883a 100644 --- a/docs/reference/ImageFilter.rst +++ b/docs/reference/ImageFilter.rst @@ -66,3 +66,29 @@ image enhancement filters: .. autoclass:: PIL.ImageFilter.ModeFilter :members: + +.. class:: Filter + + An abstract mixin used for filtering images + (for use with :py:meth:`~PIL.Image.Image.filter`) + + Implementors must provide the following method: + + .. method:: filter(self, image) + + Applies a filter to a single-band image, or a single band of an image. + + :returns: A filtered copy of the image. + +.. class:: MultibandFilter + + An abstract mixin used for filtering multi-band images + (for use with :py:meth:`~PIL.Image.Image.filter`) + + Implementors must provide the following method: + + .. method:: filter(self, image) + + Applies a filter to a multi-band image. + + :returns: A filtered copy of the image. diff --git a/docs/releasenotes/4.3.0.rst b/docs/releasenotes/4.3.0.rst index 6fa554e23..ea81fc45e 100644 --- a/docs/releasenotes/4.3.0.rst +++ b/docs/releasenotes/4.3.0.rst @@ -124,7 +124,7 @@ This release contains several performance improvements: * ``Image.transpose`` has been accelerated 15% or more by using a cache friendly algorithm. * ImageFilters based on Kernel convolution are significantly faster - due to the new MultibandFilter feature. + due to the new :py:class:`~PIL.ImageFilter.MultibandFilter` feature. * All memory allocation for images is now done in blocks, rather than falling back to an allocation for each scan line for images larger than the block size. From 39b5d7b4acfa5c64fe597787bd2507f06c96089a Mon Sep 17 00:00:00 2001 From: nulano Date: Fri, 10 Jul 2020 00:47:30 +0200 Subject: [PATCH 6/8] fix TiffTags and Exif related references --- docs/handbook/image-file-formats.rst | 6 +++--- docs/reference/Image.rst | 4 ++++ docs/reference/TiffTags.rst | 5 +++++ 3 files changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/handbook/image-file-formats.rst b/docs/handbook/image-file-formats.rst index d7fa89b2d..8955b3ede 100644 --- a/docs/handbook/image-file-formats.rst +++ b/docs/handbook/image-file-formats.rst @@ -774,7 +774,7 @@ The :py:meth:`~PIL.Image.open` method sets the following The :py:attr:`~PIL.Image.Image.tag_v2` attribute contains a dictionary of TIFF metadata. The keys are numerical indexes from -:py:attr:`~PIL.TiffTags.TAGS_V2`. Values are strings or numbers for single +:py:data:`.TiffTags.TAGS_V2`. Values are strings or numbers for single items, multiple values are returned in a tuple of values. Rational numbers are returned as a :py:class:`~PIL.TiffImagePlugin.IFDRational` object. @@ -827,7 +827,7 @@ The :py:meth:`~PIL.Image.Image.save` method can take the following keyword argum object and setting the type in :py:attr:`~PIL.TiffImagePlugin.ImageFileDirectory_v2.tagtype` with the appropriate numerical value from - ``TiffTags.TYPES``. + :py:data:`.TiffTags.TYPES`. .. versionadded:: 2.3.0 @@ -844,7 +844,7 @@ The :py:meth:`~PIL.Image.Image.save` method can take the following keyword argum Previous versions only supported some tags when writing using libtiff. The supported list is found in - :py:attr:`~PIL:TiffTags.LIBTIFF_CORE`. + :py:data:`.TiffTags.LIBTIFF_CORE`. .. versionadded:: 6.1.0 diff --git a/docs/reference/Image.rst b/docs/reference/Image.rst index b3f4b2b8e..2a23cc76d 100644 --- a/docs/reference/Image.rst +++ b/docs/reference/Image.rst @@ -333,6 +333,10 @@ Instances of the :py:class:`Image` class have the following attributes: Classes ------- +.. autoclass:: PIL.Image.Exif + :members: + :undoc-members: + :show-inheritance: .. autoclass:: PIL.Image.ImagePointHandler .. autoclass:: PIL.Image.ImageTransformHandler diff --git a/docs/reference/TiffTags.rst b/docs/reference/TiffTags.rst index a53788a9f..231051632 100644 --- a/docs/reference/TiffTags.rst +++ b/docs/reference/TiffTags.rst @@ -60,3 +60,8 @@ metadata tag numbers, names, and type information. The ``TYPES`` dictionary maps the TIFF type short integer to a human readable type name. + +.. py:data:: PIL.TiffTags.LIBTIFF_CORE + :type: list + + A list of supported tag ids when writing using libtiff. From 7a660d548d5cc1b3cca154c7ebaee23ba59d7762 Mon Sep 17 00:00:00 2001 From: nulano Date: Fri, 10 Jul 2020 01:08:13 +0200 Subject: [PATCH 7/8] fix ImageQt reference --- docs/reference/ImageQt.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/ImageQt.rst b/docs/reference/ImageQt.rst index 887eab9ba..34d4cef51 100644 --- a/docs/reference/ImageQt.rst +++ b/docs/reference/ImageQt.rst @@ -9,7 +9,7 @@ objects from PIL images. .. versionadded:: 1.1.6 -.. py:class:: ImageQt.ImageQt(image) +.. py:class:: ImageQt(image) Creates an :py:class:`~PIL.ImageQt.ImageQt` object from a PIL :py:class:`~PIL.Image.Image` object. This class is a subclass of From 1ac943991ae7dd75996dbe25ab37c1a11a82bea9 Mon Sep 17 00:00:00 2001 From: nulano Date: Fri, 10 Jul 2020 14:16:04 +0100 Subject: [PATCH 8/8] Apply suggestions from code review Co-authored-by: Hugo van Kemenade --- docs/reference/ImageFilter.rst | 4 ++-- docs/reference/TiffTags.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/reference/ImageFilter.rst b/docs/reference/ImageFilter.rst index fc879883a..c85da4fb5 100644 --- a/docs/reference/ImageFilter.rst +++ b/docs/reference/ImageFilter.rst @@ -70,7 +70,7 @@ image enhancement filters: .. class:: Filter An abstract mixin used for filtering images - (for use with :py:meth:`~PIL.Image.Image.filter`) + (for use with :py:meth:`~PIL.Image.Image.filter`). Implementors must provide the following method: @@ -83,7 +83,7 @@ image enhancement filters: .. class:: MultibandFilter An abstract mixin used for filtering multi-band images - (for use with :py:meth:`~PIL.Image.Image.filter`) + (for use with :py:meth:`~PIL.Image.Image.filter`). Implementors must provide the following method: diff --git a/docs/reference/TiffTags.rst b/docs/reference/TiffTags.rst index 231051632..1441185dd 100644 --- a/docs/reference/TiffTags.rst +++ b/docs/reference/TiffTags.rst @@ -64,4 +64,4 @@ metadata tag numbers, names, and type information. .. py:data:: PIL.TiffTags.LIBTIFF_CORE :type: list - A list of supported tag ids when writing using libtiff. + A list of supported tag IDs when writing using LibTIFF.