Merge pull request #4802 from radarhere/max

Documented MAX_IMAGE_PIXELS

docs/conf.py

@@ -118,7 +118,6 @@ nitpick_ignore = [
     ("py:attr", "PIL.Image.Image.tag"),
     ("py:attr", "PIL.Image.Image.tag_v2"),
     ("py:attr", "PIL.Image.Image.tile"),
-    ("py:data", "PIL.Image.MAX_IMAGE_PIXELS"),
     ("py:attr", "PIL.TiffImagePlugin.ImageFileDirectory_v2.tagtype"),
 ]
 

docs/reference/Image.rst

@@ -52,11 +52,19 @@ Functions
     .. warning::
         To protect against potential DOS attacks caused by "`decompression bombs`_" (i.e. malicious files
         which decompress into a huge amount of data and are designed to crash or cause disruption by using up
-        a lot of memory), Pillow will issue a ``DecompressionBombWarning`` if the image is over a certain
+        a lot of memory), Pillow will issue a ``DecompressionBombWarning`` if the number of pixels in an
-        limit. If desired, the warning can be turned into an error with
+        image is over a certain limit, :py:data:`PIL.Image.MAX_IMAGE_PIXELS`.
+
+        This threshold can be changed by setting :py:data:`PIL.Image.MAX_IMAGE_PIXELS`. It can be disabled
+        by setting ``Image.MAX_IMAGE_PIXELS = None``.
+
+        If desired, the warning can be turned into an error with
         ``warnings.simplefilter('error', Image.DecompressionBombWarning)`` or suppressed entirely with
-        ``warnings.simplefilter('ignore', Image.DecompressionBombWarning)``. See also `the logging
+        ``warnings.simplefilter('ignore', Image.DecompressionBombWarning)``. See also
-        documentation`_ to have warnings output to the logging facility instead of stderr.
+        `the logging documentation`_ to have warnings output to the logging facility instead of stderr.
+
+        If the number of pixels is greater than twice :py:data:`PIL.Image.MAX_IMAGE_PIXELS`, then a
+        ``DecompressionBombError`` will be raised instead.
 
     .. _decompression bombs: https://en.wikipedia.org/wiki/Zip_bomb
     .. _the logging documentation: https://docs.python.org/3/library/logging.html#integration-with-the-warnings-module
@@ -374,6 +382,10 @@ Constants
 ---------
 
 .. data:: NONE
+.. data:: MAX_IMAGE_PIXELS
+
+    Set to 89,478,485, approximately 0.25GB for a 24-bit (3 bpp) image.
+    See :py:meth:`~PIL.Image.open` for more information about how this is used.
 
 Transpose methods
 ^^^^^^^^^^^^^^^^^

src/PIL/Image.py

@@ -81,7 +81,7 @@ class DecompressionBombError(Exception):
     pass
 
 
-# Limit to around a quarter gigabyte for a 24 bit (3 bpp) image
+# Limit to around a quarter gigabyte for a 24-bit (3 bpp) image
 MAX_IMAGE_PIXELS = int(1024 * 1024 * 1024 // 4 // 3)
 
 
@@ -2869,7 +2869,7 @@ def open(fp, mode="r"):
 
     :param fp: A filename (string), pathlib.Path object or a file object.
        The file object must implement ``file.read``,
-       ``file.seek`, and ``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.