Merge branch 'master' into refs-nitpick

.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"

.travis.yml

@@ -46,6 +46,9 @@ matrix:
       env: PYTHONOPTIMIZE=2
       services: xvfb
 
+  allow_failures:
+  - python: "3.9-dev"
+
 install:
   - |
     if [ "$LINT" == "true" ]; then

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.

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:

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']

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**
@@ -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
 ~~~~~~
 
@@ -774,7 +778,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 +831,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 +848,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
 
@@ -857,7 +861,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"``

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
 ^^^^^^^^^^^^^^^^^^
 
 ::
@@ -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
+implement ``file.read``, ``file.seek`` and ``file.tell`` methods,
-:py:meth:`~file.tell` methods, and be opened in binary mode.
+and be opened in binary mode.
 
 Reading from an open file
 ^^^^^^^^^^^^^^^^^^^^^^^^^

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.
@@ -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**:
 
 +-----------+-----------------------------------------------------------------+

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
 

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:
 
@@ -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
@@ -330,6 +330,16 @@ 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.Exif
+    :members:
+    :undoc-members:
+    :show-inheritance:
+.. autoclass:: PIL.Image.ImagePointHandler
+.. autoclass:: PIL.Image.ImageTransformHandler
+
 Constants
 ---------
 

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
 

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.

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

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"``.
 

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

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

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.

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`.

docs/reference/plugins.rst

@@ -229,20 +229,12 @@ Plugin reference
 ---------------------------------
 
 .. automodule:: PIL.PngImagePlugin
-    :members: ChunkStream, PngStream, getchunks, is_cid, putchunk
+    :members: ChunkStream, PngImageFile, PngStream, getchunks, is_cid, putchunk,
-    :show-inheritance:
+        MAX_TEXT_CHUNK, MAX_TEXT_MEMORY, APNG_BLEND_OP_SOURCE, APNG_BLEND_OP_OVER,
-.. autoclass:: PIL.PngImagePlugin.ChunkStream
+        APNG_DISPOSE_OP_NONE, APNG_DISPOSE_OP_BACKGROUND, APNG_DISPOSE_OP_PREVIOUS
-    :members:
-    :undoc-members:
-    :show-inheritance:
-.. autoclass:: PIL.PngImagePlugin.PngImageFile
-    :members:
-    :undoc-members:
-    :show-inheritance:
-.. autoclass:: PIL.PngImagePlugin.PngStream
-    :members:
     :undoc-members:
     :show-inheritance:
+    :member-order: groupwise
 
 
 :mod:`~PIL.PpmImagePlugin` Module

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`,
+* The methods ``PIL.ImageDraw.ImageDraw.setink``,
-  :py:meth:`PIL.ImageDraw.ImageDraw.setfill`, and
+  ``PIL.ImageDraw.ImageDraw.setfill``, and
-  :py:meth:`PIL.ImageDraw.ImageDraw.setfont` have been removed.
+  ``PIL.ImageDraw.ImageDraw.setfont`` have been removed.
 
 
 Closing Files When Opening Images

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`,
+* The methods ``PIL.ImageWin.Dib.fromstring``,
-  :py:meth:`PIL.ImageWin.Dib.tostring` and
+  ``PIL.ImageWin.Dib.tostring`` and
-  :py:meth:`PIL.TiffImagePlugin.ImageFileDirectory_v2.as_dict` have
+  ``PIL.TiffImagePlugin.ImageFileDirectory_v2.as_dict`` have
   been removed.
 
 * Before Pillow 4.2.0, attempting to save an RGBA image as JPEG would

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.

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

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,

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.

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":

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
@@ -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
@@ -2352,10 +2359,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:
@@ -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
 
 
@@ -2847,8 +2862,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`,
+       The file object must implement ``file.read``,
-       :py:meth:`~file.seek`, and :py:meth:`~file.tell` methods,
+       ``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.

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`
     """

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.

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,13 +20,13 @@ import sys
 from . import EpsImagePlugin
 
 ##
-# Simple Postscript graphics interface.
+# Simple PostScript graphics interface.
 
 
 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):
@@ -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)

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<png-text>`.
+"""
 MAX_TEXT_MEMORY = 64 * MAX_TEXT_CHUNK
+"""
+Set the maximum total text chunk size.
+See :ref:`Text in PNG File Format<png-text>`.
+"""
 
 
 # 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-saving>`.
+"""
 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-saving>`.
+"""
 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-saving>`.
+"""
 
 # 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-saving>`.
+"""
 APNG_BLEND_OP_OVER = 1
+"""
+This frame should be alpha composited with the previous output image contents.
+See :ref:`Saving APNG sequences<apng-saving>`.
+"""
 
 
 def _safe_zlib_decompress(s):