Deprecate raise_oserror() for removal in Pillow 12

It's only useful if the caller has an IMAGING_CODEC_* error code, which
are only produced by codec decode() methods and are automatically
translated by ImageFile.

Co-authored-by: Andrew Murray <radarhere@users.noreply.github.com>

Tests/test_imagefile.py

@@ -115,8 +115,9 @@ class TestImageFile:
         assert_image_equal(im1, im2)
 
     def test_raise_oserror(self):
-        with pytest.raises(OSError):
+        with pytest.warns(DeprecationWarning):
-            ImageFile.raise_oserror(1)
+            with pytest.raises(OSError):
+                ImageFile.raise_oserror(1)
 
     def test_raise_typeerror(self):
         with pytest.raises(TypeError):

docs/deprecations.rst

@@ -34,6 +34,16 @@ Since Pillow's C API is now faster than PyAccess on PyPy,
 ``Image.USE_CFFI_ACCESS``, for switching from the C API to PyAccess, is
 similarly deprecated.
 
+ImageFile.raise_oserror
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. deprecated:: 10.2.0
+
+``ImageFile.raise_oserror()`` has been deprecated and will be removed in Pillow
+12.0.0 (2025-10-15). The function is undocumented and is only useful for translating
+error codes returned by a codec's ``decode()`` method, which ImageFile already does
+automatically.
+
 Removed features
 ----------------
 

docs/releasenotes/10.2.0.rst

@@ -12,6 +12,14 @@ TODO
 Deprecations
 ============
 
+ImageFile.raise_oserror
+^^^^^^^^^^^^^^^^^^^^^^^
+
+``ImageFile.raise_oserror()`` has been deprecated and will be removed in Pillow
+12.0.0 (2025-10-15). The function is undocumented and is only useful for translating
+error codes returned by a codec's ``decode()`` method, which ImageFile already does
+automatically.
+
 TODO
 ^^^^
 

src/PIL/ImageFile.py

@@ -35,6 +35,7 @@ import sys
 from typing import NamedTuple
 
 from . import Image
+from ._deprecate import deprecate
 from ._util import is_path
 
 MAXBLOCK = 65536
@@ -75,6 +76,12 @@ def _get_oserror(error, *, encoder):
 
 
 def raise_oserror(error):
+    deprecate(
+        "raise_oserror",
+        12,
+        action="It is only useful for translating error codes returned by a codec's "
+        "decode() method, which ImageFile already does automatically.",
+    )
     raise _get_oserror(error, encoder=False)
 
 
@@ -298,7 +305,7 @@ class ImageFile(Image.Image):
 
         if not self.map and not LOAD_TRUNCATED_IMAGES and err_code < 0:
             # still raised if decoder fails to return anything
-            raise_oserror(err_code)
+            raise _get_oserror(err_code, encoder=False)
 
         return Image.Image.load(self)
 
@@ -425,7 +432,7 @@ class Parser:
                 if e < 0:
                     # decoding error
                     self.image = None
-                    raise_oserror(e)
+                    raise _get_oserror(e, encoder=False)
                 else:
                     # end of image
                     return

src/PIL/_deprecate.py

@@ -47,6 +47,8 @@ def deprecate(
         raise RuntimeError(msg)
     elif when == 11:
         removed = "Pillow 11 (2024-10-15)"
+    elif when == 12:
+        removed = "Pillow 12 (2025-10-15)"
     else:
         msg = f"Unknown removal version: {when}. Update {__name__}?"
         raise ValueError(msg)