Use ImagingCore.ptr instead of ImagingCore.id

Tests/test_image_getim.py

@@ -1,11 +1,19 @@
 from __future__ import annotations
 
+import pytest
+
 from .helper import hopper
 
 
 def test_sanity() -> None:
     im = hopper()
-    type_repr = repr(type(im.getim()))
 
+    type_repr = repr(type(im.getim()))
     assert "PyCapsule" in type_repr
-    assert isinstance(im.im.id, int)
+
+    with pytest.warns(DeprecationWarning):
+        assert isinstance(im.im.id, int)
+
+    with pytest.warns(DeprecationWarning):
+        ptrs = dict(im.im.unsafe_ptrs)
+    assert all(k in ptrs for k in ["image8", "image32", "image"])

Tests/test_imagemorph.py

@@ -328,13 +328,13 @@ def test_wrong_mode() -> None:
     iml = Image.new("L", (10, 10))
 
     with pytest.raises(RuntimeError):
-        _imagingmorph.apply(bytes(lut), imrgb.im.id, iml.im.id)
+        _imagingmorph.apply(bytes(lut), imrgb.im.ptr, iml.im.ptr)
 
     with pytest.raises(RuntimeError):
-        _imagingmorph.apply(bytes(lut), iml.im.id, imrgb.im.id)
+        _imagingmorph.apply(bytes(lut), iml.im.ptr, imrgb.im.ptr)
 
     with pytest.raises(RuntimeError):
-        _imagingmorph.match(bytes(lut), imrgb.im.id)
+        _imagingmorph.match(bytes(lut), imrgb.im.ptr)
 
     # Should not raise
-    _imagingmorph.match(bytes(lut), iml.im.id)
+    _imagingmorph.match(bytes(lut), iml.im.ptr)

docs/deprecations.rst

@@ -136,6 +136,16 @@ Specific WebP Feature Checks
 ``True`` if the WebP module is installed, until they are removed in Pillow
 12.0.0 (2025-10-15).
 
+Get Internal Pointers to Objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. deprecated:: 11.0.0
+
+``Image.core.ImagingCore.id`` and ``Image.core.ImagingCore.unsafe_ptrs`` have been
+deprecated and will be removed in Pillow 12 (2025-10-15). They were used for obtaining
+raw pointers to ``ImagingCore`` internals. To interact with C code, you can use
+``Image.core.ImagingCore.ptr``, which returns a ``Capsule`` object.
+
 Removed features
 ----------------
 

src/PIL/Image.py

@@ -224,12 +224,7 @@ class Quantize(IntEnum):
     from IPython.lib.pretty import PrettyPrinter
 
     from . import ImageFile, ImageFilter, ImagePalette, ImageQt, TiffImagePlugin
