Merge pull request #4646 from nulano/show-command

Deprecate Image.show(command="...")

Tests/test_image.py

@@ -664,6 +664,18 @@ def test_overrun(self):
             except OSError as e:
                 assert str(e) == "buffer overrun when reading image file"
 
+    def test_show_deprecation(self, monkeypatch):
+        monkeypatch.setattr(Image, "_show", lambda *args, **kwargs: None)
+
+        im = Image.new("RGB", (50, 50), "white")
+
+        with pytest.warns(None) as raised:
+            im.show()
+        assert not raised
+
+        with pytest.warns(DeprecationWarning):
+            im.show(command="mock")
+
 
 class MockEncoder:
     pass

docs/deprecations.rst

@@ -12,6 +12,14 @@ Deprecated features
 Below are features which are considered deprecated. Where appropriate,
 a ``DeprecationWarning`` is issued.
 
+Image.show command parameter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. deprecated:: 7.2.0
+
+The ``command`` parameter was deprecated and will be removed in a future release.
+Use a subclass of ``ImageShow.Viewer`` instead.
+
 ImageFile.raise_ioerror
 ~~~~~~~~~~~~~~~~~~~~~~~
 

src/PIL/Image.py

@@ -2181,8 +2181,10 @@ def seek(self, frame):
 
     def show(self, title=None, command=None):
         """
-        Displays this image. This method is mainly intended for
-        debugging purposes.
+        Displays this image. This method is mainly intended for debugging purposes.
+
+        This method calls :py:func:`PIL.ImageShow.show` internally. You can use
+        :py:func:`PIL.ImageShow.register` to override its default behaviour.
 
         The image is first saved to a temporary file. By default, it will be in
         PNG format.
@@ -2194,11 +2196,16 @@ def show(self, title=None, command=None):
 
         On Windows, the image is opened with the standard PNG display utility.
 
-        :param title: Optional title to use for the image window,
-           where possible.
-        :param command: command used to show the image
+        :param title: Optional title to use for the image window, where possible.
         """
 
+        if command is not None:
+            warnings.warn(
+                "The command parameter is deprecated and will be removed in a future "
+                "release. Use a subclass of ImageShow.Viewer instead.",
+                DeprecationWarning,
+            )
+
         _show(self, title=title, command=command)
 
     def split(self):