Deprecate putpixel value lists

Tests/test_image_access.py

@@ -116,6 +116,11 @@ def test_numpy(self) -> None:
         assert numpy is not None
         assert px[numpy.int32(1), numpy.int32(2)] == (18, 20, 59)
 
+    def test_deprecation(self) -> None:
+        im = Image.new("PA", (1, 1))
+        with pytest.warns(DeprecationWarning, match="'value' lists"):
+            im.putpixel((0, 0), [0, 0, 0])  # type: ignore[arg-type]
+
 
 class TestImageGetPixel:
     @staticmethod

docs/deprecations.rst

@@ -83,6 +83,14 @@ Image getdata()
 identical, except that it returns a tuple of pixel values, instead of an internal
 Pillow data type.
 
+Image.putpixel 'value' lists
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. deprecated:: 12.3.0
+
+Passing lists to the ``value`` parameter of :py:meth:`~PIL.Image.Image.putpixel` have
+been deprecated. Use tuples instead.
+
 Removed features
 ----------------
 

docs/releasenotes/12.3.0.rst

@@ -25,10 +25,13 @@ TODO
 Deprecations
 ============
 
-TODO
-^^^^
+Image.putpixel 'value' lists
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-TODO
+.. deprecated:: 12.3.0
+
+Passing lists to the ``value`` parameter of :py:meth:`~PIL.Image.Image.putpixel` have
+been deprecated. Use tuples instead.
 
 API changes
 ===========

src/PIL/Image.py

@@ -2173,9 +2173,7 @@ def putpalette(
             self.palette.mode = "RGB"
         self.load()  # install new palette
 
-    def putpixel(
-        self, xy: tuple[int, int], value: float | tuple[int, ...] | list[int]
-    ) -> None:
+    def putpixel(self, xy: tuple[int, int], value: float | tuple[int, ...]) -> None:
         """
         Modifies the pixel at the given position. The color is given as
         a single numerical value for single-band images, and a tuple for
@@ -2204,6 +2202,9 @@ def putpixel(
             and isinstance(value, (list, tuple))
             and len(value) in [3, 4]
         ):
+            if isinstance(value, list):  # type: ignore[unreachable]
+                deprecate("'value' lists", 14, "tuples", plural=True)  # type: ignore[unreachable]
+
             # RGB or RGBA value for a P or PA image
             if self.mode == "PA":
                 alpha = value[3] if len(value) == 4 else 255