Pillow/docs/releasenotes/9.1.0.rst

9.1.0
-----

API Changes
===========

Raise an error when performing a negative crop
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Performing a negative crop on an image previously just returned a ``(0, 0)`` image. Now
it will raise a ``ValueError``, to help reduce confusion if a user has unintentionally
provided the wrong arguments.

Added specific error if path coordinate type is incorrect
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Rather than returning a ``SystemError``, passing the incorrect types of coordinates into
a path will now raise a more specific ``ValueError``, with the message "incorrect
coordinate type".

Deprecations
^^^^^^^^^^^^

Constants
~~~~~~~~~

A number of constants have been deprecated and will be removed in Pillow 10.0.0
(2023-07-01). Instead, ``enum.IntEnum`` classes have been added.

=====================================================  ============================================================
Deprecated                                             Use instead
=====================================================  ============================================================
``Image.NONE``                                         Either ``Image.Dither.NONE`` or ``Image.Resampling.NEAREST``
``Image.NEAREST``                                      Either ``Image.Dither.NONE`` or ``Image.Resampling.NEAREST``
``Image.ORDERED``                                      ``Image.Dither.ORDERED``
``Image.RASTERIZE``                                    ``Image.Dither.RASTERIZE``
``Image.FLOYDSTEINBERG``                               ``Image.Dither.FLOYDSTEINBERG``
``Image.WEB``                                          ``Image.Palette.WEB``
``Image.ADAPTIVE``                                     ``Image.Palette.ADAPTIVE``
``Image.AFFINE``                                       ``Image.Transform.AFFINE``
``Image.EXTENT``                                       ``Image.Transform.EXTENT``
``Image.PERSPECTIVE``                                  ``Image.Transform.PERSPECTIVE``
``Image.QUAD``                                         ``Image.Transform.QUAD``
``Image.MESH``                                         ``Image.Transform.MESH``
``Image.FLIP_LEFT_RIGHT``                              ``Image.Transpose.FLIP_LEFT_RIGHT``
``Image.FLIP_TOP_BOTTOM``                              ``Image.Transpose.FLIP_TOP_BOTTOM``
``Image.ROTATE_90``                                    ``Image.Transpose.ROTATE_90``
``Image.ROTATE_180``                                   ``Image.Transpose.ROTATE_180``
``Image.ROTATE_270``                                   ``Image.Transpose.ROTATE_270``
``Image.TRANSPOSE``                                    ``Image.Transpose.TRANSPOSE``
``Image.TRANSVERSE``                                   ``Image.Transpose.TRANSVERSE``
``Image.BOX``                                          ``Image.Resampling.BOX``
``Image.BILINEAR``                                     ``Image.Resampling.BILNEAR``
``Image.LINEAR``                                       ``Image.Resampling.BILNEAR``
``Image.HAMMING``                                      ``Image.Resampling.HAMMING``
``Image.BICUBIC``                                      ``Image.Resampling.BICUBIC``
``Image.CUBIC``                                        ``Image.Resampling.BICUBIC``
``Image.LANCZOS``                                      ``Image.Resampling.LANCZOS``
``Image.ANTIALIAS``                                    ``Image.Resampling.LANCZOS``
``Image.MEDIANCUT``                                    ``Image.Quantize.MEDIANCUT``
``Image.MAXCOVERAGE``                                  ``Image.Quantize.MAXCOVERAGE``
``Image.FASTOCTREE``                                   ``Image.Quantize.FASTOCTREE``
``Image.LIBIMAGEQUANT``                                ``Image.Quantize.LIBIMAGEQUANT``
``ImageCms.INTENT_PERCEPTUAL``                         ``ImageCms.Intent.PERCEPTUAL``
``ImageCms.INTENT_RELATIVE_COLORMETRIC``               ``ImageCms.Intent.RELATIVE_COLORMETRIC``
``ImageCms.INTENT_SATURATION``                         ``ImageCms.Intent.SATURATION``
``ImageCms.INTENT_ABSOLUTE_COLORIMETRIC``              ``ImageCms.Intent.ABSOLUTE_COLORIMETRIC``
``ImageCms.DIRECTION_INPUT``                           ``ImageCms.Direction.INPUT``
``ImageCms.DIRECTION_OUTPUT``                          ``ImageCms.Direction.OUTPUT``
``ImageCms.DIRECTION_PROOF``                           ``ImageCms.Direction.PROOF``
``ImageFont.LAYOUT_BASIC``                             ``ImageFont.Layout.BASIC``
``ImageFont.LAYOUT_RAQM``                              ``ImageFont.Layout.RAQM``
``BlpImagePlugin.BLP_FORMAT_JPEG``                     ``BlpImagePlugin.Format.JPEG``
``BlpImagePlugin.BLP_ENCODING_UNCOMPRESSED``           ``BlpImagePlugin.Encoding.UNCOMPRESSED``
``BlpImagePlugin.BLP_ENCODING_DXT``                    ``BlpImagePlugin.Encoding.DXT``
``BlpImagePlugin.BLP_ENCODING_UNCOMPRESSED_RAW_RGBA``  ``BlpImagePlugin.Encoding.UNCOMPRESSED_RAW_RGBA``
``BlpImagePlugin.BLP_ALPHA_ENCODING_DXT1``             ``BlpImagePlugin.AlphaEncoding.DXT1``
``BlpImagePlugin.BLP_ALPHA_ENCODING_DXT3``             ``BlpImagePlugin.AlphaEncoding.DXT3``
``BlpImagePlugin.BLP_ALPHA_ENCODING_DXT5``             ``BlpImagePlugin.AlphaEncoding.DXT5``
``FtexImagePlugin.FORMAT_DXT1``                        ``FtexImagePlugin.Format.DXT1``
``FtexImagePlugin.FORMAT_UNCOMPRESSED``                ``FtexImagePlugin.Format.UNCOMPRESSED``
``PngImagePlugin.APNG_DISPOSE_OP_NONE``                ``PngImagePlugin.Disposal.OP_NONE``
``PngImagePlugin.APNG_DISPOSE_OP_BACKGROUND``          ``PngImagePlugin.Disposal.OP_BACKGROUND``
``PngImagePlugin.APNG_DISPOSE_OP_PREVIOUS``            ``PngImagePlugin.Disposal.OP_PREVIOUS``
``PngImagePlugin.APNG_BLEND_OP_SOURCE``                ``PngImagePlugin.Blend.OP_SOURCE``
``PngImagePlugin.APNG_BLEND_OP_OVER``                  ``PngImagePlugin.Blend.OP_OVER``
=====================================================  ============================================================

