Deprecate setting size to (width, height, scale)

Tests/test_file_icns.py

@@ -87,7 +87,8 @@ def test_sizes() -> None:
         for w, h, r in im.info["sizes"]:
             wr = w * r
             hr = h * r
-            im.size = (w, h, r)
+            with pytest.warns(DeprecationWarning):
+                im.size = (w, h, r)
             im.load()
             assert im.mode == "RGBA"
             assert im.size == (wr, hr)

docs/deprecations.rst

@@ -109,6 +109,14 @@ ImageDraw.getdraw hints parameter
 
 The ``hints`` parameter in :py:meth:`~PIL.ImageDraw.getdraw()` has been deprecated.
 
+ICNS (width, height, scale) sizes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. deprecated:: 11.0.0
+
+Setting an ICNS image size to ``(width, height, scale)`` before loading has been
+deprecated. Instead, ``load(scale)`` can be used.
+
 ImageMath.lambda_eval and ImageMath.unsafe_eval options parameter
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

docs/handbook/image-file-formats.rst

@@ -324,12 +324,7 @@ sets the following :py:attr:`~PIL.Image.Image.info` property:
 **sizes**
     A list of supported sizes found in this icon file; these are a
     3-tuple, ``(width, height, scale)``, where ``scale`` is 2 for a retina
-    icon and 1 for a standard icon.  You *are* permitted to use this 3-tuple
+    icon and 1 for a standard icon.
-    format for the :py:attr:`~PIL.Image.Image.size` property if you set it
-    before calling :py:meth:`~PIL.Image.Image.load`; after loading, the size
-    will be reset to a 2-tuple containing pixel dimensions (so, e.g. if you
-    ask for ``(512, 512, 2)``, the final value of
-    :py:attr:`~PIL.Image.Image.size` will be ``(1024, 1024)``).
 
 .. _icns-loading:
 

docs/releasenotes/11.0.0.rst

@@ -43,9 +43,20 @@ similarly removed.
 Deprecations
 ============
 
+
+ICNS (width, height, scale) sizes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. deprecated:: 11.0.0
+
+Setting an ICNS image size to ``(width, height, scale)`` before loading has been
+deprecated. Instead, ``load(scale)`` can be used.
+
 ImageMath.lambda_eval and ImageMath.unsafe_eval options parameter
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+.. deprecated:: 11.0.0
+
 The ``options`` parameter in :py:meth:`~PIL.ImageMath.lambda_eval()` and
 :py:meth:`~PIL.ImageMath.unsafe_eval()` has been deprecated. One or more
 keyword arguments can be used instead.
@@ -61,6 +72,8 @@ have been deprecated, and will be removed in Pillow 12 (2025-10-15).
 Specific WebP Feature Checks
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+.. deprecated:: 11.0.0
+
 ``features.check("transp_webp")``, ``features.check("webp_mux")`` and
 ``features.check("webp_anim")`` are now deprecated. They will always return
 ``True`` if the WebP module is installed, until they are removed in Pillow

src/PIL/IcnsImagePlugin.py

@@ -25,6 +25,7 @@ import sys
 from typing import IO
 
 from . import Image, ImageFile, PngImagePlugin, features
+from ._deprecate import deprecate
 
 enable_jpeg2k = features.check_codec("jpg_2000")
 if enable_jpeg2k:
@@ -275,15 +276,16 @@ class IcnsImageFile(ImageFile.ImageFile):
             self.best_size[1] * self.best_size[2],
         )
 
-    @property
+    @property  # type: ignore[override]
-    def size(self):
+    def size(self) -> tuple[int, int] | tuple[int, int, int]:
         return self._size
 
     @size.setter
-    def size(self, value) -> None:
+    def size(self, value: tuple[int, int] | tuple[int, int, int]) -> None:
         if len(value) == 3:
+            deprecate("Setting size to (width, height, scale)", 12, "load(scale)")
             if value in self.info["sizes"]:
-                self._size = value
+                self._size = value  # type: ignore[assignment]
                 return
         else:
             # Check that a matching size exists,