Skip to content

Commit 41046b0

Browse files
ubernostrumubernostrum
committed
Reorganize and update the FAQ.
1 parent 0f865b2 commit 41046b0

File tree

1 file changed

+86
-75
lines changed

1 file changed

+86
-75
lines changed

‎docs/faq.rst

+86-75
Original file line numberDiff line numberDiff line change
@@ -7,44 +7,71 @@ The following notes answer common questions, and may be useful to you when
77
using ``webcolors``.
88

99

10+
General
11+
-------
12+
1013
What versions of Python are supported?
11-
--------------------------------------
14+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1215

1316
Version |release| of ``webcolors`` supports and is tested on Python 3.8, 3.9,
1417
3.10, 3.11, and 3.12.
1518

1619

20+
How am I allowed to use this module?
21+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
22+
23+
The ``webcolors`` module is distributed under a `three-clause BSD license
24+
<http://opensource.org/licenses/BSD-3-Clause>`_. This is an open-source license
25+
which grants you broad freedom to use, redistribute, modify and distribute
26+
modified versions of ``webcolors``. For details, see the file ``LICENSE`` in
27+
the source distribution of ``webcolors``.
28+
29+
.. _three-clause BSD license: http://opensource.org/licenses/BSD-3-Clause
30+
31+
32+
I found a bug or want to make an improvement!
33+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
34+
35+
The canonical development repository for ``webcolors`` is online at
36+
<https://github.com/ubernostrum/webcolors>. Issues and pull requests can both
37+
be filed there.
38+
39+
1740
How closely does this module follow the standards?
18-
--------------------------------------------------
41+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1942

2043
As closely as is practical (see below regarding floating-point values), within
2144
:ref:`the supported formats <support>`; the ``webcolors`` module was written
2245
with the relevant standards documents close at hand. See :ref:`the conformance
2346
documentation <conformance>` for details.
2447

2548

26-
Why aren't ``rgb_to_rgb_percent()`` and ``rgb_percent_to_rgb()`` precise?
27-
-------------------------------------------------------------------------
49+
Design choices and technical details
50+
------------------------------------
2851

29-
This is due to limitations in the representation of floating-point numbers in
30-
programming languages. Python, like many programming languages, uses `IEEE
31-
floating-point <https://en.wikipedia.org/wiki/IEEE_754>`_, which is inherently
32-
imprecise for some values. This imprecision only appears when converting
33-
between integer and percentage ```rgb()``` triplets, as in
34-
:func:`~webcolors.rgb_to_rgb_percent` and
35-
:func:`~webcolors.rgb_percent_to_rgb`.
3652

37-
To work around this, some common values (255, 128, 64, 32, 16 and 0) are
38-
handled as special cases, with hard-coded precise results. For all other
39-
values, conversion to percentage ``rgb()`` triplet uses a standard Python
40-
:class:`float`, rounding the result to two decimal places.
53+
Why not use a more object-oriented design with classes for the colors?
54+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4155

42-
See :ref:`the conformance documentation <conformance>` for details on how this
43-
affects testing.
56+
Representing color values with Python classes would introduce overhead for no
57+
real gain. Real-world use cases tend to involve working directly with the
58+
actual values, so settling on conventions for how to represent them as Python
59+
types, and then offering a function-based interface, accomplishes everything
60+
needed without the additional indirection layer of having to instantiate and
61+
serialize a color-wrapping object.
62+
63+
Keeping a function-based interface also maintains consistency with Python's
64+
built-in :mod:`colorsys` module which has the same style of interface for
65+
converting amongst color spaces.
66+
67+
Note that if an object-oriented interface is desired, `the third-party
68+
colormath module <https://pypi.org/project/colormath/>`_ does have a
69+
class-based interface (and rightly so, as it offers a wider range of color
70+
representation and manipulation options than ``webcolors``).
4471

4572

4673
Why does ``webcolors`` prefer American spellings?
47-
-------------------------------------------------
74+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4875

4976
In CSS3, several color names are defined multiple times with identical values,
5077
to support both American and British spelling variants for
@@ -65,72 +92,56 @@ and CSS2, each of which only allowed `gray`.
6592

6693

6794
Why aren't HSL values supported?
68-
--------------------------------
69-
70-
In the author's experience, actual use of HSL values on the web is extremely
71-
rare; the overwhelming majority of all colors used on the web are specified
72-
using sRGB, through hexadecimal color values or through integer or percentage
73-
``rgb()`` triplets. This decreases the importance of supporting the ``hsl()``
74-
construct.
75-
76-
Additionally, Python already has the :mod:`colorsys` module in the standard
77-
library, which offers functions for converting between RGB, HSL, HSV and YIQ
78-
color systems. If you need conversion to/from HSL or another color system, use
79-
:mod:`colorsys`.
80-
81-
82-
Why aren't alpha-channel constructs like ``rgba()`` supported?
83-
--------------------------------------------------------------
95+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
8496

