Merge pull request #7684 from nulano/docs-imagetransform

Improve ImageTransform documentation

docs/PIL.rst

@@ -77,14 +77,6 @@ can be found here.
     :undoc-members:
     :show-inheritance:
 
-:mod:`~PIL.ImageTransform` Module
----------------------------------
-
-.. automodule:: PIL.ImageTransform
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
 :mod:`~PIL.PaletteFile` Module
 ------------------------------
 

docs/reference/ImageTransform.rst

@@ -0,0 +1,35 @@
+
+.. py:module:: PIL.ImageTransform
+.. py:currentmodule:: PIL.ImageTransform
+
+:py:mod:`~PIL.ImageTransform` Module
+====================================
+
+The :py:mod:`~PIL.ImageTransform` module contains implementations of
+:py:class:`~PIL.Image.ImageTransformHandler` for some of the builtin
+:py:class:`.Image.Transform` methods.
+
+.. autoclass:: Transform
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: AffineTransform
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: ExtentTransform
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: QuadTransform
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: MeshTransform
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/reference/index.rst

@@ -25,6 +25,7 @@ Reference
    ImageShow
    ImageStat
    ImageTk
+   ImageTransform
    ImageWin
    ExifTags
    TiffTags

src/PIL/Image.py

@@ -2666,6 +2666,10 @@ class Example(Image.ImageTransformHandler):
                 def transform(self, size, data, resample, fill=1):
                     # Return result
 
+          Implementations of :py:class:`~PIL.Image.ImageTransformHandler`
+          for some of the :py:class:`Transform` methods are provided
+          in :py:mod:`~PIL.ImageTransform`.
+
           It may also be an object with a ``method.getdata`` method
           that returns a tuple supplying new ``method`` and ``data`` values::
 

src/PIL/ImageTransform.py

@@ -20,12 +20,14 @@
 
 
 class Transform(Image.ImageTransformHandler):
+    """Base class for other transforms defined in :py:mod:`~PIL.ImageTransform`."""
+
     method: Image.Transform
 
     def __init__(self, data: Sequence[int]) -> None:
         self.data = data
 
-    def getdata(self) -> tuple[int, Sequence[int]]:
+    def getdata(self) -> tuple[Image.Transform, Sequence[int]]:
         return self.method, self.data
 
     def transform(
@@ -34,6 +36,7 @@ def transform(
         image: Image.Image,
         **options: dict[str, str | int | tuple[int, ...] | list[int]],
     ) -> Image.Image:
+        """Perform the transform. Called from :py:meth:`.Image.transform`."""
         # can be overridden
         method, data = self.getdata()
         return image.transform(size, method, data, **options)
@@ -51,7 +54,7 @@ class AffineTransform(Transform):
     This function can be used to scale, translate, rotate, and shear the
     original image.
 
-    See :py:meth:`~PIL.Image.Image.transform`
+    See :py:meth:`.Image.transform`
 
     :param matrix: A 6-tuple (a, b, c, d, e, f) containing the first two rows
         from an affine transform matrix.
@@ -73,7 +76,7 @@ class ExtentTransform(Transform):
     rectangle in the current image. It is slightly slower than crop, but about
     as fast as a corresponding resize operation.
 
-    See :py:meth:`~PIL.Image.Image.transform`
+    See :py:meth:`.Image.transform`
 
     :param bbox: A 4-tuple (x0, y0, x1, y1) which specifies two points in the
         input image's coordinate system. See :ref:`coordinate-system`.
@@ -89,7 +92,7 @@ class QuadTransform(Transform):
     Maps a quadrilateral (a region defined by four corners) from the image to a
     rectangle of the given size.
 
-    See :py:meth:`~PIL.Image.Image.transform`
+    See :py:meth:`.Image.transform`
 
     :param xy: An 8-tuple (x0, y0, x1, y1, x2, y2, x3, y3) which contain the
         upper left, lower left, lower right, and upper right corner of the
@@ -104,7 +107,7 @@ class MeshTransform(Transform):
     Define a mesh image transform.  A mesh transform consists of one or more
     individual quad transforms.
 
-    See :py:meth:`~PIL.Image.Image.transform`
+    See :py:meth:`.Image.transform`
 
     :param data: A list of (bbox, quad) tuples.
     """