ImageShow.Viewer.show_file file argument
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The ``file`` argument in :py:meth:`~PIL.ImageShow.Viewer.show_file()` has been
deprecated and  will be removed in Pillow 10.0.0 (2023-07-01). It has been replaced by
``path``.

In effect, ``viewer.show_file("test.jpg")`` will continue to work unchanged.
``viewer.show_file(file="test.jpg")`` will raise a deprecation warning, and suggest
``viewer.show_file(path="test.jpg")`` instead.

FitsStubImagePlugin
~~~~~~~~~~~~~~~~~~~

.. deprecated:: 9.1.0

The stub image plugin ``FitsStubImagePlugin`` has been deprecated and will be removed in
Pillow 10.0.0 (2023-07-01). FITS images can be read without a handler through
:mod:`~PIL.FitsImagePlugin` instead.

API Additions
=============

Added get_photoshop_blocks() to parse Photoshop TIFF tag
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

:py:meth:`~PIL.TiffImagePlugin.TiffImageFile.get_photoshop_blocks` has been added, to
allow users to determine what Photoshop "Image Resource Blocks" are contained within an
image. The keys of the returned dictionary are the image resource IDs.

At present, the information within each block is merely returned as a dictionary with a
"data" entry. This will allow more useful information to be added in the future without
breaking backwards compatibility.

Added rawmode argument to Image.getpalette()
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

By default, :py:meth:`~PIL.Image.Image.getpalette` returns RGB data from the palette.
A ``rawmode`` argument has been added, to allow the mode to be chosen instead. ``None``
can be used to return data in the current mode of the palette.

Other Changes
=============

ImageShow temporary files on Unix
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

When calling :py:meth:`~PIL.Image.Image.show` or using :py:mod:`~PIL.ImageShow`,
a temporary file is created from the image. On Unix, Pillow will no longer delete these
files, and instead leave it to the operating system to do so.

Image._repr_pretty_
^^^^^^^^^^^^^^^^^^^

``im._repr_pretty_`` has been added to provide a representation of an image without the
identity of the object. This allows Jupyter to describe an image and have that
description stay the same on subsequent executions of the same code.