85-
Because the alpha-channel information can't really be usefully converted. As of
86-
CSS3, the ``hsla()`` construct is the only other color format that carries
87-
alpha-channel information, and as explained above, HSL colors are not supported
88-
in this module.
97+
The :mod:`colorsys` module in the standard library contains functions for
98+
converting between RGB, HSL, HSV and YIQ color systems, so you can convert
99+
integer RGB triplets from ``webcolors`` to HSL triplets, or vice-versa, using
100+
:mod:`colorsys`, without ``webcolors`` needing to provide its own conversion
101+
functions.
89102

90-
The W3C CSS Colors Level 4 module does provide an 8-digit hexadecimal color
91-
representation where the final two digits carry alpha-channel
92-
information. Support for its alpha-channel constructs in this module may
93-
eventually be re-evaluated, though it would likely still be limited to
94-
converting between only those constructs which carry alpha-channel information
95-
(for example, an ``rgba()`` or an eight-digit hexadecimal color value could not
96-
be losslessly round-tripped to a color name and back).
97103

104+
Why aren't ``rgb_to_rgb_percent()`` and ``rgb_percent_to_rgb()`` precise?
105+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
98106

99-
Why not use a more object-oriented design with classes for the colors?
100-
----------------------------------------------------------------------
101-
102-
Representing color values with Python classes would introduce overhead for no
103-
real gain. Real-world use cases tend to involve working directly with the
104-
actual values, so settling on conventions for how to represent them as Python
105-
types, and then offering a function-based interface, accomplishes everything
106-
needed without the additional indirection layer of having to instantiate and
107-
serialize a color-wrapping object.
108-
109-
Keeping a function-based interface also maintains consistency with Python's
110-
built-in :mod:`colorsys` module which has the same style of interface for
111-
converting amongst color spaces.
107+
This is due to limitations in the representation of floating-point numbers in
108+
programming languages. Python, like many programming languages, uses `IEEE
109+
floating-point <https://en.wikipedia.org/wiki/IEEE_754>`_, which is inherently
110+
imprecise for some values. This imprecision only appears when converting
111+
between integer and percentage ```rgb()``` triplets, as in
112+
:func:`~webcolors.rgb_to_rgb_percent` and
113+
:func:`~webcolors.rgb_percent_to_rgb`.
112114

113-
Note that if an object-oriented interface is desired, `the third-party
114-
colormath module <https://pypi.org/project/colormath/>`_ does have a
115-
class-based interface (and rightly so, as it offers a wider range of color
116-
representation and manipulation options than ``webcolors``).
115+
To work around this, some common values (255, 128, 64, 32, 16 and 0) are
116+
handled as special cases, with hard-coded precise results. For all other
117+
values, conversion to percentage ``rgb()`` triplet uses a standard Python
118+
:class:`float`, rounding the result to two decimal places.
117119

120+
See :ref:`the conformance documentation <conformance>` for details on how this
121+
affects testing.
118122

119-
How am I allowed to use this module?
120-
------------------------------------
121123

122-
The ``webcolors`` module is distributed under a `three-clause BSD license
123-
<http://opensource.org/licenses/BSD-3-Clause>`_. This is an open-source license
124-
which grants you broad freedom to use, redistribute, modify and distribute
125-
modified versions of ``webcolors``. For details, see the file ``LICENSE`` in
126-
the source distribution of ``webcolors``.
124+
Are alpha-channel constructs like ``rgba()`` supported?
125+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
127126

128-
.. _three-clause BSD license: http://opensource.org/licenses/BSD-3-Clause
127+
While this decision may be re-evaluated in the future, ``webcolors`` currently
128+
does *not* support constructs which carry alpha-channel information (the
129+
``rgba()`` and ``hsla()`` constructs of CSS3, or the ``#rrggbbaa`` construct of
130+
the CSS Colors Level 4 module).
129131

132+
There are two main reasons for this:
130133

131-
I found a bug or want to make an improvement!
132-
---------------------------------------------
134+
1. ``webcolors`` does not yet support the CSS Color Module Level 4 in any way,
135+
which means the only supported construct would be ``rgba()`` (since
136+
``webcolors`` only handles RGB color constructs, not HSL), and there would
137+
be no other alpha-channel construct to convert to or from.
133138

134-
The canonical development repository for ``webcolors`` is online at
135-
<https://github.com/ubernostrum/webcolors>. Issues and pull requests can both
136-
be filed there.
139+
2. Once support for the CSS Color Module Level 4 is finalized, it's still not
140+
clear that converting between ``rgba()`` and ``#rrggbbaa`` constructs would
141+
be useful enough on its own to justify the support. Converting to
142+
non-alpha-channel constructs would not require specialized functions since
143+
the alpha-channel component could simply be sliced off, and converting
144+
_from_ non-alpha-channel constructs to alpha-channel constructs similarly
145+
does not seem to require additional functions -- the desired alpha-channel
146+
information could be appended onto a non-alpha-channel construct easily
147+
enough.

0 commit comments

Comments
 (0)