Skip to content

Commit 5baace9

Browse files
hugovkhugovk
authored
Merge pull request #7702 from nulano/deprecate-cms-constants
2 parents d7874e8 + 5347b47 commit 5baace9

File tree

9 files changed

+123
-17
lines changed

9 files changed

+123
-17
lines changed

‎Tests/test_imagecms.py‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,8 +49,8 @@ def skip_missing():
4949
def test_sanity():
5050
# basic smoke test.
5151
# this mostly follows the cms_test outline.
52-
53-
v = ImageCms.versions() # should return four strings
52+
with pytest.warns(DeprecationWarning):
53+
v = ImageCms.versions() # should return four strings
5454
assert v[0] == "1.0.0 pil"
5555
assert list(map(type, v)) == [str, str, str, str]
5656

@@ -637,3 +637,12 @@ def test_rgb_lab(mode):
637637
im = Image.new("LAB", (1, 1), (255, 0, 0))
638638
converted_im = im.convert(mode)
639639
assert converted_im.getpixel((0, 0))[:3] == (0, 255, 255)
640+
641+
642+
def test_deprecation() -> None:
643+
with pytest.warns(DeprecationWarning):
644+
assert ImageCms.DESCRIPTION.strip().startswith("pyCMS")
645+
with pytest.warns(DeprecationWarning):
646+
assert ImageCms.VERSION == "1.0.0 pil"
647+
with pytest.warns(DeprecationWarning):
648+
assert isinstance(ImageCms.FLAGS, dict)

‎docs/deprecations.rst‎

Lines changed: 38 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,43 @@ The functions ``IptcImageFile.dump`` and ``IptcImageFile.i``, and the constant
5555
for internal use, so there is no replacement. They can each be replaced
5656
by a single line of code using builtin functions in Python.
5757

58+
ImageCms constants and versions() function
59+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
60+
61+
.. deprecated:: 10.3.0
62+
63+
A number of constants and a function in :py:mod:`.ImageCms` have been deprecated.
64+
This includes a table of flags based on LittleCMS version 1 which has been
65+
replaced with a new class :py:class:`.ImageCms.Flags` based on LittleCMS 2 flags.
66+
67+
============================================ ====================================================
68+
Deprecated Use instead
69+
============================================ ====================================================
70+
``ImageCms.DESCRIPTION`` No replacement
71+
``ImageCms.VERSION`` ``PIL.__version__``
72+
``ImageCms.FLAGS["MATRIXINPUT"]`` :py:attr:`.ImageCms.Flags.CLUT_POST_LINEARIZATION`
73+
``ImageCms.FLAGS["MATRIXOUTPUT"]`` :py:attr:`.ImageCms.Flags.FORCE_CLUT`
74+
``ImageCms.FLAGS["MATRIXONLY"]`` No replacement
75+
``ImageCms.FLAGS["NOWHITEONWHITEFIXUP"]`` :py:attr:`.ImageCms.Flags.NOWHITEONWHITEFIXUP`
76+
``ImageCms.FLAGS["NOPRELINEARIZATION"]`` :py:attr:`.ImageCms.Flags.CLUT_PRE_LINEARIZATION`
77+
``ImageCms.FLAGS["GUESSDEVICECLASS"]`` :py:attr:`.ImageCms.Flags.GUESSDEVICECLASS`
78+
``ImageCms.FLAGS["NOTCACHE"]`` :py:attr:`.ImageCms.Flags.NOCACHE`
79+
``ImageCms.FLAGS["NOTPRECALC"]`` :py:attr:`.ImageCms.Flags.NOOPTIMIZE`
80+
``ImageCms.FLAGS["NULLTRANSFORM"]`` :py:attr:`.ImageCms.Flags.NULLTRANSFORM`
81+
``ImageCms.FLAGS["HIGHRESPRECALC"]`` :py:attr:`.ImageCms.Flags.HIGHRESPRECALC`
82+
``ImageCms.FLAGS["LOWRESPRECALC"]`` :py:attr:`.ImageCms.Flags.LOWRESPRECALC`
83+
``ImageCms.FLAGS["GAMUTCHECK"]`` :py:attr:`.ImageCms.Flags.GAMUTCHECK`
84+
``ImageCms.FLAGS["WHITEBLACKCOMPENSATION"]`` :py:attr:`.ImageCms.Flags.BLACKPOINTCOMPENSATION`
85+
``ImageCms.FLAGS["BLACKPOINTCOMPENSATION"]`` :py:attr:`.ImageCms.Flags.BLACKPOINTCOMPENSATION`
86+
``ImageCms.FLAGS["SOFTPROOFING"]`` :py:attr:`.ImageCms.Flags.SOFTPROOFING`
87+
``ImageCms.FLAGS["PRESERVEBLACK"]`` :py:attr:`.ImageCms.Flags.NONEGATIVES`
88+
``ImageCms.FLAGS["NODEFAULTRESOURCEDEF"]`` :py:attr:`.ImageCms.Flags.NODEFAULTRESOURCEDEF`
89+
``ImageCms.FLAGS["GRIDPOINTS"]`` :py:attr:`.ImageCms.Flags.GRIDPOINTS()`
90+
``ImageCms.versions()`` :py:func:`PIL.features.version_module` with
91+
``feature="littlecms2"``, :py:data:`sys.version` or
92+
:py:data:`sys.version_info`, and ``PIL.__version__``
93+
============================================ ====================================================
94+
5895
Removed features
5996
----------------
6097

