Merge pull request #7702 from nulano/deprecate-cms-constants

python-pillow · Jan 11, 2024 · 5baace9 · 5baace9
2 parents d7874e8 + 5347b47
commit 5baace9
Show file tree

Hide file tree

Showing 9 changed files with 123 additions and 17 deletions.
diff --git a/Tests/test_imagecms.py b/Tests/test_imagecms.py
@@ -49,8 +49,8 @@ def skip_missing():
 def test_sanity():
     # basic smoke test.
     # this mostly follows the cms_test outline.
-
-    v = ImageCms.versions()  # should return four strings
+    with pytest.warns(DeprecationWarning):
+        v = ImageCms.versions()  # should return four strings
     assert v[0] == "1.0.0 pil"
     assert list(map(type, v)) == [str, str, str, str]
 
@@ -637,3 +637,12 @@ def test_rgb_lab(mode):
     im = Image.new("LAB", (1, 1), (255, 0, 0))
     converted_im = im.convert(mode)
     assert converted_im.getpixel((0, 0))[:3] == (0, 255, 255)
+
+
+def test_deprecation() -> None:
+    with pytest.warns(DeprecationWarning):
+        assert ImageCms.DESCRIPTION.strip().startswith("pyCMS")
+    with pytest.warns(DeprecationWarning):
+        assert ImageCms.VERSION == "1.0.0 pil"
+    with pytest.warns(DeprecationWarning):
+        assert isinstance(ImageCms.FLAGS, dict)
diff --git a/docs/deprecations.rst b/docs/deprecations.rst
@@ -55,6 +55,43 @@ The functions ``IptcImageFile.dump`` and ``IptcImageFile.i``, and the constant
 for internal use, so there is no replacement. They can each be replaced
 by a single line of code using builtin functions in Python.
 
+ImageCms constants and versions() function
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. deprecated:: 10.3.0
+
+A number of constants and a function in :py:mod:`.ImageCms` have been deprecated.
+This includes a table of flags based on LittleCMS version 1 which has been
+replaced with a new class :py:class:`.ImageCms.Flags` based on LittleCMS 2 flags.
+
+============================================  ====================================================
+Deprecated                                    Use instead
+============================================  ====================================================
+``ImageCms.DESCRIPTION``                      No replacement
+``ImageCms.VERSION``                          ``PIL.__version__``
+``ImageCms.FLAGS["MATRIXINPUT"]``             :py:attr:`.ImageCms.Flags.CLUT_POST_LINEARIZATION`
+``ImageCms.FLAGS["MATRIXOUTPUT"]``            :py:attr:`.ImageCms.Flags.FORCE_CLUT`
+``ImageCms.FLAGS["MATRIXONLY"]``              No replacement
+``ImageCms.FLAGS["NOWHITEONWHITEFIXUP"]``     :py:attr:`.ImageCms.Flags.NOWHITEONWHITEFIXUP`
+``ImageCms.FLAGS["NOPRELINEARIZATION"]``      :py:attr:`.ImageCms.Flags.CLUT_PRE_LINEARIZATION`
+``ImageCms.FLAGS["GUESSDEVICECLASS"]``        :py:attr:`.ImageCms.Flags.GUESSDEVICECLASS`
+``ImageCms.FLAGS["NOTCACHE"]``                :py:attr:`.ImageCms.Flags.NOCACHE`
+``ImageCms.FLAGS["NOTPRECALC"]``              :py:attr:`.ImageCms.Flags.NOOPTIMIZE`
+``ImageCms.FLAGS["NULLTRANSFORM"]``           :py:attr:`.ImageCms.Flags.NULLTRANSFORM`
+``ImageCms.FLAGS["HIGHRESPRECALC"]``          :py:attr:`.ImageCms.Flags.HIGHRESPRECALC`
+``ImageCms.FLAGS["LOWRESPRECALC"]``           :py:attr:`.ImageCms.Flags.LOWRESPRECALC`
+``ImageCms.FLAGS["GAMUTCHECK"]``              :py:attr:`.ImageCms.Flags.GAMUTCHECK`
+``ImageCms.FLAGS["WHITEBLACKCOMPENSATION"]``  :py:attr:`.ImageCms.Flags.BLACKPOINTCOMPENSATION`
+``ImageCms.FLAGS["BLACKPOINTCOMPENSATION"]``  :py:attr:`.ImageCms.Flags.BLACKPOINTCOMPENSATION`
+``ImageCms.FLAGS["SOFTPROOFING"]``            :py:attr:`.ImageCms.Flags.SOFTPROOFING`
+``ImageCms.FLAGS["PRESERVEBLACK"]``           :py:attr:`.ImageCms.Flags.NONEGATIVES`
+``ImageCms.FLAGS["NODEFAULTRESOURCEDEF"]``    :py:attr:`.ImageCms.Flags.NODEFAULTRESOURCEDEF`
+``ImageCms.FLAGS["GRIDPOINTS"]``              :py:attr:`.ImageCms.Flags.GRIDPOINTS()`
+``ImageCms.versions()``                       :py:func:`PIL.features.version_module` with
+                                              ``feature="littlecms2"``, :py:data:`sys.version` or
+                                              :py:data:`sys.version_info`, and ``PIL.__version__``
+============================================  ====================================================
+
 Removed features
 ----------------
 
