Repository: python-pillow/Pillow

Issue:
"box" parameter of PIL.ImageTk.PhotoImage.paste method appears to be dysfunctional
The "**box**" 4-tuple parameter of the **PIL.ImageTk.PhotoImage.paste** method is intended to allow a PIL Image to be pasted onto a Tkinter compatible PhotoImage within the specified box coordinates, but "box" appears to be dysfunctional, and I can't see anything in the source code of the method to implement its function. Smaller images pasted to larger images appear top-left and ignore any "box" value.

The documentation detailing the "box" parameter is here:
https://pillow.readthedocs.io/en/stable/reference/ImageTk.html#PIL.ImageTk.PhotoImage.paste

The source code of the paste method includes "box" as a parameter and has a docstring for it:
https://github.com/python-pillow/Pillow/blob/main/src/PIL/ImageTk.py#L178

Test code. A smaller blue box pasted into a larger yellow box always appears top-left and ignores the paste coordinates:

```python
import tkinter as tk
from PIL import Image, ImageTk
root = tk.Tk()
pil_img1 = Image.new("RGB",(400, 200), "yellow")
tk_img1 = ImageTk.PhotoImage(pil_img1)
tk.Label(root, image=tk_img1).pack()
pil_img2 = Image.new("RGB",(200, 100), "blue")
tk_img1.paste(pil_img2, box=(100, 50, 200, 150))
root.mainloop()
```

Tested with    Windows 10,   Python 3.10.4, Pillow 9.0.1
and with       Ubuntu 21.10, Python 3.9.7,  Pillow 8.1.2



Discussion:
Investigating, the `box` parameter is unused, and this has been the case since the PIL fork.
Experimenting with [our call to Tk](https://github.com/python-pillow/Pillow/blob/a6efaa1ae1d0bc83bf1cbbe7170f7734a7f4203d/src/Tk/tkImaging.c#L143-L151) and your code, I don't think Tk actually provides a simple way to do this.

We could add this functionality at the Python level - by creating a larger RGBA image, pasting the incoming image into that, and then applying it onto the Tk image. But then again, so could you as the user.

Would you like us to implement this feature, or is it easier for us to deprecate and eventually remove the `box` parameter?
Myself, I did find another way to do what I wanted. That code for creating a Tcl command looks complicated, so if that's non-trivial to adapt, then I'm OK with not adding to it. Remove the feature from the documentation and have the docstring say that it's unused?

Resolving patch:
diff --git a/src/PIL/ImageTk.py b/src/PIL/ImageTk.py
--- a/src/PIL/ImageTk.py
+++ b/src/PIL/ImageTk.py
@@ -26,6 +26,7 @@
 #
 
 import tkinter
+import warnings
 from io import BytesIO
 
 from . import Image
@@ -183,11 +184,15 @@ def paste(self, im, box=None):
         :param im: A PIL image. The size must match the target region.  If the
                    mode does not match, the image is converted to the mode of
                    the bitmap image.
-        :param box: A 4-tuple defining the left, upper, right, and lower pixel
-                    coordinate. See :ref:`coordinate-system`. If None is given
-                    instead of a tuple, all of the image is assumed.
         """
 
+        if box is not None:
+            warnings.warn(
+                "The box parameter is deprecated and will be removed in Pillow 10 "
+                "(2023-07-01).",
+                DeprecationWarning,
+            )
+
         # convert to blittable
         im.load()
         image = im.im


Test patch:
diff --git a/Tests/test_imagetk.py b/Tests/test_imagetk.py
--- a/Tests/test_imagetk.py
+++ b/Tests/test_imagetk.py
@@ -80,6 +80,13 @@ def test_photoimage_blank():
         assert_image_equal(reloaded.convert(mode), im)
 
 
+def test_box_deprecation():
+    im = hopper()
+    im_tk = ImageTk.PhotoImage(im)
+    with pytest.warns(DeprecationWarning):
+        im_tk.paste(im, (0, 0, 128, 128))
+
+
 def test_bitmapimage():
     im = hopper("1")