@@ -118,7 +155,7 @@ Constants
118155
.. versionremoved:: 10.0.0
119156

120157
A number of constants have been removed.
121-
Instead, ``enum.IntEnum`` classes have been added.
158+
Instead, :py:class:`enum.IntEnum` classes have been added.
122159

123160
.. note::
124161

‎docs/reference/ExifTags.rst‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,9 @@
44
:py:mod:`~PIL.ExifTags` Module
55
==============================
66

7-
The :py:mod:`~PIL.ExifTags` module exposes several ``enum.IntEnum`` classes
8-
which provide constants and clear-text names for various well-known EXIF tags.
7+
The :py:mod:`~PIL.ExifTags` module exposes several :py:class:`enum.IntEnum`
8+
classes which provide constants and clear-text names for various well-known
9+
EXIF tags.
910

1011
.. py:data:: Base
1112

‎docs/reference/ImageCms.rst‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,14 +24,17 @@ Constants
2424
:members:
2525
:member-order: bysource
2626
:undoc-members:
27+
:show-inheritance:
2728
.. autoclass:: Direction
2829
:members:
2930
:member-order: bysource
3031
:undoc-members:
32+
:show-inheritance:
3133
.. autoclass:: Flags
3234
:members:
3335
:member-order: bysource
3436
:undoc-members:
37+
:show-inheritance:
3538

3639
Functions
3740
---------

‎docs/releasenotes/10.0.0.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ Constants
4343
^^^^^^^^^
4444

4545
A number of constants have been removed.
46-
Instead, ``enum.IntEnum`` classes have been added.
46+
Instead, :py:class:`enum.IntEnum` classes have been added.
4747

4848
===================================================== ============================================================
4949
Removed Use instead

‎docs/releasenotes/10.3.0.rst‎

Lines changed: 34 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,40 @@ TODO
1010
Deprecations
1111
============
1212

13-
TODO
14-
^^^^
15-
16-
TODO
13+
ImageCms constants and versions() function
14+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15+
16+
A number of constants and a function in :py:mod:`.ImageCms` have been deprecated.
17+
This includes a table of flags based on LittleCMS version 1 which has been replaced
18+
with a new class :py:class:`.ImageCms.Flags` based on LittleCMS 2 flags.
19+
20+
============================================ ====================================================
21+
Deprecated Use instead
22+
============================================ ====================================================
23+
``ImageCms.DESCRIPTION`` No replacement
24+
``ImageCms.VERSION`` ``PIL.__version__``
25+
``ImageCms.FLAGS["MATRIXINPUT"]`` :py:attr:`.ImageCms.Flags.CLUT_POST_LINEARIZATION`
26+
``ImageCms.FLAGS["MATRIXOUTPUT"]`` :py:attr:`.ImageCms.Flags.FORCE_CLUT`
27+
``ImageCms.FLAGS["MATRIXONLY"]`` No replacement
28+
``ImageCms.FLAGS["NOWHITEONWHITEFIXUP"]`` :py:attr:`.ImageCms.Flags.NOWHITEONWHITEFIXUP`
29+
``ImageCms.FLAGS["NOPRELINEARIZATION"]`` :py:attr:`.ImageCms.Flags.CLUT_PRE_LINEARIZATION`
30+
``ImageCms.FLAGS["GUESSDEVICECLASS"]`` :py:attr:`.ImageCms.Flags.GUESSDEVICECLASS`
31+
``ImageCms.FLAGS["NOTCACHE"]`` :py:attr:`.ImageCms.Flags.NOCACHE`
32+
``ImageCms.FLAGS["NOTPRECALC"]`` :py:attr:`.ImageCms.Flags.NOOPTIMIZE`
33+
``ImageCms.FLAGS["NULLTRANSFORM"]`` :py:attr:`.ImageCms.Flags.NULLTRANSFORM`
34+
``ImageCms.FLAGS["HIGHRESPRECALC"]`` :py:attr:`.ImageCms.Flags.HIGHRESPRECALC`
35+
``ImageCms.FLAGS["LOWRESPRECALC"]`` :py:attr:`.ImageCms.Flags.LOWRESPRECALC`
36+
``ImageCms.FLAGS["GAMUTCHECK"]`` :py:attr:`.ImageCms.Flags.GAMUTCHECK`
37+
``ImageCms.FLAGS["WHITEBLACKCOMPENSATION"]`` :py:attr:`.ImageCms.Flags.BLACKPOINTCOMPENSATION`
38+
``ImageCms.FLAGS["BLACKPOINTCOMPENSATION"]`` :py:attr:`.ImageCms.Flags.BLACKPOINTCOMPENSATION`
39+
``ImageCms.FLAGS["SOFTPROOFING"]`` :py:attr:`.ImageCms.Flags.SOFTPROOFING`
40+
``ImageCms.FLAGS["PRESERVEBLACK"]`` :py:attr:`.ImageCms.Flags.NONEGATIVES`
41+
``ImageCms.FLAGS["NODEFAULTRESOURCEDEF"]`` :py:attr:`.ImageCms.Flags.NODEFAULTRESOURCEDEF`
42+
``ImageCms.FLAGS["GRIDPOINTS"]`` :py:attr:`.ImageCms.Flags.GRIDPOINTS()`
43+
``ImageCms.versions()`` :py:func:`PIL.features.version_module` with
44+
``feature="littlecms2"``, :py:data:`sys.version` or
45+
:py:data:`sys.version_info`, and ``PIL.__version__``
46+
============================================ ====================================================
1747

