From 41046b00da5e892809d83cf4c0725d471e36118f Mon Sep 17 00:00:00 2001 From: James Bennett Date: Wed, 5 Jun 2024 23:23:05 -0700 Subject: [PATCH] Reorganize and update the FAQ. --- docs/faq.rst | 161 +++++++++++++++++++++++++++------------------------ 1 file changed, 86 insertions(+), 75 deletions(-) diff --git a/docs/faq.rst b/docs/faq.rst index f5b5a01..3d5cc91 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -7,15 +7,38 @@ The following notes answer common questions, and may be useful to you when using ``webcolors``. +General +------- + What versions of Python are supported? --------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Version |release| of ``webcolors`` supports and is tested on Python 3.8, 3.9, 3.10, 3.11, and 3.12. +How am I allowed to use this module? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``webcolors`` module is distributed under a `three-clause BSD license +`_. This is an open-source license +which grants you broad freedom to use, redistribute, modify and distribute +modified versions of ``webcolors``. For details, see the file ``LICENSE`` in +the source distribution of ``webcolors``. + +.. _three-clause BSD license: http://opensource.org/licenses/BSD-3-Clause + + +I found a bug or want to make an improvement! +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The canonical development repository for ``webcolors`` is online at +. Issues and pull requests can both +be filed there. + + How closely does this module follow the standards? --------------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ As closely as is practical (see below regarding floating-point values), within :ref:`the supported formats `; the ``webcolors`` module was written @@ -23,28 +46,32 @@ with the relevant standards documents close at hand. See :ref:`the conformance documentation ` for details. -Why aren't ``rgb_to_rgb_percent()`` and ``rgb_percent_to_rgb()`` precise? -------------------------------------------------------------------------- +Design choices and technical details +------------------------------------ -This is due to limitations in the representation of floating-point numbers in -programming languages. Python, like many programming languages, uses `IEEE -floating-point `_, which is inherently -imprecise for some values. This imprecision only appears when converting -between integer and percentage ```rgb()``` triplets, as in -:func:`~webcolors.rgb_to_rgb_percent` and -:func:`~webcolors.rgb_percent_to_rgb`. -To work around this, some common values (255, 128, 64, 32, 16 and 0) are -handled as special cases, with hard-coded precise results. For all other -values, conversion to percentage ``rgb()`` triplet uses a standard Python -:class:`float`, rounding the result to two decimal places. +Why not use a more object-oriented design with classes for the colors? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -See :ref:`the conformance documentation ` for details on how this -affects testing. +Representing color values with Python classes would introduce overhead for no +real gain. Real-world use cases tend to involve working directly with the +actual values, so settling on conventions for how to represent them as Python +types, and then offering a function-based interface, accomplishes everything +needed without the additional indirection layer of having to instantiate and +serialize a color-wrapping object. + +Keeping a function-based interface also maintains consistency with Python's +built-in :mod:`colorsys` module which has the same style of interface for +converting amongst color spaces. + +Note that if an object-oriented interface is desired, `the third-party +colormath module `_ does have a +class-based interface (and rightly so, as it offers a wider range of color +representation and manipulation options than ``webcolors``). Why does ``webcolors`` prefer American spellings? -------------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In CSS3, several color names are defined multiple times with identical values, to support both American and British spelling variants for @@ -65,72 +92,56 @@ and CSS2, each of which only allowed `gray`. Why aren't HSL values supported? --------------------------------- - -In the author's experience, actual use of HSL values on the web is extremely -rare; the overwhelming majority of all colors used on the web are specified -using sRGB, through hexadecimal color values or through integer or percentage -``rgb()`` triplets. This decreases the importance of supporting the ``hsl()`` -construct. - -Additionally, Python already has the :mod:`colorsys` module in the standard -library, which offers functions for converting between RGB, HSL, HSV and YIQ -color systems. If you need conversion to/from HSL or another color system, use -:mod:`colorsys`. - - -Why aren't alpha-channel constructs like ``rgba()`` supported? --------------------------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Because the alpha-channel information can't really be usefully converted. As of -CSS3, the ``hsla()`` construct is the only other color format that carries -alpha-channel information, and as explained above, HSL colors are not supported -in this module. +The :mod:`colorsys` module in the standard library contains functions for +converting between RGB, HSL, HSV and YIQ color systems, so you can convert +integer RGB triplets from ``webcolors`` to HSL triplets, or vice-versa, using +:mod:`colorsys`, without ``webcolors`` needing to provide its own conversion +functions. -The W3C CSS Colors Level 4 module does provide an 8-digit hexadecimal color -representation where the final two digits carry alpha-channel -information. Support for its alpha-channel constructs in this module may -eventually be re-evaluated, though it would likely still be limited to -converting between only those constructs which carry alpha-channel information -(for example, an ``rgba()`` or an eight-digit hexadecimal color value could not -be losslessly round-tripped to a color name and back). +Why aren't ``rgb_to_rgb_percent()`` and ``rgb_percent_to_rgb()`` precise? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Why not use a more object-oriented design with classes for the colors? ----------------------------------------------------------------------- - -Representing color values with Python classes would introduce overhead for no -real gain. Real-world use cases tend to involve working directly with the -actual values, so settling on conventions for how to represent them as Python -types, and then offering a function-based interface, accomplishes everything -needed without the additional indirection layer of having to instantiate and -serialize a color-wrapping object. - -Keeping a function-based interface also maintains consistency with Python's -built-in :mod:`colorsys` module which has the same style of interface for -converting amongst color spaces. +This is due to limitations in the representation of floating-point numbers in +programming languages. Python, like many programming languages, uses `IEEE +floating-point `_, which is inherently +imprecise for some values. This imprecision only appears when converting +between integer and percentage ```rgb()``` triplets, as in +:func:`~webcolors.rgb_to_rgb_percent` and +:func:`~webcolors.rgb_percent_to_rgb`. -Note that if an object-oriented interface is desired, `the third-party -colormath module `_ does have a -class-based interface (and rightly so, as it offers a wider range of color -representation and manipulation options than ``webcolors``). +To work around this, some common values (255, 128, 64, 32, 16 and 0) are +handled as special cases, with hard-coded precise results. For all other +values, conversion to percentage ``rgb()`` triplet uses a standard Python +:class:`float`, rounding the result to two decimal places. +See :ref:`the conformance documentation ` for details on how this +affects testing. -How am I allowed to use this module? ------------------------------------- -The ``webcolors`` module is distributed under a `three-clause BSD license -`_. This is an open-source license -which grants you broad freedom to use, redistribute, modify and distribute -modified versions of ``webcolors``. For details, see the file ``LICENSE`` in -the source distribution of ``webcolors``. +Are alpha-channel constructs like ``rgba()`` supported? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. _three-clause BSD license: http://opensource.org/licenses/BSD-3-Clause +While this decision may be re-evaluated in the future, ``webcolors`` currently +does *not* support constructs which carry alpha-channel information (the +``rgba()`` and ``hsla()`` constructs of CSS3, or the ``#rrggbbaa`` construct of +the CSS Colors Level 4 module). +There are two main reasons for this: -I found a bug or want to make an improvement! ---------------------------------------------- +1. ``webcolors`` does not yet support the CSS Color Module Level 4 in any way, + which means the only supported construct would be ``rgba()`` (since + ``webcolors`` only handles RGB color constructs, not HSL), and there would + be no other alpha-channel construct to convert to or from. -The canonical development repository for ``webcolors`` is online at -. Issues and pull requests can both -be filed there. +2. Once support for the CSS Color Module Level 4 is finalized, it's still not + clear that converting between ``rgba()`` and ``#rrggbbaa`` constructs would + be useful enough on its own to justify the support. Converting to + non-alpha-channel constructs would not require specialized functions since + the alpha-channel component could simply be sliced off, and converting + _from_ non-alpha-channel constructs to alpha-channel constructs similarly + does not seem to require additional functions -- the desired alpha-channel + information could be appended onto a non-alpha-channel construct easily + enough.