Deprecated FitsStubImagePlugin

Tests/test_file_fits.py

@@ -2,7 +2,7 @@ from io import BytesIO
 
 import pytest
 
-from PIL import FitsImagePlugin, Image
+from PIL import FitsImagePlugin, FitsStubImagePlugin, Image
 
 from .helper import assert_image_equal, hopper
 
@@ -43,3 +43,38 @@ def test_naxis_zero():
     with pytest.raises(ValueError):
         with Image.open("Tests/images/hopper_naxis_zero.fits"):
             pass
+
+
+def test_stub_deprecated():
+    class Handler:
+        opened = False
+        loaded = False
+
+        def open(self, im):
+            self.opened = True
+
+        def load(self, im):
+            self.loaded = True
+            return Image.new("RGB", (1, 1))
+
+    handler = Handler()
+    with pytest.warns(DeprecationWarning):
+        FitsStubImagePlugin.register_handler(handler)
+
+    with Image.open(TEST_FILE) as im:
+        assert im.format == "FITS"
+        assert im.size == (128, 128)
+        assert im.mode == "L"
+
+        assert handler.opened
+        assert not handler.loaded
+
+        im.load()
+        assert handler.loaded
+
+    FitsStubImagePlugin._handler = None
+    Image.register_open(
+        FitsImagePlugin.FitsImageFile.format,
+        FitsImagePlugin.FitsImageFile,
+        FitsImagePlugin._accept,
+    )

docs/deprecations.rst

@@ -66,6 +66,15 @@ In effect, ``viewer.show_file("test.jpg")`` will continue to work unchanged.
 ``viewer.show_file(file="test.jpg")`` will raise a deprecation warning, and suggest
 ``viewer.show_file(path="test.jpg")`` instead.
 
+FitsStubImagePlugin
+~~~~~~~~~~~~~~~~~~~
+
+.. deprecated:: 9.1.0
+
+The stub image plugin FitsStubImagePlugin has been deprecated and will be removed in
+Pillow 10.0.0 (2023-07-01). FITS images can be read without a handler through
+FitsImagePlugin instead.
+
 Removed features
 ----------------
 

docs/releasenotes/9.1.0.rst

@@ -31,6 +31,15 @@ In effect, ``viewer.show_file("test.jpg")`` will continue to work unchanged.
 ``viewer.show_file(file="test.jpg")`` will raise a deprecation warning, and suggest
 ``viewer.show_file(path="test.jpg")`` instead.
 
+FitsStubImagePlugin
+~~~~~~~~~~~~~~~~~~~
+
+.. deprecated:: 9.1.0
+
+The stub image plugin FitsStubImagePlugin has been deprecated and will be removed in
+Pillow 10.0.0 (2023-07-01). FITS images can be read without a handler through
+FitsImagePlugin instead.
+
 API Additions
 =============
 

src/PIL/FitsStubImagePlugin.py

@@ -0,0 +1,77 @@
+#
+# The Python Imaging Library
+# $Id$
+#
+# FITS stub adapter
+#
+# Copyright (c) 1998-2003 by Fredrik Lundh
+#
+# See the README file for information on usage and redistribution.
+#
+
+import warnings
+
+from . import FitsImagePlugin, Image, ImageFile
+
+_handler = None
+
+
+def register_handler(handler):
+    """
+    Install application-specific FITS image handler.
+
+    :param handler: Handler object.
+    """
+    global _handler
+    _handler = handler
+
+    warnings.warn(
+        "FitsStubImagePlugin is deprecated and will be removed in Pillow "
+        "10 (2023-07-01). FITS images can now be read without a handler through "
+        "FitsImagePlugin instead.",
+        DeprecationWarning,
+    )
+
+    # Override FitsImagePlugin with this handler
+    # for backwards compatibility
+    try:
+        Image.ID.remove(FITSStubImageFile.format)
+    except ValueError:
+        pass
+
+    Image.register_open(
+        FITSStubImageFile.format, FITSStubImageFile, FitsImagePlugin._accept
+    )
+
+
+class FITSStubImageFile(ImageFile.StubImageFile):
+
+    format = FitsImagePlugin.FitsImageFile.format
+    format_description = FitsImagePlugin.FitsImageFile.format_description
+
+    def _open(self):
+        offset = self.fp.tell()
+
+        im = FitsImagePlugin.FitsImageFile(self.fp)
+        self._size = im.size
+        self.mode = im.mode
+        self.tile = []
+
+        self.fp.seek(offset)
+
+        loader = self._load()
+        if loader:
+            loader.open(self)
+
+    def _load(self):
+        return _handler
+
+
+def _save(im, fp, filename):
+    raise OSError("FITS save handler not installed")
+
+
+# --------------------------------------------------------------------
+# Registry
+
+Image.register_save(FITSStubImageFile.format, _save)

src/PIL/__init__.py

@@ -31,6 +31,7 @@ _plugins = [
     "DdsImagePlugin",
     "EpsImagePlugin",
     "FitsImagePlugin",
+    "FitsStubImagePlugin",
     "FliImagePlugin",
     "FpxImagePlugin",
     "FtexImagePlugin",