Merge branch 'main' into fromarray_mode

Author: radarhere

.ci/requirements-mypy.txt

@@ -1,4 +1,4 @@
-mypy==1.16.0
+mypy==1.16.1
 IceSpringPySideStubs-PyQt6
 IceSpringPySideStubs-PySide6
 ipython

.github/workflows/wheels-dependencies.sh

@@ -39,7 +39,7 @@ ARCHIVE_SDIR=pillow-depends-main
 # Package versions for fresh source builds
 FREETYPE_VERSION=2.13.3
 HARFBUZZ_VERSION=11.2.1
-LIBPNG_VERSION=1.6.48
+LIBPNG_VERSION=1.6.49
 JPEGTURBO_VERSION=3.1.1
 OPENJPEG_VERSION=2.5.3
 XZ_VERSION=5.8.1

Tests/test_file_blp.py

@@ -7,9 +7,8 @@
 from PIL import BlpImagePlugin, Image
 
 from .helper import (
-    assert_image_equal,
     assert_image_equal_tofile,
-    assert_image_similar,
+    assert_image_similar_tofile,
     hopper,
 )
 
@@ -52,18 +51,16 @@ def test_save(tmp_path: Path) -> None:
         im = hopper("P")
         im.save(f, blp_version=version)
 
-        with Image.open(f) as reloaded:
-            assert_image_equal(im.convert("RGB"), reloaded)
+        assert_image_equal_tofile(im.convert("RGB"), f)
 
         with Image.open("Tests/images/transparent.png") as im:
             f = tmp_path / "temp.blp"
             im.convert("P").save(f, blp_version=version)
 
-            with Image.open(f) as reloaded:
-                assert_image_similar(im, reloaded, 8)
+            assert_image_similar_tofile(im, f, 8)
 
     im = hopper()
-    with pytest.raises(ValueError):
+    with pytest.raises(ValueError, match="Unsupported BLP image mode"):
         im.save(f)
 
 

Tests/test_file_png.py

@@ -100,11 +100,11 @@ def test_sanity(self, tmp_path: Path) -> None:
             assert im.format == "PNG"
             assert im.get_format_mimetype() == "image/png"
 
-        for mode in ["1", "L", "P", "RGB", "I", "I;16", "I;16B"]:
+        for mode in ["1", "L", "P", "RGB", "I;16", "I;16B"]:
             im = hopper(mode)
             im.save(test_file)
             with Image.open(test_file) as reloaded:
-                if mode in ("I", "I;16B"):
+                if mode == "I;16B":
                     reloaded = reloaded.convert(mode)
                 assert_image_equal(reloaded, im)
 
@@ -801,6 +801,16 @@ def test_truncated_end_chunk(self, monkeypatch: pytest.MonkeyPatch) -> None:
         with Image.open("Tests/images/truncated_end_chunk.png") as im:
             assert_image_equal_tofile(im, "Tests/images/hopper.png")
 
+    def test_deprecation(self, tmp_path: Path) -> None:
+        test_file = tmp_path / "out.png"
+
+        im = hopper("I")
+        with pytest.warns(DeprecationWarning):
+            im.save(test_file)
+
+        with Image.open(test_file) as reloaded:
+            assert_image_equal(im, reloaded.convert("I"))
+
 
 @pytest.mark.skipif(is_win32(), reason="Requires Unix or macOS")
 @skip_unless_feature("zlib")

Tests/test_file_ppm.py

@@ -294,9 +294,10 @@ def test_header_token_too_long(tmp_path: Path, data: bytes) -> None:
     with open(path, "wb") as f:
         f.write(data)
 
-    with pytest.raises(ValueError, match="Token too long in file header: "):
+    with pytest.raises(ValueError) as e:
         with Image.open(path):
             pass
+    assert "Token too long in file header: " in repr(e)
 
 
 def test_truncated_file(tmp_path: Path) -> None:

Tests/test_file_qoi.py

@@ -1,10 +1,12 @@
 from __future__ import annotations
 
+from pathlib import Path
+
 import pytest
 
 from PIL import Image, QoiImagePlugin
 
-from .helper import assert_image_equal_tofile
+from .helper import assert_image_equal_tofile, hopper
 
 
 def test_sanity() -> None:
@@ -34,3 +36,22 @@ def test_op_index() -> None:
     # QOI_OP_INDEX as the first chunk
     with Image.open("Tests/images/op_index.qoi") as im:
         assert im.getpixel((0, 0)) == (0, 0, 0, 0)
