From 3bb5cf49016007d2b1cfb7812aa880140b0fbff1 Mon Sep 17 00:00:00 2001
From: Benjamin Gilbert <bgilbert@backtick.net>
Date: Sun, 10 Dec 2023 15:32:27 -0600
Subject: [PATCH] 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 functions internal to Pillow.
---
 Tests/test_imagefile.py      |  5 +++--
 docs/deprecations.rst        |  9 +++++++++
 docs/releasenotes/10.2.0.rst |  7 +++++++
 src/PIL/ImageFile.py         | 11 +++++++++--
 src/PIL/_deprecate.py        |  2 ++
 5 files changed, 30 insertions(+), 4 deletions(-)

diff --git a/Tests/test_imagefile.py b/Tests/test_imagefile.py
index ff75b8c2a69..2389c471748 100644
--- a/Tests/test_imagefile.py
+++ b/Tests/test_imagefile.py
@@ -115,8 +115,9 @@ def test_safeblock(self):
         assert_image_equal(im1, im2)
 
     def test_raise_oserror(self):
-        with pytest.raises(OSError):
-            ImageFile.raise_oserror(1)
+        with pytest.warns(DeprecationWarning):
+            with pytest.raises(OSError):
+                ImageFile.raise_oserror(1)
 
     def test_raise_typeerror(self):
         with pytest.raises(TypeError):
diff --git a/docs/deprecations.rst b/docs/deprecations.rst
index b4fbb8d5053..971ba0cb277 100644
--- a/docs/deprecations.rst
+++ b/docs/deprecations.rst
@@ -34,6 +34,15 @@ 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-01-02). The function is undocumented and is only useful for
+translating error codes returned by internal codec APIs.
+
 Removed features
 ----------------
 
diff --git a/docs/releasenotes/10.2.0.rst b/docs/releasenotes/10.2.0.rst
index bdcd93f69cb..02a78cd96c8 100644
--- a/docs/releasenotes/10.2.0.rst
+++ b/docs/releasenotes/10.2.0.rst
@@ -12,6 +12,13 @@ TODO
 Deprecations
 ============
 
+ImageFile.raise_oserror
+^^^^^^^^^^^^^^^^^^^^^^^
+
+``ImageFile.raise_oserror`` has been deprecated and will be removed in Pillow
+12.0.0. The function is undocumented and is only useful for translating error
+codes returned by internal codec APIs.
+
 TODO
 ^^^^
 
diff --git a/src/PIL/ImageFile.py b/src/PIL/ImageFile.py
index e413579b00f..82110bc3142 100644
--- a/src/PIL/ImageFile.py
+++ b/src/PIL/ImageFile.py
@@ -35,6 +35,7 @@
 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=False):
 
 
 def raise_oserror(error):
+    deprecate(
+        "raise_oserror",
+        12,
+        action="It is only useful for translating error codes from internal "
+        "Pillow APIs.",
+    )
     raise _get_oserror(error, encoder=False)
 
 
@@ -298,7 +305,7 @@ def load(self):
 
         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 @@ def feed(self, data):
                 if e < 0:
                     # decoding error
                     self.image = None
-                    raise_oserror(e)
+                    raise _get_oserror(e, encoder=False)
                 else:
                     # end of image
                     return
diff --git a/src/PIL/_deprecate.py b/src/PIL/_deprecate.py
index 2f2a3df13e3..5c22e87e4d2 100644
--- a/src/PIL/_deprecate.py
+++ b/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-01-02)"
     else:
         msg = f"Unknown removal version: {when}. Update {__name__}?"
         raise ValueError(msg)