document ImageCms deprecations

nulano · Jan 8, 2024 · edc46e2 · edc46e2
1 parent 08f11c5
commit edc46e2
Show file tree

Hide file tree

Showing 5 changed files with 126 additions and 2 deletions.
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``
+``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
 ----------------
 
@@ -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/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.3.0.rst b/docs/releasenotes/10.3.0.rst
@@ -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"]``
+``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
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/index.rst b/docs/releasenotes/index.rst
@@ -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