Deprecated show_file "file" argument in favour of "path"

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 subprocess
 import sys
 import tempfile
+import warnings
 from shlex import quote
 
 from PIL import Image
@@ -105,9 +106,24 @@ def show_image(self, image, **options):
         """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 @@ def get_command(self, file, **options):
         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 @@ def get_command(self, file, **options):
         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