-    from ._typing import NumpyArray, StrOrBytesPath, TypeGuard
-
-    if sys.version_info >= (3, 13):
-        from types import CapsuleType
-    else:
-        CapsuleType = object
+    from ._typing import CapsuleType, NumpyArray, StrOrBytesPath, TypeGuard
 ID: list[str] = []
 OPEN: dict[
     str,

src/PIL/ImageCms.py

@@ -352,7 +352,7 @@ def apply(self, im: Image.Image, imOut: Image.Image | None = None) -> Image.Imag
         im.load()
         if imOut is None:
             imOut = Image.new(self.output_mode, im.size, None)
-        self.transform.apply(im.im.id, imOut.im.id)
+        self.transform.apply(im.im.ptr, imOut.im.ptr)
         imOut.info["icc_profile"] = self.output_profile.tobytes()
         return imOut
 
@@ -361,7 +361,7 @@ def apply_in_place(self, im: Image.Image) -> Image.Image:
         if im.mode != self.output_mode:
             msg = "mode mismatch"
             raise ValueError(msg)  # wrong output mode
-        self.transform.apply(im.im.id, im.im.id)
+        self.transform.apply(im.im.ptr, im.im.ptr)
         im.info["icc_profile"] = self.output_profile.tobytes()
         return im
 

src/PIL/ImageMath.py

@@ -65,7 +65,7 @@ def apply(
             except AttributeError as e:
                 msg = f"bad operand type for '{op}'"
                 raise TypeError(msg) from e
-            _imagingmath.unop(op, out.im.id, im_1.im.id)
+            _imagingmath.unop(op, out.im.ptr, im_1.im.ptr)
         else:
             # binary operation
             im_2 = self.__fixup(im2)
@@ -93,7 +93,7 @@ def apply(
             except AttributeError as e:
                 msg = f"bad operand type for '{op}'"
                 raise TypeError(msg) from e
-            _imagingmath.binop(op, out.im.id, im_1.im.id, im_2.im.id)
+            _imagingmath.binop(op, out.im.ptr, im_1.im.ptr, im_2.im.ptr)
         return _Operand(out)
 
     # unary operators

src/PIL/ImageMorph.py

@@ -213,7 +213,7 @@ def apply(self, image: Image.Image) -> tuple[int, Image.Image]:
             msg = "Image mode must be L"
             raise ValueError(msg)
         outimage = Image.new(image.mode, image.size, None)
-        count = _imagingmorph.apply(bytes(self.lut), image.im.id, outimage.im.id)
+        count = _imagingmorph.apply(bytes(self.lut), image.im.ptr, outimage.im.ptr)
         return count, outimage
 
     def match(self, image: Image.Image) -> list[tuple[int, int]]:
@@ -229,7 +229,7 @@ def match(self, image: Image.Image) -> list[tuple[int, int]]:
         if image.mode != "L":
             msg = "Image mode must be L"
             raise ValueError(msg)
-        return _imagingmorph.match(bytes(self.lut), image.im.id)
+        return _imagingmorph.match(bytes(self.lut), image.im.ptr)
 
     def get_on_pixels(self, image: Image.Image) -> list[tuple[int, int]]:
         """Get a list of all turned on pixels in a binary image
@@ -240,7 +240,7 @@ def get_on_pixels(self, image: Image.Image) -> list[tuple[int, int]]:
         if image.mode != "L":
             msg = "Image mode must be L"
             raise ValueError(msg)
-        return _imagingmorph.get_on_pixels(image.im.id)
+        return _imagingmorph.get_on_pixels(image.im.ptr)
 
     def load_lut(self, filename: str) -> None:
         """Load an operator from an mrl file"""

src/PIL/ImageTk.py

@@ -32,23 +32,12 @@
 
 from . import Image, ImageFile
 
+if TYPE_CHECKING:
+    from ._typing import CapsuleType
+
 # --------------------------------------------------------------------
 # Check for Tkinter interface hooks
 
-_pilbitmap_ok = None
-
-
-def _pilbitmap_check() -> int:
-    global _pilbitmap_ok
-    if _pilbitmap_ok is None:
-        try:
-            im = Image.new("1", (1, 1))
-            tkinter.BitmapImage(data=f"PIL:{im.im.id}")
-            _pilbitmap_ok = 1
-        except tkinter.TclError:
-            _pilbitmap_ok = 0
-    return _pilbitmap_ok
-
 
 def _get_image_from_kw(kw: dict[str, Any]) -> ImageFile.ImageFile | None:
     source = None
@@ -62,18 +51,18 @@ def _get_image_from_kw(kw: dict[str, Any]) -> ImageFile.ImageFile | None:
 
 
 def _pyimagingtkcall(
-    command: str, photo: PhotoImage | tkinter.PhotoImage, id: int
+    command: str, photo: PhotoImage | tkinter.PhotoImage, ptr: CapsuleType
 ) -> None:
     tk = photo.tk
     try:
-        tk.call(command, photo, id)
+        tk.call(command, photo, repr(ptr))
     except tkinter.TclError:
         # activate Tkinter hook
         # may raise an error if it cannot attach to Tkinter
         from . import _imagingtk
 
         _imagingtk.tkinit(tk.interpaddr())
-        tk.call(command, photo, id)
+        tk.call(command, photo, repr(ptr))
 
 
 # --------------------------------------------------------------------
@@ -142,6 +131,8 @@ def __init__(
             self.paste(image)
 
     def __del__(self) -> None:
+        if not hasattr(self, "__photo"):
+            return
         name = self.__photo.name
         self.__photo.name = None
         try:
@@ -190,10 +181,10 @@ def paste(self, im: Image.Image) -> None:
         if image.isblock() and im.mode == self.__mode:
             block = image
         else:
-            block = image.new_block(self.__mode, im.size)
+            block = Image.core.new_block(self.__mode, im.size)
             image.convert2(block, image)  # convert directly between buffers
 
-        _pyimagingtkcall("PyImagingPhoto", self.__photo, block.id)
+        _pyimagingtkcall("PyImagingPhoto", self.__photo, block.ptr)
 
 
 # --------------------------------------------------------------------
@@ -225,17 +216,11 @@ def __init__(self, image: Image.Image | None = None, **kw: Any) -> None:
         self.__mode = image.mode
         self.__size = image.size
 
-        if _pilbitmap_check():
-            # fast way (requires the pilbitmap booster patch)
-            image.load()
-            kw["data"] = f"PIL:{image.im.id}"
-            self.__im = image  # must keep a reference
-        else:
-            # slow but safe way
-            kw["data"] = image.tobitmap()
-        self.__photo = tkinter.BitmapImage(**kw)
+        self.__photo = tkinter.BitmapImage(data=image.tobitmap(), **kw)
 
     def __del__(self) -> None:
+        if not hasattr(self, "__photo"):
+            return
         name = self.__photo.name
         self.__photo.name = None
         try:
@@ -273,9 +258,8 @@ def __str__(self) -> str:
 def getimage(photo: PhotoImage) -> Image.Image:
     """Copies the contents of a PhotoImage to a PIL image memory."""
     im = Image.new("RGBA", (photo.width(), photo.height()))
-    block = im.im
 
-    _pyimagingtkcall("PyImagingPhotoGet", photo, block.id)
+    _pyimagingtkcall("PyImagingPhotoGet", photo, im.im.ptr)
 
     return im
 

src/PIL/_typing.py

@@ -15,6 +15,11 @@
     except (ImportError, AttributeError):
         pass
 
+if sys.version_info >= (3, 13):
+    from types import CapsuleType
+else:
+    CapsuleType = object
+
 if sys.version_info >= (3, 12):
     from collections.abc import Buffer
 else:

src/Tk/tkImaging.c

@@ -56,19 +56,34 @@
 
 static Imaging
 ImagingFind(const char *name) {
-    Py_ssize_t id;
+    PyObject *capsule;
+    int direct_pointer = 0;
+    const char *expected = "capsule object \"" IMAGING_MAGIC "\" at 0x";
 
-    /* FIXME: use CObject instead? */
-#if defined(_WIN64)
-    id = _atoi64(name);
-#else
-    id = atol(name);
-#endif
-    if (!id) {
+    if (name[0] == '<') {
+        name++;
+    } else {
+        // Special case for PyPy, where the string representation of a Capsule
+        // refers directly to the pointer itself, not to the PyCapsule object.
+        direct_pointer = 1;
+    }
+
+    if (strncmp(name, expected, strlen(expected))) {
+        return NULL;
+    }
+
+    capsule = (PyObject *)strtoull(name + strlen(expected), NULL, 16);
+
+    if (direct_pointer) {
+        return (Imaging)capsule;
+    }
+
+    if (!PyCapsule_IsValid(capsule, IMAGING_MAGIC)) {
+        PyErr_Format(PyExc_TypeError, "Expected '%s' Capsule", IMAGING_MAGIC);
         return NULL;
     }
 
-    return (Imaging)id;
+    return (Imaging)PyCapsule_GetPointer(capsule, IMAGING_MAGIC);
 }
 
 static int

src/_imaging.c

@@ -3674,15 +3674,12 @@
     /* Unsharpmask extension */
     {"gaussian_blur", (PyCFunction)_gaussian_blur, METH_VARARGS},
     {"unsharp_mask", (PyCFunction)_unsharp_mask, METH_VARARGS},
-
     {"box_blur", (PyCFunction)_box_blur, METH_VARARGS},
 
     /* Special effects */
     {"effect_spread", (PyCFunction)_effect_spread, METH_VARARGS},
 
     /* Misc. */
-    {"new_block", (PyCFunction)_new_block, METH_VARARGS},
-
     {"save_ppm", (PyCFunction)_save_ppm, METH_VARARGS},
 
     {NULL, NULL} /* sentinel */
@@ -3707,6 +3704,13 @@
 
 static PyObject *
 _getattr_id(ImagingObject *self, void *closure) {
+    if (PyErr_WarnEx(
+            PyExc_DeprecationWarning,
+            "id property is deprecated and will be removed in Pillow 12.0",
+            1
+        ) < 0) {
+        return NULL;
+    }
     return PyLong_FromSsize_t((Py_ssize_t)self->image);
 }
 
@@ -3717,6 +3721,13 @@
 
 static PyObject *
 _getattr_unsafe_ptrs(ImagingObject *self, void *closure) {
+    if (PyErr_WarnEx(
+            PyExc_DeprecationWarning,
+            "unsafe_ptrs property is deprecated and will be removed in Pillow 12.0",
+            1
+        ) < 0) {
+        return NULL;
+    }
     return Py_BuildValue(
         "(sn)(sn)(sn)",
         "image8",
@@ -4198,6 +4209,7 @@
     {"blend", (PyCFunction)_blend, METH_VARARGS},
     {"fill", (PyCFunction)_fill, METH_VARARGS},
     {"new", (PyCFunction)_new, METH_VARARGS},
+    {"new_block", (PyCFunction)_new_block, METH_VARARGS},
     {"merge", (PyCFunction)_merge, METH_VARARGS},
 
     /* Functions */

src/_imagingcms.c

@@ -531,23 +531,24 @@
 
 static PyObject *
 cms_transform_apply(CmsTransformObject *self, PyObject *args) {
-    Py_ssize_t idIn;
-    Py_ssize_t idOut;
+    PyObject *i0, *i1;
     Imaging im;
     Imaging imOut;
 
-    int result;
-
-    if (!PyArg_ParseTuple(args, "nn:apply", &idIn, &idOut)) {
+    if (!PyArg_ParseTuple(args, "OO:apply", &i0, &i1)) {
         return NULL;
     }
 
-    im = (Imaging)idIn;
-    imOut = (Imaging)idOut;
+    if (!PyCapsule_IsValid(i0, IMAGING_MAGIC) ||
+        !PyCapsule_IsValid(i1, IMAGING_MAGIC)) {
+        PyErr_Format(PyExc_TypeError, "Expected '%s' Capsule", IMAGING_MAGIC);
+        return NULL;
+    }
 
-    result = pyCMSdoTransform(im, imOut, self->transform);
+    im = (Imaging)PyCapsule_GetPointer(i0, IMAGING_MAGIC);
+    imOut = (Imaging)PyCapsule_GetPointer(i1, IMAGING_MAGIC);
 
-    return Py_BuildValue("i", result);
+    return Py_BuildValue("i", pyCMSdoTransform(im, imOut, self->transform));
 }
 
 /* -------------------------------------------------------------------- */