diff --git a/docs/conf.py b/docs/conf.py index 2d80e3170..5b42bba11 100644 --- a/docs/conf.py +++ b/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"), ] diff --git a/docs/reference/Image.rst b/docs/reference/Image.rst index f24d382b8..c656507d9 100644 --- a/docs/reference/Image.rst +++ b/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 - limit. If desired, the warning can be turned into an error with + a lot of memory), Pillow will issue a ``DecompressionBombWarning`` if the number of pixels in an + 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 - documentation`_ to have warnings output to the logging facility instead of stderr. + ``warnings.simplefilter('ignore', Image.DecompressionBombWarning)``. See also + `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 ^^^^^^^^^^^^^^^^^ diff --git a/src/PIL/Image.py b/src/PIL/Image.py index 03829d9a9..927147956 100644 --- a/src/PIL/Image.py +++ b/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.