1848
API Changes
1949
===========

‎docs/releasenotes/9.1.0.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ Constants
5151
^^^^^^^^^
5252

5353
A number of constants have been deprecated and will be removed in Pillow 10.0.0
54-
(2023-07-01). Instead, ``enum.IntEnum`` classes have been added.
54+
(2023-07-01). Instead, :py:class:`enum.IntEnum` classes have been added.
5555

5656
.. note::
5757

‎docs/releasenotes/9.3.0.rst‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,9 @@ Added ExifTags enums
3333
^^^^^^^^^^^^^^^^^^^^
3434

3535
The data from :py:data:`~PIL.ExifTags.TAGS` and
36-
:py:data:`~PIL.ExifTags.GPSTAGS` is now also exposed as ``enum.IntEnum``
37-
classes: :py:data:`~PIL.ExifTags.Base` and :py:data:`~PIL.ExifTags.GPS`.
36+
:py:data:`~PIL.ExifTags.GPSTAGS` is now also exposed as
37+
:py:class:`enum.IntEnum` classes: :py:data:`~PIL.ExifTags.Base` and
38+
:py:data:`~PIL.ExifTags.GPS`.
3839

3940

4041
Security

‎src/PIL/ImageCms.py‎

Lines changed: 29 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,9 @@
44
# Optional color management support, based on Kevin Cazabon's PyCMS
55
# library.
66

7+
# Originally released under LGPL. Graciously donated to PIL in
8+
# March 2009, for distribution under the standard PIL license
9+
710
# History:
811

912
# 2009-03-08 fl Added to PIL.
@@ -20,8 +23,10 @@
2023
import sys
2124
from enum import IntEnum, IntFlag
2225
from functools import reduce
26+
from typing import Any
2327

2428
from . import Image
29+
from ._deprecate import deprecate
2530

2631
try:
2732
from . import _imagingcms
@@ -32,7 +37,7 @@
3237

3338
_imagingcms = DeferredError.new(ex)
3439

35-
DESCRIPTION = """
40+
_DESCRIPTION = """
3641
pyCMS
3742
3843
a Python / PIL interface to the littleCMS ICC Color Management System
@@ -95,7 +100,22 @@
95100
96101
"""
97102

98-
VERSION = "1.0.0 pil"
103+
_VERSION = "1.0.0 pil"
104+
105+
106+
def __getattr__(name: str) -> Any:
107+
if name == "DESCRIPTION":
108+
deprecate("PIL.ImageCms.DESCRIPTION", 12)
109+
return _DESCRIPTION
110+
elif name == "VERSION":
111+
deprecate("PIL.ImageCms.VERSION", 12)
112+
return _VERSION
113+
elif name == "FLAGS":
114+
deprecate("PIL.ImageCms.FLAGS", 12, "PIL.ImageCms.Flags")
115+
return _FLAGS
116+
msg = f"module '{__name__}' has no attribute '{name}'"
117+
raise AttributeError(msg)
118+
99119

100120
# --------------------------------------------------------------------.
101121

@@ -184,7 +204,7 @@ def GRIDPOINTS(n: int) -> Flags:
184204
_MAX_FLAG = reduce(operator.or_, Flags)
185205

186206

187-
FLAGS = {
207+
_FLAGS = {
188208
"MATRIXINPUT": 1,
189209
"MATRIXOUTPUT": 2,
190210
"MATRIXONLY": (1 | 2),
@@ -1064,4 +1084,9 @@ def versions():
10641084
(pyCMS) Fetches versions.
10651085
"""
10661086

1067-
return VERSION, core.littlecms_version, sys.version.split()[0], Image.__version__
1087+
deprecate(
1088+
"PIL.ImageCms.versions()",
1089+
12,
1090+
'(PIL.features.version("littlecms2"), sys.version, PIL.__version__)',
1091+
)
1092+
return _VERSION, core.littlecms_version, sys.version.split()[0], Image.__version__

0 commit comments

Comments
 (0)