@@ -118,7 +155,7 @@ Constants
 .. versionremoved:: 10.0.0
 
 A number of constants have been removed.
-Instead, ``enum.IntEnum`` classes have been added.
+Instead, :py:class:`enum.IntEnum` classes have been added.
 
 .. note::
 

diff --git a/docs/reference/ExifTags.rst b/docs/reference/ExifTags.rst
@@ -4,8 +4,9 @@
 :py:mod:`~PIL.ExifTags` Module
 ==============================
 
-The :py:mod:`~PIL.ExifTags` module exposes several ``enum.IntEnum`` classes
-which provide constants and clear-text names for various well-known EXIF tags.
+The :py:mod:`~PIL.ExifTags` module exposes several :py:class:`enum.IntEnum`
+classes which provide constants and clear-text names for various well-known
+EXIF tags.
 
 .. py:data:: Base
 

diff --git a/docs/reference/ImageCms.rst b/docs/reference/ImageCms.rst
@@ -24,14 +24,17 @@ Constants
     :members:
     :member-order: bysource
     :undoc-members:
+    :show-inheritance:
 .. autoclass:: Direction
     :members:
     :member-order: bysource
     :undoc-members:
+    :show-inheritance:
 .. autoclass:: Flags
     :members:
     :member-order: bysource
     :undoc-members:
+    :show-inheritance:
 
 Functions
 ---------

diff --git a/docs/releasenotes/10.0.0.rst b/docs/releasenotes/10.0.0.rst
@@ -43,7 +43,7 @@ Constants
 ^^^^^^^^^
 
 A number of constants have been removed.
-Instead, ``enum.IntEnum`` classes have been added.
+Instead, :py:class:`enum.IntEnum` classes have been added.
 
 =====================================================  ============================================================
 Removed                                                Use instead

diff --git a/docs/releasenotes/10.3.0.rst b/docs/releasenotes/10.3.0.rst
@@ -10,10 +10,40 @@ TODO
 Deprecations
 ============
 
-TODO
-^^^^
-
-TODO
+ImageCms constants and versions() function
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A number of constants and a function in :py:mod:`.ImageCms` have been deprecated.
+This includes a table of flags based on LittleCMS version 1 which has been replaced
+with a new class :py:class:`.ImageCms.Flags` based on LittleCMS 2 flags.
+
+============================================  ====================================================
+Deprecated                                    Use instead
+============================================  ====================================================
+``ImageCms.DESCRIPTION``                      No replacement
+``ImageCms.VERSION``                          ``PIL.__version__``
+``ImageCms.FLAGS["MATRIXINPUT"]``             :py:attr:`.ImageCms.Flags.CLUT_POST_LINEARIZATION`
+``ImageCms.FLAGS["MATRIXOUTPUT"]``            :py:attr:`.ImageCms.Flags.FORCE_CLUT`
+``ImageCms.FLAGS["MATRIXONLY"]``              No replacement
+``ImageCms.FLAGS["NOWHITEONWHITEFIXUP"]``     :py:attr:`.ImageCms.Flags.NOWHITEONWHITEFIXUP`
+``ImageCms.FLAGS["NOPRELINEARIZATION"]``      :py:attr:`.ImageCms.Flags.CLUT_PRE_LINEARIZATION`
+``ImageCms.FLAGS["GUESSDEVICECLASS"]``        :py:attr:`.ImageCms.Flags.GUESSDEVICECLASS`
+``ImageCms.FLAGS["NOTCACHE"]``                :py:attr:`.ImageCms.Flags.NOCACHE`
+``ImageCms.FLAGS["NOTPRECALC"]``              :py:attr:`.ImageCms.Flags.NOOPTIMIZE`
+``ImageCms.FLAGS["NULLTRANSFORM"]``           :py:attr:`.ImageCms.Flags.NULLTRANSFORM`
+``ImageCms.FLAGS["HIGHRESPRECALC"]``          :py:attr:`.ImageCms.Flags.HIGHRESPRECALC`
+``ImageCms.FLAGS["LOWRESPRECALC"]``           :py:attr:`.ImageCms.Flags.LOWRESPRECALC`
+``ImageCms.FLAGS["GAMUTCHECK"]``              :py:attr:`.ImageCms.Flags.GAMUTCHECK`
+``ImageCms.FLAGS["WHITEBLACKCOMPENSATION"]``  :py:attr:`.ImageCms.Flags.BLACKPOINTCOMPENSATION`
+``ImageCms.FLAGS["BLACKPOINTCOMPENSATION"]``  :py:attr:`.ImageCms.Flags.BLACKPOINTCOMPENSATION`
+``ImageCms.FLAGS["SOFTPROOFING"]``            :py:attr:`.ImageCms.Flags.SOFTPROOFING`
+``ImageCms.FLAGS["PRESERVEBLACK"]``           :py:attr:`.ImageCms.Flags.NONEGATIVES`
+``ImageCms.FLAGS["NODEFAULTRESOURCEDEF"]``    :py:attr:`.ImageCms.Flags.NODEFAULTRESOURCEDEF`
+``ImageCms.FLAGS["GRIDPOINTS"]``              :py:attr:`.ImageCms.Flags.GRIDPOINTS()`
+``ImageCms.versions()``                       :py:func:`PIL.features.version_module` with
+                                              ``feature="littlecms2"``, :py:data:`sys.version` or
+                                              :py:data:`sys.version_info`, and ``PIL.__version__``
+============================================  ====================================================
 
 API Changes
 ===========

