Module contents#
The contents of the webcolors module fall into five categories:
A set of (optional) data types for representing color values.
Constants for several purposes.
Normalization functions which sanitize input in various formats prior to conversion or output.
Conversion functions between each method of specifying colors.
Implementations of the color parsing and serialization algorithms in HTML5.
See the documentation regarding conventions for information regarding the types and representation of various color formats in webcolors.
All conversion functions which involve color names take an optional argument to determine the specification from which to draw color names. See the set of specification identifiers for valid values.
All conversion functions, when faced with identifiably invalid hexadecimal
color values, or with a request to name a color which has no name in the
requested specification, or with an invalid specification identifier, will
raise ValueError
.
Imports and submodules
The public, supported API of webcolors is exported from its top-level
module, webcolors
. Although the codebase is internally organized into
several submodules for easier maintenance, the existence, names, and
organization of these submodules is not part of webcolors’ public API and
cannot be relied upon.
For example: although normalize_hex()
is actually implemented
in a submodule named webcolors.normalization
, it must always be
referred to as webcolors.normalize_hex
, never as
webcolors.normalization.normalize_hex
.
Data types#
Integer and percentage rgb()
triplets, and HTML5 simple colors, can be
passed to functions in webcolors as plain 3-tuple
of the appropriate
data type. But the following NamedTuple
instances are also
provided to represent these types more richly, and functions in webcolors which
return triplets or simple colors will return instances of these:
Additionally, to aid in type annotations, the following type aliases are defined, and used throughout this module:
Constants#
Several sets of constants are provided in webcolors, for use when converting or identifying colors or specifications.
Specification identifiers#
The following constants are available for indicating the specification from which to draw color name choices, in functions which can work with multiple specifications.
- webcolors.CSS2#
Represents the CSS2 specification. Value is
"css2"
.
- webcolors.CSS21#
Represents the CSS2.1 specification. Value is
"css21"
.
- webcolors.CSS3#
Represents the CSS3 specification. Value is
"css3"
.
- webcolors.HTML4#
Represents the HTML 4 specification. Value is
"html4"
.
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#
- webcolors.HTML4_NAMES_TO_HEX#
A
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.
- webcolors.CSS2_NAMES_TO_HEX#
An alias for
HTML4_NAMES_TO_HEX
, as CSS2 defined the same set of colors.
- webcolors.CSS21_NAMES_TO_HEX#
A
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).
- webcolors.CSS3_NAMES_TO_HEX#
A
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#
- webcolors.HTML4_HEX_TO_NAMES#
A
dict
whose keys are the normalized hexadecimal values of the sixteen named HTML 4 colors, and whose values are the corresponding normalized names.
- webcolors.CSS2_HEX_TO_NAMES#
An alias for
HTML4_HEX_TO_NAMES
, as CSS2 defined the same set of colors.
- webcolors.CSS21_HEX_TO_NAMES#
A
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).
- webcolors.CSS3_HEX_TO_NAMES#
A
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 the documentation on name conventions for details.
Normalization functions#
Conversions from color names to other formats#
Conversions from hexadecimal color values to other formats#
Conversions from integer rgb() triplets to other formats#
Conversions from percentage rgb() triplets to other formats#
HTML5 color algorithms#
Warning
Previously there were two competing HTML5 standards: one from WHATWG, and one from W3C. The WHATWG version is now the sole official HTML5 standard, and so the functions documented below implement the HTML5 color algorithms as given in section 2.3.6 of the WHATWG HTML5 standard.