Re-add deprecated PILLOW_VERSION to give projects more time to upgrade

Tests/test_image.py

@@ -3,6 +3,7 @@
 import shutil
 import tempfile
 
+import PIL
 import pytest
 from PIL import Image, ImageDraw, ImagePalette, UnidentifiedImageError
 
@@ -608,6 +609,34 @@ def act(fp):
 
             assert not fp.closed
 
+    @pytest.mark.parametrize(
+        "test_module", [PIL, Image],
+    )
+    def test_pillow_version(self, test_module):
+        with pytest.warns(DeprecationWarning):
+            assert test_module.PILLOW_VERSION == PIL.__version__
+
+        with pytest.warns(DeprecationWarning):
+            str(test_module.PILLOW_VERSION)
+
+        with pytest.warns(DeprecationWarning):
+            assert int(test_module.PILLOW_VERSION[0]) >= 7
+
+        with pytest.warns(DeprecationWarning):
+            assert test_module.PILLOW_VERSION < "9.9.0"
+
+        with pytest.warns(DeprecationWarning):
+            assert test_module.PILLOW_VERSION <= "9.9.0"
+
+        with pytest.warns(DeprecationWarning):
+            assert test_module.PILLOW_VERSION != "7.0.0"
+
+        with pytest.warns(DeprecationWarning):
+            assert test_module.PILLOW_VERSION >= "7.0.0"
+
+        with pytest.warns(DeprecationWarning):
+            assert test_module.PILLOW_VERSION > "7.0.0"
+
     def test_overrun(self):
         for file in [
             "fli_overrun.bin",

docs/deprecations.rst

@@ -12,6 +12,17 @@ Deprecated features
 Below are features which are considered deprecated. Where appropriate,
 a ``DeprecationWarning`` is issued.
 
+PILLOW_VERSION constant
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. deprecated:: 5.2.0
+
+``PILLOW_VERSION`` has been deprecated and will be removed in a future release. Use
+``__version__`` instead.
+
+It was initially removed in Pillow 7.0.0, but brought back in 7.1.0 to give projects
+more time to upgrade.
+
 ImageCms.CmsProfile attributes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -69,13 +80,6 @@ Use instead:
     with Image.open("hopper.png") as im:
         im.save("out.jpg")
 
-PILLOW_VERSION constant
-~~~~~~~~~~~~~~~~~~~~~~~
-
-*Removed in version 7.0.0.*
-
-``PILLOW_VERSION`` has been removed. Use ``__version__`` instead.
-
 PIL.*ImagePlugin.__version__ attributes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/releasenotes/7.1.0.rst

@@ -21,17 +21,27 @@ been resolved.
 API Additions
 =============
 
+New channel operations
+^^^^^^^^^^^^^^^^^^^^^^
+
+Three new channel operations have been added: :py:meth:`~PIL.ImageChops.soft_light`,
+:py:meth:`~PIL.ImageChops.hard_light` and :py:meth:`~PIL.ImageChops.overlay`.
+
+PILLOW_VERSION constant
+^^^^^^^^^^^^^^^^^^^^^^^
+
+``PILLOW_VERSION`` has been re-added but is deprecated and will be removed in a future
+release. Use ``__version__`` instead.
+
+It was initially removed in Pillow 7.0.0, but brought back in 7.1.0 to give projects
+more time to upgrade.
+
 Reading JPEG comments
 ^^^^^^^^^^^^^^^^^^^^^
 
 When opening a JPEG image, the comment may now be read into
 :py:attr:`~PIL.Image.Image.info`.
 
-New channel operations
-^^^^^^^^^^^^^^^^^^^^^^
-
-Three new channel operations have been added: :py:meth:`~PIL.ImageChops.soft_light`,
-:py:meth:`~PIL.ImageChops.hard_light` and :py:meth:`~PIL.ImageChops.overlay`.
 
 Other Changes
 =============

src/PIL/Image.py

@@ -39,12 +39,36 @@
 from pathlib import Path
 
 # VERSION was removed in Pillow 6.0.0.
-# PILLOW_VERSION was removed in Pillow 7.0.0.
+# PILLOW_VERSION is deprecated and will be removed in a future release.
 # Use __version__ instead.
-from . import ImageMode, TiffTags, UnidentifiedImageError, __version__, _plugins
+from . import (
+    ImageMode,
+    TiffTags,
+    UnidentifiedImageError,
+    __version__,
+    _plugins,
+    _raise_version_warning,
+)
 from ._binary import i8, i32le
 from ._util import deferred_error, isPath
 
+if sys.version_info >= (3, 7):
+
+    def __getattr__(name):
+        if name == "PILLOW_VERSION":
+            _raise_version_warning()
+            return __version__
+        raise AttributeError("module '{}' has no attribute '{}'".format(__name__, name))
+
+
+else:
+
+    from . import PILLOW_VERSION
+
+    # Silence warning
+    assert PILLOW_VERSION
+
+
 logger = logging.getLogger(__name__)
 
 

src/PIL/__init__.py

@@ -13,13 +13,72 @@
 ;-)
 """
 
+import sys
+import warnings
+
 from . import _version
 
 # VERSION was removed in Pillow 6.0.0.
-# PILLOW_VERSION was removed in Pillow 7.0.0.
-# Use __version__ instead.
 __version__ = _version.__version__
 
+
+# PILLOW_VERSION is deprecated and will be removed in a future release.
+# Use __version__ instead.
+def _raise_version_warning():
+    warnings.warn(
+        "PILLOW_VERSION is deprecated and will be removed in a future release. "
+        "Use __version__ instead.",
+        DeprecationWarning,
+        stacklevel=3,
+    )
+
+
+if sys.version_info >= (3, 7):
+
+    def __getattr__(name):
+        if name == "PILLOW_VERSION":
+            _raise_version_warning()
+            return __version__
+        raise AttributeError("module '{}' has no attribute '{}'".format(__name__, name))
+
+
+else:
+
+    class _Deprecated_Version(str):
+        def __str__(self):
+            _raise_version_warning()
+            return super().__str__()
+
+        def __getitem__(self, key):
+            _raise_version_warning()
+            return super().__getitem__(key)
+
+        def __eq__(self, other):
+            _raise_version_warning()
+            return super().__eq__(other)
+
+        def __ne__(self, other):
+            _raise_version_warning()
+            return super().__ne__(other)
+
+        def __gt__(self, other):
+            _raise_version_warning()
+            return super().__gt__(other)
+
+        def __lt__(self, other):
+            _raise_version_warning()
+            return super().__lt__(other)
+
+        def __ge__(self, other):
+            _raise_version_warning()
+            return super().__gt__(other)
+
+        def __le__(self, other):
+            _raise_version_warning()
+            return super().__lt__(other)
+
+    PILLOW_VERSION = _Deprecated_Version(__version__)
+
 del _version