From af5e0fa2aac6504846fad96f212243f70edfe8ff Mon Sep 17 00:00:00 2001 From: nulano Date: Thu, 9 Jul 2020 23:20:45 +0200 Subject: [PATCH 01/18] add Python stdlib intersphinx mapping --- docs/conf.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index c700fff79..ddfb24fe3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -34,6 +34,8 @@ extensions = [ "sphinx_removed_in", ] +intersphinx_mapping = {"python": ("https://docs.python.org/3", None)} + # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # source_suffix = ['.rst', '.md'] From 09a87161a240d84cf20e02b6ef6faea0172d8c01 Mon Sep 17 00:00:00 2001 From: nulano Date: Thu, 9 Jul 2020 23:46:28 +0200 Subject: [PATCH 02/18] fix sys.stdout reference --- src/PIL/PSDraw.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/PIL/PSDraw.py b/src/PIL/PSDraw.py index 762d31e88..a080ce44d 100644 --- a/src/PIL/PSDraw.py +++ b/src/PIL/PSDraw.py @@ -26,7 +26,7 @@ from . import EpsImagePlugin class PSDraw: """ Sets up printing to the given file. If **fp** is omitted, - :py:attr:`sys.stdout` is assumed. + :py:data:`sys.stdout` is assumed. """ def __init__(self, fp=None): From 9589159585e996e75dd47c7155635043a31cffca Mon Sep 17 00:00:00 2001 From: nulano Date: Thu, 9 Jul 2020 23:50:57 +0200 Subject: [PATCH 03/18] use cross-reference for None value --- docs/handbook/image-file-formats.rst | 2 +- docs/handbook/writing-your-own-file-decoder.rst | 2 +- docs/reference/Image.rst | 4 ++-- docs/reference/ImageDraw.rst | 2 +- docs/reference/ImageGrab.rst | 2 +- docs/releasenotes/5.3.0.rst | 2 +- docs/releasenotes/7.0.0.rst | 4 ++-- docs/releasenotes/7.1.0.rst | 2 +- 8 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/handbook/image-file-formats.rst b/docs/handbook/image-file-formats.rst index 6bcff7135..3daa75c96 100644 --- a/docs/handbook/image-file-formats.rst +++ b/docs/handbook/image-file-formats.rst @@ -857,7 +857,7 @@ The :py:meth:`~PIL.Image.Image.save` method can take the following keyword argum **compression** A string containing the desired compression method for the file. (valid only with libtiff installed) Valid compression - methods are: ``None``, ``"tiff_ccitt"``, ``"group3"``, + methods are: :data:`None`, ``"tiff_ccitt"``, ``"group3"``, ``"group4"``, ``"tiff_jpeg"``, ``"tiff_adobe_deflate"``, ``"tiff_thunderscan"``, ``"tiff_deflate"``, ``"tiff_sgilog"``, ``"tiff_sgilog24"``, ``"tiff_raw_16"`` diff --git a/docs/handbook/writing-your-own-file-decoder.rst b/docs/handbook/writing-your-own-file-decoder.rst index 89d0e3e9f..2a546b0c6 100644 --- a/docs/handbook/writing-your-own-file-decoder.rst +++ b/docs/handbook/writing-your-own-file-decoder.rst @@ -132,7 +132,7 @@ The fields are used as follows: **parameters** Parameters to the decoder. The contents of this field depends on the decoder specified by the first field in the tile descriptor tuple. If the - decoder doesn’t need any parameters, use ``None`` for this field. + decoder doesn’t need any parameters, use :data:`None` for this field. Note that the :py:attr:`tile` attribute contains a list of tile descriptors, not just a single descriptor. diff --git a/docs/reference/Image.rst b/docs/reference/Image.rst index 6fe499036..347c57688 100644 --- a/docs/reference/Image.rst +++ b/docs/reference/Image.rst @@ -285,7 +285,7 @@ Instances of the :py:class:`Image` class have the following attributes: The file format of the source file. For images created by the library itself (via a factory function, or by running a method on an existing - image), this attribute is set to ``None``. + image), this attribute is set to :data:`None`. .. py:attribute:: Image.mode :type: str @@ -314,7 +314,7 @@ Instances of the :py:class:`Image` class have the following attributes: Colour palette table, if any. If mode is "P" or "PA", this should be an instance of the :py:class:`~PIL.ImagePalette.ImagePalette` class. - Otherwise, it should be set to ``None``. + Otherwise, it should be set to :data:`None`. .. py:attribute:: Image.info :type: dict diff --git a/docs/reference/ImageDraw.rst b/docs/reference/ImageDraw.rst index fd74b69c1..3faa0d3e0 100644 --- a/docs/reference/ImageDraw.rst +++ b/docs/reference/ImageDraw.rst @@ -212,7 +212,7 @@ Methods .. versionadded:: 1.1.5 .. note:: This option was broken until version 1.1.6. - :param joint: Joint type between a sequence of lines. It can be ``"curve"``, for rounded edges, or ``None``. + :param joint: Joint type between a sequence of lines. It can be ``"curve"``, for rounded edges, or :data:`None`. .. versionadded:: 5.3.0 diff --git a/docs/reference/ImageGrab.rst b/docs/reference/ImageGrab.rst index a9427be9c..ac83b2255 100644 --- a/docs/reference/ImageGrab.rst +++ b/docs/reference/ImageGrab.rst @@ -27,7 +27,7 @@ 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. + X11 Display address. Pass :data:`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"``. diff --git a/docs/releasenotes/5.3.0.rst b/docs/releasenotes/5.3.0.rst index cce671c32..bff56566b 100644 --- a/docs/releasenotes/5.3.0.rst +++ b/docs/releasenotes/5.3.0.rst @@ -34,7 +34,7 @@ Curved joints for line sequences ``ImageDraw.Draw.line`` draws a line, or lines, between points. Previously, when multiple points are given, for a larger ``width``, the joints between these lines looked unsightly. There is now an additional optional argument, -``joint``, defaulting to ``None``. When it is set to ``curved``, the joints +``joint``, defaulting to :data:`None`. When it is set to ``curved``, the joints between the lines will become rounded. ImageOps.colorize diff --git a/docs/releasenotes/7.0.0.rst b/docs/releasenotes/7.0.0.rst index 73c44275c..80002b0ce 100644 --- a/docs/releasenotes/7.0.0.rst +++ b/docs/releasenotes/7.0.0.rst @@ -66,7 +66,7 @@ See :ref:`concept-filters` to learn the difference. In short, Image.draft() return value ^^^^^^^^^^^^^^^^^^^^^^^^^^ -If the :py:meth:`~PIL.Image.Image.draft` method has no effect, it returns ``None``. +If the :py:meth:`~PIL.Image.Image.draft` method has no effect, it returns :data:`None`. If it does have an effect, then it previously returned the image itself. However, unlike other `chain methods`_, :py:meth:`~PIL.Image.Image.draft` does not return a modified version of the image, but modifies it in-place. So instead, if @@ -95,7 +95,7 @@ the closer the result to the fair resampling. The smaller ``reducing_gap``, the faster resizing. With ``reducing_gap`` greater or equal to 3.0, the result is indistinguishable from fair resampling. -The default value for :py:meth:`~PIL.Image.Image.resize` is ``None``, +The default value for :py:meth:`~PIL.Image.Image.resize` is :data:`None`, which means that the optimization is turned off by default. The default value for :py:meth:`~PIL.Image.Image.thumbnail` is 2.0, diff --git a/docs/releasenotes/7.1.0.rst b/docs/releasenotes/7.1.0.rst index 55a970c1e..35e5c4464 100644 --- a/docs/releasenotes/7.1.0.rst +++ b/docs/releasenotes/7.1.0.rst @@ -63,7 +63,7 @@ Support has been added for ``ImageGrab.grab()`` on Linux using the X server with the XCB library. An optional ``xdisplay`` parameter has been added to select the X server, -with the default value of ``None`` using the default X server. +with the default value of :data:`None` using the default X server. Passing a different value on Windows or macOS will force taking a snapshot using the selected X server; pass an empty string to use the default X server. From 3fa495ca25de2ca51ba053cc37430c890097393e Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Fri, 10 Jul 2020 11:12:21 +0300 Subject: [PATCH 04/18] Allow 3.9-dev to fail --- .travis.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.travis.yml b/.travis.yml index 980506368..bfe366000 100644 --- a/.travis.yml +++ b/.travis.yml @@ -46,6 +46,9 @@ matrix: env: PYTHONOPTIMIZE=2 services: xvfb + allow_failures: + - python: "3.9-dev" + install: - | if [ "$LINT" == "true" ]; then From 384523fab28c536eeedd3ea1e294fb4438a1ea6e Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Fri, 10 Jul 2020 11:48:02 +0300 Subject: [PATCH 05/18] Fix PostScript typos --- CHANGES.rst | 6 +++--- docs/handbook/tutorial.rst | 6 +++--- docs/reference/PSDraw.rst | 2 +- src/PIL/EpsImagePlugin.py | 6 +++--- src/PIL/PSDraw.py | 18 +++++++++--------- 5 files changed, 19 insertions(+), 19 deletions(-) diff --git a/CHANGES.rst b/CHANGES.rst index 62a134717..e06508f38 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -5587,7 +5587,7 @@ Pre-fork any other pixel value means opaque. This is faster than using an "L" transparency mask. - + Properly writes EPS files (and properly prints images to postscript + + Properly writes EPS files (and properly prints images to PostScript printers as well). + Reads 4-bit BMP files, as well as 4 and 8-bit Windows ICO and CUR @@ -5670,7 +5670,7 @@ Pre-fork + Added the "pilfile" utility, which quickly identifies image files (without loading them, in most cases). - + Added the "pilprint" utility, which prints image files to Postscript + + Added the "pilprint" utility, which prints image files to PostScript printers. + Added a rudimentary version of the "pilview" utility, which is @@ -5684,5 +5684,5 @@ Pre-fork Jack). This allows you to read images through the Img extensions file format handlers. See the file "Lib/ImgExtImagePlugin.py" for details. - + Postscript printing is provided through the PSDraw module. See the + + PostScript printing is provided through the PSDraw module. See the handbook for details. diff --git a/docs/handbook/tutorial.rst b/docs/handbook/tutorial.rst index 94a8e3aa1..76c0fa83f 100644 --- a/docs/handbook/tutorial.rst +++ b/docs/handbook/tutorial.rst @@ -406,13 +406,13 @@ Using the ImageSequence Iterator class # ...do something to frame... -Postscript printing +PostScript printing ------------------- The Python Imaging Library includes functions to print images, text and -graphics on Postscript printers. Here’s a simple example: +graphics on PostScript printers. Here’s a simple example: -Drawing Postscript +Drawing PostScript ^^^^^^^^^^^^^^^^^^ :: diff --git a/docs/reference/PSDraw.rst b/docs/reference/PSDraw.rst index 958385818..3e8512e7a 100644 --- a/docs/reference/PSDraw.rst +++ b/docs/reference/PSDraw.rst @@ -4,7 +4,7 @@ :py:mod:`~PIL.PSDraw` Module ============================ -The :py:mod:`~PIL.PSDraw` module provides simple print support for Postscript +The :py:mod:`~PIL.PSDraw` module provides simple print support for PostScript printers. You can print text, graphics and images through this module. .. autoclass:: PIL.PSDraw.PSDraw diff --git a/src/PIL/EpsImagePlugin.py b/src/PIL/EpsImagePlugin.py index 652dc489a..16d7ae039 100644 --- a/src/PIL/EpsImagePlugin.py +++ b/src/PIL/EpsImagePlugin.py @@ -191,7 +191,7 @@ def _accept(prefix): ## -# Image plugin for Encapsulated Postscript. This plugin supports only +# Image plugin for Encapsulated PostScript. This plugin supports only # a few variants of this format. @@ -262,7 +262,7 @@ class EpsImageFile(ImageFile.ImageFile): else: self.info[k] = "" elif s[0] == "%": - # handle non-DSC Postscript comments that some + # handle non-DSC PostScript comments that some # tools mistakenly put in the Comments section pass else: @@ -352,7 +352,7 @@ def _save(im, fp, filename, eps=1): im.load() # - # determine postscript image mode + # determine PostScript image mode if im.mode == "L": operator = (8, 1, "image") elif im.mode == "RGB": diff --git a/src/PIL/PSDraw.py b/src/PIL/PSDraw.py index 762d31e88..4b71d5790 100644 --- a/src/PIL/PSDraw.py +++ b/src/PIL/PSDraw.py @@ -2,7 +2,7 @@ # The Python Imaging Library # $Id$ # -# simple postscript graphics interface +# Simple PostScript graphics interface # # History: # 1996-04-20 fl Created @@ -20,7 +20,7 @@ import sys from . import EpsImagePlugin ## -# Simple Postscript graphics interface. +# Simple PostScript graphics interface. class PSDraw: @@ -41,7 +41,7 @@ class PSDraw: self.fp.write(bytes(to_write, "UTF-8")) def begin_document(self, id=None): - """Set up printing of a document. (Write Postscript DSC header.)""" + """Set up printing of a document. (Write PostScript DSC header.)""" # FIXME: incomplete self._fp_write( "%!PS-Adobe-3.0\n" @@ -57,7 +57,7 @@ class PSDraw: self.isofont = {} def end_document(self): - """Ends printing. (Write Postscript DSC footer.)""" + """Ends printing. (Write PostScript DSC footer.)""" self._fp_write("%%EndDocument\nrestore showpage\n%%End\n") if hasattr(self.fp, "flush"): self.fp.flush() @@ -66,7 +66,7 @@ class PSDraw: """ Selects which font to use. - :param font: A Postscript font name + :param font: A PostScript font name :param size: Size in points. """ if font not in self.isofont: @@ -79,7 +79,7 @@ class PSDraw: def line(self, xy0, xy1): """ Draws a line between the two points. Coordinates are given in - Postscript point coordinates (72 points per inch, (0, 0) is the lower + PostScript point coordinates (72 points per inch, (0, 0) is the lower left corner of the page). """ xy = xy0 + xy1 @@ -143,10 +143,10 @@ class PSDraw: # -------------------------------------------------------------------- -# Postscript driver +# PostScript driver # -# EDROFF.PS -- Postscript driver for Edroff 2 +# EDROFF.PS -- PostScript driver for Edroff 2 # # History: # 94-01-25 fl: created (edroff 2.04) @@ -176,7 +176,7 @@ EDROFF_PS = """\ """ # -# VDI.PS -- Postscript driver for VDI meta commands +# VDI.PS -- PostScript driver for VDI meta commands # # History: # 94-01-25 fl: created (edroff 2.04) From 20135f7cbd8309d20b9ebd8c005376efea8625f2 Mon Sep 17 00:00:00 2001 From: Andrew Murray Date: Fri, 10 Jul 2020 21:26:49 +1000 Subject: [PATCH 06/18] Install setuptools 47.3.1 on Python 3.9 --- .ci/install.sh | 1 + 1 file changed, 1 insertion(+) diff --git a/.ci/install.sh b/.ci/install.sh index 8a3b8fee4..36bce295c 100755 --- a/.ci/install.sh +++ b/.ci/install.sh @@ -30,6 +30,7 @@ pip install -U pytest-cov pip install pyroma pip install test-image-results pip install numpy +if [ "$TRAVIS_PYTHON_VERSION" == "3.9-dev" ]; then pip install setuptools==47.3.1 ; fi if [[ $TRAVIS_PYTHON_VERSION == 3.* ]]; then # arm64, ppc64le, s390x CPUs: # "ERROR: Could not find a version that satisfies the requirement pyqt5" From d7309b25d49ee0d4e2ceb57701a1e194962ea0fe Mon Sep 17 00:00:00 2001 From: joseville1001 <66519798+joseville1001@users.noreply.github.com> Date: Fri, 10 Jul 2020 21:17:08 -0400 Subject: [PATCH 07/18] Update ImageFilter.py `the` -> `The` --- src/PIL/ImageFilter.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/PIL/ImageFilter.py b/src/PIL/ImageFilter.py index 3e61a6ca1..18c550c84 100644 --- a/src/PIL/ImageFilter.py +++ b/src/PIL/ImageFilter.py @@ -49,7 +49,7 @@ class Kernel(BuiltinFilter): version, this must be (3,3) or (5,5). :param kernel: A sequence containing kernel weights. :param scale: Scale factor. If given, the result for each pixel is - divided by this value. the default is the sum of the + divided by this value. The default is the sum of the kernel weights. :param offset: Offset. If given, this value is added to the result, after it has been divided by the scale factor. From 9c277f5c498ddd451cdced6bc50d74e3020dd0e2 Mon Sep 17 00:00:00 2001 From: nulano Date: Thu, 9 Jul 2020 22:16:25 +0200 Subject: [PATCH 08/18] document PngImagePlugin constants --- docs/handbook/image-file-formats.rst | 8 +++++-- docs/reference/plugins.rst | 16 ++++--------- src/PIL/PngImagePlugin.py | 35 +++++++++++++++++++++++++--- 3 files changed, 42 insertions(+), 17 deletions(-) diff --git a/docs/handbook/image-file-formats.rst b/docs/handbook/image-file-formats.rst index 3daa75c96..771f4f557 100644 --- a/docs/handbook/image-file-formats.rst +++ b/docs/handbook/image-file-formats.rst @@ -501,12 +501,14 @@ The :py:meth:`~PIL.Image.Image.open` method sets the following This key is omitted if the image is not a transparent palette image. +.. _png-text: + ``open`` also sets ``Image.text`` to a dictionary of the values of the ``tEXt``, ``zTXt``, and ``iTXt`` chunks of the PNG image. Individual compressed chunks are limited to a decompressed size of -``PngImagePlugin.MAX_TEXT_CHUNK``, by default 1MB, to prevent +:data:`.PngImagePlugin.MAX_TEXT_CHUNK`, by default 1MB, to prevent decompression bombs. Additionally, the total size of all of the text -chunks is limited to ``PngImagePlugin.MAX_TEXT_MEMORY``, defaulting to +chunks is limited to :data:`.PngImagePlugin.MAX_TEXT_MEMORY`, defaulting to 64MB. The :py:meth:`~PIL.Image.Image.save` method supports the following options: @@ -611,6 +613,8 @@ where applicable: Any APNG file containing sequence errors is treated as an invalid image. The APNG loader will not attempt to repair and reorder files containing sequence errors. +.. _apng-saving: + Saving ~~~~~~ diff --git a/docs/reference/plugins.rst b/docs/reference/plugins.rst index ef080b6db..7094f8784 100644 --- a/docs/reference/plugins.rst +++ b/docs/reference/plugins.rst @@ -229,20 +229,12 @@ Plugin reference --------------------------------- .. automodule:: PIL.PngImagePlugin - :members: ChunkStream, PngStream, getchunks, is_cid, putchunk - :show-inheritance: -.. autoclass:: PIL.PngImagePlugin.ChunkStream - :members: - :undoc-members: - :show-inheritance: -.. autoclass:: PIL.PngImagePlugin.PngImageFile - :members: - :undoc-members: - :show-inheritance: -.. autoclass:: PIL.PngImagePlugin.PngStream - :members: + :members: ChunkStream, PngImageFile, PngStream, getchunks, is_cid, putchunk, + MAX_TEXT_CHUNK, MAX_TEXT_MEMORY, APNG_BLEND_OP_SOURCE, APNG_BLEND_OP_OVER, + APNG_DISPOSE_OP_NONE, APNG_DISPOSE_OP_BACKGROUND, APNG_DISPOSE_OP_PREVIOUS :undoc-members: :show-inheritance: + :member-order: groupwise :mod:`~PIL.PpmImagePlugin` Module diff --git a/src/PIL/PngImagePlugin.py b/src/PIL/PngImagePlugin.py index e027953dd..dd70edfe8 100644 --- a/src/PIL/PngImagePlugin.py +++ b/src/PIL/PngImagePlugin.py @@ -76,21 +76,50 @@ _MODES = { _simple_palette = re.compile(b"^\xff*\x00\xff*$") -# Maximum decompressed size for a iTXt or zTXt chunk. -# Eliminates decompression bombs where compressed chunks can expand 1000x MAX_TEXT_CHUNK = ImageFile.SAFEBLOCK -# Set the maximum total text chunk size. +""" +Maximum decompressed size for a iTXt or zTXt chunk. +Eliminates decompression bombs where compressed chunks can expand 1000x +See :ref:`Text in PNG File Format`. +""" MAX_TEXT_MEMORY = 64 * MAX_TEXT_CHUNK +""" +Set the maximum total text chunk size. +See :ref:`Text in PNG File Format`. +""" # APNG frame disposal modes APNG_DISPOSE_OP_NONE = 0 +""" +No disposal is done on this frame before rendering the next frame. +See :ref:`Saving APNG sequences`. +""" APNG_DISPOSE_OP_BACKGROUND = 1 +""" +This frame’s modified region is cleared to fully transparent black before rendering +the next frame. +See :ref:`Saving APNG sequences`. +""" APNG_DISPOSE_OP_PREVIOUS = 2 +""" +This frame’s modified region is reverted to the previous frame’s contents before +rendering the next frame. +See :ref:`Saving APNG sequences`. +""" # APNG frame blend modes APNG_BLEND_OP_SOURCE = 0 +""" +All color components of this frame, including alpha, overwrite the previous output +image contents. +See :ref:`Saving APNG sequences`. +""" APNG_BLEND_OP_OVER = 1 +""" +This frame should be alpha composited with the previous output image contents. +See :ref:`Saving APNG sequences`. +""" def _safe_zlib_decompress(s): From 1fa01b013589c154a0d8ab33235cd9de2a1716c4 Mon Sep 17 00:00:00 2001 From: nulano Date: Thu, 9 Jul 2020 22:16:44 +0200 Subject: [PATCH 09/18] fix iTXt and PngInfo heading references --- docs/PIL.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/PIL.rst b/docs/PIL.rst index 4b10184fa..fa036b9cc 100644 --- a/docs/PIL.rst +++ b/docs/PIL.rst @@ -93,8 +93,8 @@ can be found here. :undoc-members: :show-inheritance: -:class:`PngImagePlugin.iTXt` Class ----------------------------------- +:class:`.PngImagePlugin.iTXt` Class +----------------------------------- .. autoclass:: PIL.PngImagePlugin.iTXt :members: @@ -107,8 +107,8 @@ can be found here. :param lang: language code :param tkey: UTF-8 version of the key name -:class:`PngImagePlugin.PngInfo` Class -------------------------------------- +:class:`.PngImagePlugin.PngInfo` Class +-------------------------------------- .. autoclass:: PIL.PngImagePlugin.PngInfo :members: From 2ce2fa2dfc61463823736fa0a8c724ae0665f751 Mon Sep 17 00:00:00 2001 From: nulano Date: Fri, 10 Jul 2020 14:17:10 +0100 Subject: [PATCH 10/18] Add a period Co-authored-by: Hugo van Kemenade --- src/PIL/PngImagePlugin.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/PIL/PngImagePlugin.py b/src/PIL/PngImagePlugin.py index dd70edfe8..9d048b211 100644 --- a/src/PIL/PngImagePlugin.py +++ b/src/PIL/PngImagePlugin.py @@ -79,7 +79,7 @@ _simple_palette = re.compile(b"^\xff*\x00\xff*$") MAX_TEXT_CHUNK = ImageFile.SAFEBLOCK """ Maximum decompressed size for a iTXt or zTXt chunk. -Eliminates decompression bombs where compressed chunks can expand 1000x +Eliminates decompression bombs where compressed chunks can expand 1000x. See :ref:`Text in PNG File Format`. """ MAX_TEXT_MEMORY = 64 * MAX_TEXT_CHUNK From 0083ebb3d49c580cb606ebec8a9e37062ef147d2 Mon Sep 17 00:00:00 2001 From: nulano Date: Thu, 9 Jul 2020 19:48:04 +0200 Subject: [PATCH 11/18] 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 12/18] 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 13/18] 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 14/18] 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 15/18] 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 16/18] 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 17/18] 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 18/18] 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.