From 5df83a57ff0f8362fc1d66180f777d5d79672342 Mon Sep 17 00:00:00 2001
From: Andrew Murray <radarhere@users.noreply.github.com>
Date: Sun, 16 Jan 2022 11:38:34 +1100
Subject: [PATCH] Documented deprecation

---
 docs/deprecations.rst | 12 ++++++++++++
 src/PIL/ImageShow.py  | 21 ++++++++++++++++++---
 2 files changed, 30 insertions(+), 3 deletions(-)

diff --git a/docs/deprecations.rst b/docs/deprecations.rst
index ce30fdf3b..dbe65dda1 100644
--- a/docs/deprecations.rst
+++ b/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
 ----------------
 
diff --git a/src/PIL/ImageShow.py b/src/PIL/ImageShow.py
index 068b7f784..e437bbade 100644
--- a/src/PIL/ImageShow.py
+++ b/src/PIL/ImageShow.py
@@ -107,7 +107,12 @@ class Viewer:
         return self.show_file(self.save_image(image), **options)
 
     def show_file(self, path=None, **options):
-        """Display given file."""
+        """
+        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(
@@ -157,7 +162,12 @@ class MacViewer(Viewer):
         return command
 
     def show_file(self, path=None, **options):
-        """Display given file"""
+        """
+        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(
@@ -194,7 +204,12 @@ class UnixViewer(Viewer):
         return f"({command} {quote(file)}; rm -f {quote(file)})&"
 
     def show_file(self, path=None, **options):
-        """Display given file"""
+        """
+        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(