Merge pull request #5959 from radarhere/imageshow_file

Tests/test_imageshow.py

@@ -79,3 +79,18 @@ def test_ipythonviewer():
 
     im = hopper()
     assert test_viewer.show(im) == 1
+
+
+@pytest.mark.skipif(
+    not on_ci() or is_win32(),
+    reason="Only run on CIs; hangs on Windows CIs",
+)
+def test_file_deprecated():
+    for viewer in ImageShow._viewers:
+        with pytest.warns(DeprecationWarning):
+            try:
+                viewer.show_file(file="test.jpg")
+            except NotImplementedError:
+                pass
+        with pytest.raises(TypeError):
+            viewer.show_file()

docs/deprecations.rst

@@ -53,6 +53,18 @@ Before Pillow 8.3.0, ``ImagePalette`` required palette data of particular length
 default, and the size parameter could be used to override that. Pillow 8.3.0 removed
 the default required length, also removing the need for the size parameter.
 
+ImageShow.Viewer.show_file file argument
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. deprecated:: 9.1.0
+
+The ``file`` argument in :py:meth:`~PIL.ImageShow.Viewer.show_file()` has been
+deprecated, replaced by ``path``.
+
+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.
+
 Removed features
 ----------------
 

src/PIL/ImageShow.py

@@ -16,6 +16,7 @@ import shutil
 import subprocess
 import sys
 import tempfile
+import warnings
 from shlex import quote
 
 from PIL import Image
@@ -105,9 +106,24 @@ class Viewer:
         """Display the given image."""
         return self.show_file(self.save_image(image), **options)
 
-    def show_file(self, file, **options):
-        """Display the given file."""
-        os.system(self.get_command(file, **options))
+    def show_file(self, path=None, **options):
+        """
+        Display given file.
+
+        Before Pillow 9.1.0, the first argument was ``file``. This is now deprecated,
+        and ``path`` should be used instead.
+        """
+        if path is None:
+            if "file" in options:
+                warnings.warn(
+                    "The 'file' argument is deprecated and will be removed in Pillow "
+                    "10 (2023-07-01). Use 'path' instead.",
+                    DeprecationWarning,
+                )
+                path = options.pop("file")
+            else:
+                raise TypeError("Missing required argument: 'path'")
+        os.system(self.get_command(path, **options))
         return 1
 
 
@@ -145,18 +161,33 @@ class MacViewer(Viewer):
         command = f"({command} {quote(file)}; sleep 20; rm -f {quote(file)})&"
         return command
 
-    def show_file(self, file, **options):
-        """Display given file"""
-        fd, path = tempfile.mkstemp()
+    def show_file(self, path=None, **options):
+        """
+        Display given file.
+
+        Before Pillow 9.1.0, the first argument was ``file``. This is now deprecated,
+        and ``path`` should be used instead.
+        """
+        if path is None:
+            if "file" in options:
+                warnings.warn(
+                    "The 'file' argument is deprecated and will be removed in Pillow "
+                    "10 (2023-07-01). Use 'path' instead.",
+                    DeprecationWarning,
+                )
+                path = options.pop("file")
+            else:
+                raise TypeError("Missing required argument: 'path'")
+        fd, temp_path = tempfile.mkstemp()
         with os.fdopen(fd, "w") as f:
-            f.write(file)
-        with open(path) as f:
+            f.write(path)
+        with open(temp_path) as f:
             subprocess.Popen(
                 ["im=$(cat); open -a Preview.app $im; sleep 20; rm -f $im"],
                 shell=True,
                 stdin=f,
             )
-        os.remove(path)
+        os.remove(temp_path)
         return 1
 
 
@@ -172,17 +203,32 @@ class UnixViewer(Viewer):
         command = self.get_command_ex(file, **options)[0]
         return f"({command} {quote(file)}; rm -f {quote(file)})&"
 
-    def show_file(self, file, **options):
-        """Display given file"""
-        fd, path = tempfile.mkstemp()
+    def show_file(self, path=None, **options):
+        """
+        Display given file.
+
+        Before Pillow 9.1.0, the first argument was ``file``. This is now deprecated,
+        and ``path`` should be used instead.
+        """
+        if path is None:
+            if "file" in options:
+                warnings.warn(
+                    "The 'file' argument is deprecated and will be removed in Pillow "
+                    "10 (2023-07-01). Use 'path' instead.",
+                    DeprecationWarning,
+                )
+                path = options.pop("file")
+            else:
+                raise TypeError("Missing required argument: 'path'")
+        fd, temp_path = tempfile.mkstemp()
         with os.fdopen(fd, "w") as f:
-            f.write(file)
-        with open(path) as f:
-            command = self.get_command_ex(file, **options)[0]
+            f.write(path)
+        with open(temp_path) as f:
+            command = self.get_command_ex(path, **options)[0]
             subprocess.Popen(
                 ["im=$(cat);" + command + " $im; rm -f $im"], shell=True, stdin=f
             )
-        os.remove(path)
+        os.remove(temp_path)
         return 1