Add deprecations helper

Tests/test_deprecate.py

@@ -0,0 +1,91 @@
+import pytest
+
+from PIL import _deprecate
+
+
+@pytest.mark.parametrize(
+    "version, expected",
+    [
+        (
+            10,
+            "Old thing is deprecated and will be removed in Pillow 10 "
+            r"\(2023-07-01\)\. Use new thing instead\.",
+        ),
+        (
+            None,
+            r"Old thing is deprecated and will be removed in a future version\. "
+            r"Use new thing instead\.",
+        ),
+    ],
+)
+def test_version(version, expected):
+    with pytest.warns(DeprecationWarning, match=expected):
+        _deprecate.deprecate("Old thing", version, "new thing")
+
+
+def test_unknown_version():
+    expected = r"Unknown removal version, update PIL\._deprecate\?"
+    with pytest.raises(ValueError, match=expected):
+        _deprecate.deprecate("Old thing", 12345, "new thing")
+
+
+@pytest.mark.parametrize(
+    "deprecated, plural, expected",
+    [
+        (
+            "Old thing",
+            False,
+            r"Old thing is deprecated and should be removed\.",
+        ),
+        (
+            "Old things",
+            True,
+            r"Old things are deprecated and should be removed\.",
+        ),
+    ],
+)
+def test_old_version(deprecated, plural, expected):
+    expected = r""
+    with pytest.raises(RuntimeError, match=expected):
+        _deprecate.deprecate(deprecated, 1, plural=plural)
+
+
+def test_plural():
+    expected = (
+        r"Old things are deprecated and will be removed in Pillow 10 \(2023-07-01\)\. "
+        r"Use new thing instead\."
+    )
+    with pytest.warns(DeprecationWarning, match=expected):
+        _deprecate.deprecate("Old things", 10, "new thing", plural=True)
+
+
+def test_replacement_and_action():
+    expected = "Use only one of 'replacement' and 'action'"
+    with pytest.raises(ValueError, match=expected):
+        _deprecate.deprecate(
+            "Old thing", 10, replacement="new thing", action="Upgrade to new thing"
+        )
+
+
+@pytest.mark.parametrize(
+    "action",
+    [
+        "Upgrade to new thing",
+        "Upgrade to new thing.",
+    ],
+)
+def test_action(action):
+    expected = (
+        r"Old thing is deprecated and will be removed in Pillow 10 \(2023-07-01\)\. "
+        r"Upgrade to new thing\."
+    )
+    with pytest.warns(DeprecationWarning, match=expected):
+        _deprecate.deprecate("Old thing", 10, action=action)
+
+
+def test_no_replacement_or_action():
+    expected = (
+        r"Old thing is deprecated and will be removed in Pillow 10 \(2023-07-01\)"
+    )
+    with pytest.warns(DeprecationWarning, match=expected):
+        _deprecate.deprecate("Old thing", 10)

docs/reference/internal_modules.rst

@@ -9,6 +9,14 @@ Internal Modules
     :undoc-members:
     :show-inheritance:
 
+:mod:`~PIL._deprecate` Module
+-----------------------------
+
+.. automodule:: PIL._deprecate
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 :mod:`~PIL._tkinter_finder` Module
 ----------------------------------
 

src/PIL/BlpImagePlugin.py

@@ -31,11 +31,11 @@
 
 import os
 import struct
-import warnings
 from enum import IntEnum
 from io import BytesIO
 
 from . import Image, ImageFile
+from ._deprecate import deprecate
 
 
 class Format(IntEnum):
@@ -55,7 +55,6 @@ class AlphaEncoding(IntEnum):
 
 
 def __getattr__(name):
