Merge pull request #4771 from nulano/refs-misc

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**
@@ -778,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.
@@ -831,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
 
@@ -848,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
 

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
+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

@@ -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:
 
@@ -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/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/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/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/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.

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