Skip to content

Commit

Permalink
Deprecate raise_oserror() for removal in Pillow 12
Browse files Browse the repository at this point in the history
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>
  • Loading branch information
bgilbert and radarhere committed Dec 13, 2023
1 parent ec17dc1 commit e1fb1ab
Show file tree
Hide file tree
Showing 5 changed files with 32 additions and 4 deletions.
5 changes: 3 additions & 2 deletions Tests/test_imagefile.py
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down
10 changes: 10 additions & 0 deletions docs/deprecations.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
----------------

Expand Down
8 changes: 8 additions & 0 deletions docs/releasenotes/10.2.0.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
^^^^

Expand Down
11 changes: 9 additions & 2 deletions src/PIL/ImageFile.py
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@
from typing import NamedTuple

from . import Image
from ._deprecate import deprecate
from ._util import is_path

MAXBLOCK = 65536
Expand Down Expand Up @@ -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)


Expand Down Expand Up @@ -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)

Expand Down Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions src/PIL/_deprecate.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down

0 comments on commit e1fb1ab

Please sign in to comment.