-    deprecated = "deprecated and will be removed in Pillow 10 (2023-07-01). "
     for enum, prefix in {
         Format: "BLP_FORMAT_",
         Encoding: "BLP_ENCODING_",
@@ -64,19 +63,7 @@ def __getattr__(name):
         if name.startswith(prefix):
             name = name[len(prefix) :]
             if name in enum.__members__:
-                warnings.warn(
-                    prefix
-                    + name
-                    + " is "
-                    + deprecated
-                    + "Use "
-                    + enum.__name__
-                    + "."
-                    + name
-                    + " instead.",
-                    DeprecationWarning,
-                    stacklevel=2,
-                )
+                deprecate(f"{prefix}{name}", 10, f"{enum.__name__}.{name}")
                 return enum[name]
     raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
 

src/PIL/FitsStubImagePlugin.py

@@ -9,9 +9,8 @@
 # See the README file for information on usage and redistribution.
 #
 
-import warnings
-
 from . import FitsImagePlugin, Image, ImageFile
+from ._deprecate import deprecate
 
 _handler = None
 
@@ -25,11 +24,11 @@ def register_handler(handler):
     global _handler
     _handler = handler
 
-    warnings.warn(
-        "FitsStubImagePlugin is deprecated and will be removed in Pillow "
-        "10 (2023-07-01). FITS images can now be read without a handler through "
-        "FitsImagePlugin instead.",
-        DeprecationWarning,
+    deprecate(
+        "FitsStubImagePlugin",
+        10,
+        action="FITS images can now be read without "
+        "a handler through FitsImagePlugin instead",
     )
 
     # Override FitsImagePlugin with this handler

src/PIL/FtexImagePlugin.py

@@ -52,11 +52,11 @@
 """
 
 import struct
-import warnings
 from enum import IntEnum
 from io import BytesIO
 
 from . import Image, ImageFile
+from ._deprecate import deprecate
 
 MAGIC = b"FTEX"
 
@@ -67,24 +67,11 @@ class Format(IntEnum):
 
 
 def __getattr__(name):
-    deprecated = "deprecated and will be removed in Pillow 10 (2023-07-01). "
     for enum, prefix in {Format: "FORMAT_"}.items():
         if name.startswith(prefix):
             name = name[len(prefix) :]
             if name in enum.__members__:
-                warnings.warn(
-                    prefix
-                    + name
-                    + " is "
-                    + deprecated
-                    + "Use "
-                    + enum.__name__
-                    + "."
-                    + name
-                    + " instead.",
-                    DeprecationWarning,
-                    stacklevel=2,
-                )
+                deprecate(f"{prefix}{name}", 10, f"{enum.__name__}.{name}")
                 return enum[name]
     raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
 

src/PIL/Image.py

@@ -50,60 +50,29 @@
 # Use __version__ instead.
 from . import ImageMode, TiffTags, UnidentifiedImageError, __version__, _plugins
 from ._binary import i32le, o32be, o32le
+from ._deprecate import deprecate
 from ._util import deferred_error, isPath
 
 
 def __getattr__(name):
-    deprecated = "deprecated and will be removed in Pillow 10 (2023-07-01). "
     categories = {"NORMAL": 0, "SEQUENCE": 1, "CONTAINER": 2}
     if name in categories:
-        warnings.warn(
-            "Image categories are " + deprecated + "Use is_animated instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
+        deprecate("Image categories", 10, "is_animated", plural=True)
         return categories[name]
     elif name in ("NEAREST", "NONE"):
-        warnings.warn(
-            name
-            + " is "
-            + deprecated
-            + "Use Resampling.NEAREST or Dither.NONE instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
+        deprecate(name, 10, "Resampling.NEAREST or Dither.NONE")
         return 0
     old_resampling = {
         "LINEAR": "BILINEAR",
         "CUBIC": "BICUBIC",
         "ANTIALIAS": "LANCZOS",
     }
     if name in old_resampling:
-        warnings.warn(
-            name
-            + " is "
-            + deprecated
-            + "Use Resampling."
-            + old_resampling[name]
-            + " instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
+        deprecate(name, 10, f"Resampling.{old_resampling[name]}")
         return Resampling[old_resampling[name]]
     for enum in (Transpose, Transform, Resampling, Dither, Palette, Quantize):
         if name in enum.__members__:
-            warnings.warn(
-                name
-                + " is "
-                + deprecated
-                + "Use "
-                + enum.__name__
-                + "."
-                + name
-                + " instead.",
-                DeprecationWarning,
-                stacklevel=2,
-            )
+            deprecate(name, 10, f"{enum.__name__}.{name}")
             return enum[name]
     raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
 
@@ -538,12 +507,7 @@ def __init__(self):
 
     def __getattr__(self, name):
         if name == "category":
-            warnings.warn(
-                "Image categories are deprecated and will be removed in Pillow 10 "
-                "(2023-07-01). Use is_animated instead.",
-                DeprecationWarning,
-                stacklevel=2,
-            )
+            deprecate("Image categories", 10, "is_animated", plural=True)
             return self._category
         raise AttributeError(name)
 

src/PIL/ImageCms.py

@@ -16,11 +16,12 @@
 # below for the original description.
 
 import sys
-import warnings
 from enum import IntEnum
 
 from PIL import Image
 
+from ._deprecate import deprecate
+
 try:
     from PIL import _imagingcms
 except ImportError as ex:
@@ -117,24 +118,11 @@ class Direction(IntEnum):
 
 
 def __getattr__(name):
-    deprecated = "deprecated and will be removed in Pillow 10 (2023-07-01). "
     for enum, prefix in {Intent: "INTENT_", Direction: "DIRECTION_"}.items():
         if name.startswith(prefix):
             name = name[len(prefix) :]
             if name in enum.__members__:
-                warnings.warn(
-                    prefix
-                    + name
-                    + " is "
-                    + deprecated
-                    + "Use "
-                    + enum.__name__
-                    + "."
-                    + name
-                    + " instead.",
-                    DeprecationWarning,
-                    stacklevel=2,
-                )
+                deprecate(f"{prefix}{name}", 10, f"{enum.__name__}.{name}")
                 return enum[name]
     raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
 

src/PIL/ImageFont.py

@@ -33,6 +33,7 @@
 from io import BytesIO
 
 from . import Image
+from ._deprecate import deprecate
 from ._util import isDirectory, isPath
 
 
@@ -42,24 +43,11 @@ class Layout(IntEnum):
 
 
 def __getattr__(name):
-    deprecated = "deprecated and will be removed in Pillow 10 (2023-07-01). "
     for enum, prefix in {Layout: "LAYOUT_"}.items():
         if name.startswith(prefix):
             name = name[len(prefix) :]
             if name in enum.__members__:
-                warnings.warn(
-                    prefix
-                    + name
-                    + " is "
-                    + deprecated
-                    + "Use "
-                    + enum.__name__
-                    + "."
-                    + name
-                    + " instead.",
-                    DeprecationWarning,
-                    stacklevel=2,
-                )
+                deprecate(f"{prefix}{name}", 10, f"{enum.__name__}.{name}")
                 return enum[name]
     raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
 
@@ -196,8 +184,6 @@ def __init__(self, font=None, size=10, index=0, encoding="", layout_engine=None)
             if core.HAVE_RAQM:
                 layout_engine = Layout.RAQM
         elif layout_engine == Layout.RAQM and not core.HAVE_RAQM:
-            import warnings
-
             warnings.warn(
                 "Raqm layout was requested, but Raqm is not available. "
                 "Falling back to basic layout."