Skip to content

Deprecate ImageCms constants and versions() function #7702

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hugovk merged 7 commits into from
Jan 11, 2024
Merged

Deprecate ImageCms constants and versions() function #7702

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
08f11c5
deprecate ImageCms members: DESCRIPTION, VERSION, FLAGS, versions()
nulano Jan 1, 2024
edc46e2
document ImageCms deprecations
nulano Jan 8, 2024
bddfebc
add license comment to ImageCms; explicitly say "no replacement" for …
nulano Jan 8, 2024
208a34c
Merge branch 'main' into deprecate-cms-constants
radarhere Jan 8, 2024
1e8a03c
Link to Python enum documentation
radarhere Jan 9, 2024
71ba20b
Shortened table description
radarhere Jan 9, 2024
5347b47
Update Tests/test_imagecms.py
nulano Jan 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 11 additions & 2 deletions Tests/test_imagecms.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]

Expand Down Expand Up @@ -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():
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)
39 changes: 38 additions & 1 deletion docs/deprecations.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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``
``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"]``
``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
----------------

Expand Down Expand Up @@ -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::

Expand Down
3 changes: 3 additions & 0 deletions docs/reference/ImageCms.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
---------
Expand Down
83 changes: 83 additions & 0 deletions docs/releasenotes/10.3.0.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
10.3.0
------

Backwards Incompatible Changes
==============================

TODO
^^^^

Deprecations
============

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``
``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"]``
Copy link
Member

@hugovk hugovk Jan 8, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No replacement for this?

Copy link
Contributor Author

@nulano nulano Jan 8, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is equal to (1 | 2) i.e. (MATRIXINPUT | MATRIXOUTPUT), so it could be CLUT_POST_LINEARIZATION | FORCE_CLUT, but from the flag names it looks like these values have been repurposed in LCMS2.

I wasn't even sure about listing the replacements for MATRIXINPUT and MATRIXOUTPUT, but I couldn't find any LCMS2 documentation on this and didn't feel like hunting around in LCMS2 source code to check for each flag, so I just matched all flags by their values.

``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__``
===================================================== ============================================================

TODO
^^^^

TODO

API Changes
===========

TODO
^^^^

TODO

API Additions
=============

TODO
^^^^

TODO

Security
========

TODO
^^^^

TODO

Other Changes
=============

TODO
^^^^

TODO
2 changes: 1 addition & 1 deletion docs/releasenotes/9.1.0.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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::

Expand Down
1 change: 1 addition & 0 deletions docs/releasenotes/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ expected to be backported to earlier versions.
.. toctree::
:maxdepth: 2

10.3.0
10.2.0
10.1.0
10.0.1
Expand Down
30 changes: 26 additions & 4 deletions src/PIL/ImageCms.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,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
Expand All @@ -32,7 +34,7 @@

_imagingcms = DeferredError.new(ex)

DESCRIPTION = """
_DESCRIPTION = """
Copy link
Member

@hugovk hugovk Jan 8, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When removing this constant, is there any important info in this text we should keep somewhere?

Copy link
Contributor Author

@nulano nulano Jan 8, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Originally released under LGPL. Graciously donated to PIL in
March 2009, for distribution under the standard PIL license

This should probably be turned into a comment - I've pushed a commit.

There are also links to https://www.cazabon.com/pyCMS and https://www.littlecms.com. I'm not sure these need to be kept; https://www.cazabon.com/pyCMS is the first result I get on Google for "Kevin Cazabon's PyCMS library" in a private window.

Otherwise, it just duplicates information from comments in ImageCms.py, text from ImageCms.rst, and part of CHANGES.rst for PIL 1.1.7c1.

pyCMS

a Python / PIL interface to the littleCMS ICC Color Management System
Expand Down Expand Up @@ -95,7 +97,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)


# --------------------------------------------------------------------.

Expand Down Expand Up @@ -184,7 +201,7 @@ def GRIDPOINTS(n: int) -> Flags:
_MAX_FLAG = reduce(operator.or_, Flags)


FLAGS = {
_FLAGS = {
"MATRIXINPUT": 1,
"MATRIXOUTPUT": 2,
"MATRIXONLY": (1 | 2),
Expand Down Expand Up @@ -1064,4 +1081,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__