+
+
+def test_save(tmp_path: Path) -> None:
+    f = tmp_path / "temp.qoi"
+
+    im = hopper()
+    im.save(f, colorspace="sRGB")
+
+    assert_image_equal_tofile(im, f)
+
+    for path in ("Tests/images/default_font.png", "Tests/images/pil123rgba.png"):
+        with Image.open(path) as im:
+            im.save(f)
+
+            assert_image_equal_tofile(im, f)
+
+    im = hopper("P")
+    with pytest.raises(ValueError, match="Unsupported QOI image mode"):
+        im.save(f)

docs/deprecations.rst

@@ -201,6 +201,20 @@ Image.fromarray mode parameter
 The ``mode`` parameter in :py:meth:`~PIL.Image.fromarray()` has been deprecated. The
 mode can be automatically determined from the object's shape and type instead.
 
+Saving I mode images as PNG
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. deprecated:: 11.3.0
+
+In order to fit the 32 bits of I mode images into PNG, when PNG images can only contain
+at most 16 bits for a channel, Pillow has been clipping the values. Rather than quietly
+changing the data, this is now deprecated. Instead, the image can be converted to
+another mode before saving::
+
+    from PIL import Image
+    im = Image.new("I", (1, 1))
+    im.convert("I;16").save("out.png")
+
 Removed features
 ----------------
 

docs/handbook/image-file-formats.rst

@@ -1082,6 +1082,26 @@ Pillow reads and writes PBM, PGM, PPM and PNM files containing ``1``, ``L``, ``I
 
 Since Pillow 9.2.0, "plain" (P1 to P3) formats can be read as well.
 
+QOI
+^^^
+
+.. versionadded:: 9.5.0
+
+Pillow reads and writes images in Quite OK Image format using a Python codec. If you
+wish to write code specifically for this format, :pypi:`qoi` is an alternative library
+that uses C to decode the image and interfaces with NumPy.
+
+.. _qoi-saving:
+
+Saving
+~~~~~~
+
+The :py:meth:`~PIL.Image.Image.save` method can take the following keyword arguments:
+
+**colorspace**
+    If set to "sRGB", the colorspace will be written as sRGB with linear alpha, instead
+    of all channels being linear.
+
 SGI
 ^^^
 
@@ -1578,15 +1598,6 @@ PSD
 
 Pillow identifies and reads PSD files written by Adobe Photoshop 2.5 and 3.0.
 
-QOI
-^^^
-
-.. versionadded:: 9.5.0
-
-Pillow reads images in Quite OK Image format using a Python decoder. If you wish to
-write code specifically for this format, :pypi:`qoi` is an alternative library that
-uses C to decode the image and interfaces with NumPy.
-
 SUN
 ^^^
 

docs/releasenotes/11.3.0.rst

@@ -29,6 +29,18 @@ Image.fromarray mode parameter
 The ``mode`` parameter in :py:meth:`~PIL.Image.fromarray()` has been deprecated. The
 mode can be automatically determined from the object's shape and type instead.
 
+Saving I mode images as PNG
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In order to fit the 32 bits of I mode images into PNG, when PNG images can only contain
+at most 16 bits for a channel, Pillow has been clipping the values. Rather than quietly
+changing the data, this is now deprecated. Instead, the image can be converted to
+another mode before saving::
+
+    from PIL import Image
+    im = Image.new("I", (1, 1))
+    im.convert("I;16").save("out.png")
+
 API changes
 ===========
 
@@ -48,6 +60,26 @@ TODO
 Other changes
 =============
 
+Added QOI saving
+^^^^^^^^^^^^^^^^
+
+Support has been added for saving QOI images. ``colorspace`` can be used to specify the
+colorspace as sRGB with linear alpha, e.g. ``im.save("out.qoi", colorspace="sRGB")``.
+By default, all channels will be linear.
+
+Support using more screenshot utilities with ImageGrab on Linux
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:py:meth:`~PIL.ImageGrab.grab` is now able to use GNOME Screenshot, grim or Spectacle
+on Linux in order to take a snapshot of the screen.
+
+Do not build against libavif < 1
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Pillow only supports libavif 1.0.0 or later. In order to prevent errors when building
+from source, if a user happens to have an earlier libavif on their system, Pillow will
+now ignore it.
+
 Python 3.14 beta
 ^^^^^^^^^^^^^^^^
 

src/PIL/PngImagePlugin.py

@@ -48,6 +48,7 @@
 from ._binary import o8
 from ._binary import o16be as o16
 from ._binary import o32be as o32
+from ._deprecate import deprecate
 from ._util import DeferredError
 
 TYPE_CHECKING = False
@@ -1368,6 +1369,8 @@ def _save(
     except KeyError as e:
         msg = f"cannot write mode {mode} as PNG"
         raise OSError(msg) from e
+    if outmode == "I":
+        deprecate("Saving I mode images as PNG", 13, stacklevel=4)
 
     #
     # write minimal PNG file