Merge pull request #5351 from radarhere/categories

Tests/test_image.py

@@ -1,6 +1,7 @@
 import io
 import os
 import shutil
+import sys
 import tempfile
 
 import pytest
@@ -769,6 +770,20 @@ class TestImage:
         reloaded_exif.load(exif.tobytes())
         assert reloaded_exif.get_ifd(0x8769) == exif.get_ifd(0x8769)
 
+    @pytest.mark.skipif(
+        sys.version_info < (3, 7), reason="Python 3.7 or greater required"
+    )
+    def test_categories_deprecation(self):
+        with pytest.warns(DeprecationWarning):
+            assert hopper().category == 0
+
+        with pytest.warns(DeprecationWarning):
+            assert Image.NORMAL == 0
+        with pytest.warns(DeprecationWarning):
+            assert Image.SEQUENCE == 1
+        with pytest.warns(DeprecationWarning):
+            assert Image.CONTAINER == 2
+
     @pytest.mark.parametrize(
         "test_module",
         [PIL, Image],

docs/deprecations.rst

@@ -33,6 +33,18 @@ Tk/Tcl 8.4
 Support for Tk/Tcl 8.4 is deprecated and will be removed in Pillow 10.0.0 (2023-01-02),
 when Tk/Tcl 8.5 will be the minimum supported.
 
+Categories
+~~~~~~~~~~
+
+.. deprecated:: 8.2.0
+
+``im.category`` is deprecated and will be removed in Pillow 10.0.0 (2023-01-02),
+along with the related ``Image.NORMAL``, ``Image.SEQUENCE`` and
+``Image.CONTAINER`` attributes.
+
+To determine if an image has multiple frames or not,
+``getattr(im, "is_animated", False)`` can be used instead.
+
 Image.show command parameter
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/reference/Image.rst

@@ -503,10 +503,3 @@ Used to specify the quantization method to use for the :meth:`~Image.quantize` m
 
     Check support using :py:func:`PIL.features.check_feature`
     with ``feature="libimagequant"``.
-
-.. comment: These are not referenced anywhere?
-    Categories
-    ^^^^^^^^^^
-    .. data:: NORMAL
-    .. data:: SEQUENCE
-    .. data:: CONTAINER

docs/releasenotes/8.2.0.rst

@@ -10,6 +10,16 @@ Tk/Tcl 8.4
 Support for Tk/Tcl 8.4 is deprecated and will be removed in Pillow 10.0.0 (2023-01-02),
 when Tk/Tcl 8.5 will be the minimum supported.
 
+Categories
+^^^^^^^^^^
+
+``im.category`` is deprecated and will be removed in Pillow 10.0.0 (2023-01-02),
+along with the related ``Image.NORMAL``, ``Image.SEQUENCE`` and
+``Image.CONTAINER`` attributes.
+
+To determine if an image has multiple frames or not,
+``getattr(im, "is_animated", False)`` can be used instead.
+
 API Changes
 ===========
 

src/PIL/Image.py

@@ -59,6 +59,16 @@ if sys.version_info >= (3, 7):
         if name == "PILLOW_VERSION":
             _raise_version_warning()
             return __version__
+        else:
+            categories = {"NORMAL": 0, "SEQUENCE": 1, "CONTAINER": 2}
+            if name in categories:
+                warnings.warn(
+                    "Image categories are deprecated and will be removed in Pillow 10 "
+                    "(2023-01-02). Use is_animated instead.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+                return categories[name]
         raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
 
 
@@ -69,6 +79,11 @@ else:
     # Silence warning
     assert PILLOW_VERSION
 
+    # categories
+    NORMAL = 0
+    SEQUENCE = 1
+    CONTAINER = 2
+
 
 logger = logging.getLogger(__name__)
 
@@ -187,11 +202,6 @@ MAXCOVERAGE = 1
 FASTOCTREE = 2
 LIBIMAGEQUANT = 3
 
-# categories
-NORMAL = 0
-SEQUENCE = 1
-CONTAINER = 2
-
 if hasattr(core, "DEFAULT_STRATEGY"):
     DEFAULT_STRATEGY = core.DEFAULT_STRATEGY
     FILTERED = core.FILTERED
@@ -535,11 +545,22 @@ class Image:
         self._size = (0, 0)
         self.palette = None
         self.info = {}
-        self.category = NORMAL
+        self._category = 0
         self.readonly = 0
         self.pyaccess = None
         self._exif = None
 
+    def __getattr__(self, name):
+        if name == "category":
+            warnings.warn(
+                "Image categories are deprecated and will be removed in Pillow 10 "
+                "(2023-01-02). Use is_animated instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            return self._category
+        raise AttributeError(name)
+
     @property
     def width(self):
         return self.size[0]
@@ -648,7 +669,7 @@ class Image:
             and self.mode == other.mode
             and self.size == other.size
             and self.info == other.info
-            and self.category == other.category
+            and self._category == other._category
             and self.readonly == other.readonly
             and self.getpalette() == other.getpalette()
             and self.tobytes() == other.tobytes()

src/PIL/MicImagePlugin.py

@@ -68,7 +68,7 @@ class MicImageFile(TiffImagePlugin.TiffImageFile):
         self.is_animated = self._n_frames > 1
 
         if len(self.images) > 1:
-            self.category = Image.CONTAINER
+            self._category = Image.CONTAINER
 
         self.seek(0)