diff --git a/docs/releasenotes/9.1.0.rst b/docs/releasenotes/9.1.0.rst
@@ -51,7 +51,7 @@ Constants
 ^^^^^^^^^
 
 A number of constants have been deprecated and will be removed in Pillow 10.0.0
-(2023-07-01). Instead, ``enum.IntEnum`` classes have been added.
+(2023-07-01). Instead, :py:class:`enum.IntEnum` classes have been added.
 
 .. note::
 

diff --git a/docs/releasenotes/9.3.0.rst b/docs/releasenotes/9.3.0.rst
@@ -33,8 +33,9 @@ Added ExifTags enums
 ^^^^^^^^^^^^^^^^^^^^
 
 The data from :py:data:`~PIL.ExifTags.TAGS` and
-:py:data:`~PIL.ExifTags.GPSTAGS` is now also exposed as ``enum.IntEnum``
-classes: :py:data:`~PIL.ExifTags.Base` and :py:data:`~PIL.ExifTags.GPS`.
+:py:data:`~PIL.ExifTags.GPSTAGS` is now also exposed as
+:py:class:`enum.IntEnum` classes: :py:data:`~PIL.ExifTags.Base` and
+:py:data:`~PIL.ExifTags.GPS`.
 
 
 Security

diff --git a/src/PIL/ImageCms.py b/src/PIL/ImageCms.py
@@ -4,6 +4,9 @@
 # Optional color management support, based on Kevin Cazabon's PyCMS
 # library.
 
+# Originally released under LGPL.  Graciously donated to PIL in
+# March 2009, for distribution under the standard PIL license
+
 # History:
 
 # 2009-03-08 fl   Added to PIL.
@@ -20,8 +23,10 @@
 import sys
 from enum import IntEnum, IntFlag
 from functools import reduce
+from typing import Any
 
 from . import Image
+from ._deprecate import deprecate
 
 try:
     from . import _imagingcms
@@ -32,7 +37,7 @@
 
     _imagingcms = DeferredError.new(ex)
 
-DESCRIPTION = """
+_DESCRIPTION = """
 pyCMS
 
     a Python / PIL interface to the littleCMS ICC Color Management System
@@ -95,7 +100,22 @@
 
 """
 
-VERSION = "1.0.0 pil"
+_VERSION = "1.0.0 pil"
+
+
+def __getattr__(name: str) -> Any:
+    if name == "DESCRIPTION":
+        deprecate("PIL.ImageCms.DESCRIPTION", 12)
+        return _DESCRIPTION
+    elif name == "VERSION":
+        deprecate("PIL.ImageCms.VERSION", 12)
+        return _VERSION
+    elif name == "FLAGS":
+        deprecate("PIL.ImageCms.FLAGS", 12, "PIL.ImageCms.Flags")
+        return _FLAGS
+    msg = f"module '{__name__}' has no attribute '{name}'"
+    raise AttributeError(msg)
+
 
 # --------------------------------------------------------------------.
 
@@ -184,7 +204,7 @@ def GRIDPOINTS(n: int) -> Flags:
 _MAX_FLAG = reduce(operator.or_, Flags)
 
 
-FLAGS = {
+_FLAGS = {
     "MATRIXINPUT": 1,
     "MATRIXOUTPUT": 2,
     "MATRIXONLY": (1 | 2),
@@ -1064,4 +1084,9 @@ def versions():
     (pyCMS) Fetches versions.
     """
 
-    return VERSION, core.littlecms_version, sys.version.split()[0], Image.__version__
+    deprecate(
+        "PIL.ImageCms.versions()",
+        12,
+        '(PIL.features.version("littlecms2"), sys.version, PIL.__version__)',
+    )
+    return _VERSION, core.littlecms_version, sys.version.split()[0], Image.__version__