Remove the raw color name/value mappings.

It was never a good idea to use them directly, so they've been removed
from the public API. Code which accessed them directly should use the
normalizing conversion functions instead.

Author: ubernostrum

docs/changelog.rst

@@ -20,7 +20,7 @@ subsequent release in the same month would be 25.1.1; a release the following
 month (February) would be 25.2.0.
 
 The CalVer system was adopted for this library in 2024, and the first release
-to use a CalVer version number was 24.5.0.
+to use a CalVer version number was 24.6.0.
 
 
 API stability and deprecations
@@ -50,13 +50,13 @@ The API stability/deprecation policy for this library is as follows:
   case.
 
 * This policy is in effect as of the adoption of CalVer versioning, with
-  version 24.5.0 of this library.
+  version 24.6.0 of this library.
 
 
 Releases under CalVer
 ---------------------
 
-Version 24.5.0
+Version 24.6.0
 ~~~~~~~~~~~~~~
 
 *Not yet released*
@@ -75,6 +75,10 @@ Version 24.5.0
 
 * Adopted `CalVer versioning <https://calver.org>`_.
 
+* The raw mappings of color names/values are no longer publicly exposed; use
+  the appropriate normalizing conversion functions instead of accessing the
+  mappings directly.
+
 
 Releases not under CalVer
 -------------------------

docs/contents.rst

@@ -66,16 +66,11 @@ defined, and used throughout this module:
 .. autodata:: IntTuple
 .. autodata:: PercentTuple
 
-Constants
----------
-
-Several sets of constants are provided in ``webcolors``, for use when
-converting or identifying colors or specifications.
 
 .. _spec-constants:
 
-Specification identifiers
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+Constants
+---------
 
 The following constants are available for indicating the specification from
 which to draw color name choices, in functions which can work with multiple
@@ -98,81 +93,6 @@ specifications.
    Represents the HTML 4 specification. Value is ``"html4"``.
 
 
-.. _mapping-constants:
-
-Color mappings
-~~~~~~~~~~~~~~
-
-The following constants are available for direct use in mapping from color
-names to values, although it is strongly recommended to use one of the
-normalizing conversion functions instead.
-
-
-Mappings from names to hexadecimal values
-+++++++++++++++++++++++++++++++++++++++++
-
-.. data:: HTML4_NAMES_TO_HEX
-
-   A :class:`dict` whose keys are the normalized names of the sixteen named
-   HTML 4 colors, and whose values are the normalized hexadecimal values of
-   those colors.
-
-.. data:: CSS2_NAMES_TO_HEX
-
-   An alias for :data:`~webcolors.HTML4_NAMES_TO_HEX`, as CSS2 defined the same
-   set of colors.
-
-.. data:: CSS21_NAMES_TO_HEX
-
-   A :class:`dict` whose keys are the normalized names of the seventeen named
-   CSS2.1 colors, and whose values are the normalized hexadecimal values of
-   those colors (sixteen of these are identical to HTML 4 and CSS2; the
-   seventeenth color is ``"orange"``, added in CSS2.1).
-
-.. data:: CSS3_NAMES_TO_HEX
-
-   A :class:`dict` whose keys are the normalized names of the 147 named CSS3
-   colors, and whose values are the normalized hexadecimal values of those
-   colors. These colors are also identical to the 147 named colors of SVG.
-
-
-Mappings from hexadecimal values to names
-+++++++++++++++++++++++++++++++++++++++++
-
-.. data:: HTML4_HEX_TO_NAMES
-
-   A :class:`dict` whose keys are the normalized hexadecimal values of the
-   sixteen named HTML 4 colors, and whose values are the corresponding
-   normalized names.
-
-.. data:: CSS2_HEX_TO_NAMES
-
-   An alias for :data:`~webcolors.HTML4_HEX_TO_NAMES`, as CSS2 defined the same
-   set of colors.
-
-.. data:: CSS21_HEX_TO_NAMES
-
-   A :class:`dict` whose keys are the normalized hexadecimal values of the
-   seventeen named CSS2.1 colors, and whose values are the corresponding
-   normalized names (sixteen of these are identical to HTML 4 and CSS2; the
-   seventeenth color is ``"orange"``, added in CSS2.1).
-
-.. data:: CSS3_HEX_TO_NAMES
-
-   A :class:`dict` whose keys are the normalized hexadecimal values of the 147
-   named CSS3 colors, and whose values are the corresponding normalized
-   names. These colors are also identical to the 147 named colors of SVG.
-
-   .. note:: **Spelling variants**
-
-      Some values representing named gray colors can map to either of two names
-      in CSS3, because it supports both ``"gray"`` and ``"grey"`` spelling
-      variants for those colors. This mapping will always return the variant
-      spelled ``"gray"`` (such as ``"lightgray"`` instead of
-      ``"lightgrey"``). See :ref:`the documentation on name conventions
-      <color-name-conventions>` for details.
-
-
 Normalization functions
 -----------------------
 

src/webcolors/__init__.py

@@ -1,10 +1,9 @@
 """
-Utility functions for working with the color names and color value
-formats defined by the HTML and CSS specifications for use in
-documents on the web.
+Functions for working with the color names and color value formats defined by the
+HTML and CSS specifications for use in documents on the web.
 
-See documentation (in docs/ directory of source distribution) for
-details of the supported formats, conventions and conversions.
+See documentation (in docs/ directory of source distribution) for details of the
+supported formats, conventions and conversions.
 
 """
 
@@ -24,20 +23,7 @@
     rgb_to_name,
     rgb_to_rgb_percent,
 )
-from ._definitions import (
-    CSS2,
-    CSS2_HEX_TO_NAMES,
-    CSS2_NAMES_TO_HEX,
-    CSS3,
-    CSS3_HEX_TO_NAMES,
-    CSS3_NAMES_TO_HEX,
-    CSS21,
-    CSS21_HEX_TO_NAMES,
-    CSS21_NAMES_TO_HEX,
-    HTML4,
-    HTML4_HEX_TO_NAMES,
-    HTML4_NAMES_TO_HEX,
-)
+from ._definitions import CSS2, CSS3, CSS21, HTML4
 from ._html5 import (
     html5_parse_legacy_color,
     html5_parse_simple_color,
@@ -50,21 +36,13 @@
 )
 from ._types import HTML5SimpleColor, IntegerRGB, IntTuple, PercentRGB, PercentTuple
 
-__version__ = "24.5.0a1"
+__version__ = "24.6.0a1"
 
 __all__ = [
     "HTML4",
     "CSS2",
     "CSS21",
     "CSS3",
-    "HTML4_NAMES_TO_HEX",
-    "HTML4_HEX_TO_NAMES",
-    "CSS2_NAMES_TO_HEX",
-    "CSS2_HEX_TO_NAMES",
-    "CSS21_HEX_TO_NAMES",
-    "CSS21_NAMES_TO_HEX",
-    "CSS3_HEX_TO_NAMES",
-    "CSS3_NAMES_TO_HEX",
     "name_to_hex",
     "name_to_rgb",
     "name_to_rgb_percent",

tests/test_html5.py

@@ -88,7 +88,7 @@ def test_parse_legacy_color_names(self):
         Test the HTML5 legacy color parsing of SVG/CSS3 color names.
 
         """
-        for name in webcolors.CSS3_NAMES_TO_HEX:
+        for name in webcolors._definitions.CSS3_NAMES_TO_HEX:
             parsed = webcolors.html5_parse_legacy_color(name)
             assert parsed == webcolors.name_to_rgb(name)