Module contents¶

The contents of the webcolors module fall into five categories:

A set of (optional) data types for representing color values.
Constants which provide mappings between color names and values.
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 which specification to draw color names from. See the list of specification identifiers for a list of 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.

In the documentation below, “Unicode string” means the Unicode string type of the Python version being used; on Python 3 this is str and on Python 2 it is unicode. See the documentation on use of Python string types for details.

Data types¶

class webcolors.IntegerRGB¶

A namedtuple representing an integer RGB triplet. Has three fields, each of type int and in the range 0-255 inclusive:

red¶: The red portion of the color value.

green¶: The red portion of the color value.

blue¶: The red portion of the color value.

class webcolors.PercentRGB¶

A namedtuple representing a percentage RGB triplet. Has three fields, each of type str and representing a percentage value in the range 0%-100% inclusive:

red¶: The red portion of the color value.

green¶: The red portion of the color value.

blue¶: The red portion of the color value.

class webcolors.HTML5SimpleColor¶

A namedtuple representing an HTML5 simple color. Has three fields, each of type int and in the range 0-255 inclusive:

red¶: The red portion of the color value.

green¶: The red portion of the color value.

blue¶: The red portion of the color value.

Constants¶

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 dictionary 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 CSS 2 defined the same set of colors.

webcolors.CSS21_NAMES_TO_HEX¶: A dictionary whose keys are the normalized names of the seventeen named CSS 2.1 colors, and whose values are the normalized hexadecimal values of those colors (sixteen of these are identical to HTML 4 and CSS 2; the seventeenth color is orange, added in CSS 2.1).

webcolors.CSS3_NAMES_TO_HEX¶: A dictionary whose keys are the normalized names of the 147 named CSS 3 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 dictionary 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.

webcolors.CSS21_HEX_TO_NAMES¶: A dictionary whose keys are the normalized hexadecimal values of the seventeen named CSS 2.1 colors, and whose values are the corresponding normalized names.

webcolors.CSS3_HEX_TO_NAMES¶: A dictionary whose keys are the normalized hexadecimal values of the 147 names CSS 3 colors, and whose values are the corresponding normalized names.

The canonical names of these constants are as listed above, entirely in uppercase. For backwards compatibility with older versions of webcolors, aliases are provided whose names are entirely lowercase (for example, html4_names_to_hex).

Normalization functions¶

webcolors.normalize_hex(hex_value)¶

Normalize a hexadecimal color value to a string consisting of the character # followed by six lowercase hexadecimal digits (what HTML5 terms a “valid lowercase simple color”).

If the supplied value cannot be interpreted as a hexadecimal color value, ValueError is raised. See the conventions used by this module for information on acceptable formats for hexadecimal values.

Examples:

>>> normalize_hex(u'#0099cc')
'#0099cc'
>>> normalize_hex(u'#0099CC')
'#0099cc'
>>> normalize_hex(u'#09c')
'#0099cc'
>>> normalize_hex(u'#09C')
'#0099cc'
>>> normalize_hex(u'#0099gg')
Traceback (most recent call last):
    ...
ValueError: '#0099gg' is not a valid hexadecimal color value.
>>> normalize_hex(u'0099cc')
Traceback (most recent call last):
    ...
ValueError: '0099cc' is not a valid hexadecimal color value.

Parameters:	hex_value (`str`) – The hexadecimal color value to normalize.
Return type:	Unicode string

webcolors.normalize_integer_triplet(rgb_triplet)¶

Normalize an integer rgb() triplet so that all values are within the range 0..255.

Examples:

>>> normalize_integer_triplet((128, 128, 128))
IntegerRGB(red=128, green=128, blue=128)
>>> normalize_integer_triplet((0, 0, 0))
IntegerRGB(red=0, green=0, blue=0)
>>> normalize_integer_triplet((255, 255, 255))
IntegerRGB(red=255, green=255, blue=255)
>>> normalize_integer_triplet((270, -20, -0))
IntegerRGB(red=255, green=0, blue=0)

Parameters:	rgb_triplet (3-tuple of `int`) – The integer `rgb()` triplet to normalize.
Return type:	IntegerRGB

webcolors.normalize_percent_triplet(rgb_triplet)¶

Normalize a percentage rgb() triplet to that all values are within the range 0%..100%.

Examples:

>>> normalize_percent_triplet((u'50%', u'50%', u'50%'))
PercentRGB(red=u'50%', green=u'50%', blue=u'50%')
>>> normalize_percent_triplet((u'0%', u'100%', u'0%'))
PercentRGB(red=u'0%', green=u'100%', blue=u'0%')
>>> normalize_percent_triplet((u'-10%', u'-0%', u'500%'))
PercentRGB(red=u'0%', green=u'0%', blue=u'100%')

Parameters:	rgb_triplet (3-tuple of `str`) – The percentage `rgb()` triplet to normalize.
Return type:	PercentRGB

Conversions from color names to other formats¶

webcolors.name_to_hex(name, spec=u'css3')¶

Convert a color name to a normalized hexadecimal color value.

The color name will be normalized to lower-case before being looked up.

Examples:

>>> name_to_hex(u'white')
u'#ffffff'
>>> name_to_hex(u'navy')
u'#000080'
>>> name_to_hex(u'goldenrod')
u'#daa520'
>>> name_to_hex(u'goldenrod', spec=u'html4')
Traceback (most recent call last):
    ...
ValueError: 'goldenrod' is not defined as a named color in html4.

Parameters:	name (`str`) – The color name to convert. spec (`str`) – The specification from which to draw the list of color names; valid values are `'html4'`, `'css2'`, `'css21'` and `'css3'`. Default is `'css3'`.
Return type:	Unicode string

webcolors.name_to_rgb(name, spec=u'css3')¶

Convert a color name to a 3-tuple of integers suitable for use in an rgb() triplet specifying that color.

The color name will be normalized to lower-case before being looked up.

Examples:

>>> name_to_rgb(u'white')
IntegerRGB(red=255, green=255, blue=255)
>>> name_to_rgb(u'navy')
IntegerRGB(red=0, green=0, blue=128)
>>> name_to_rgb(u'goldenrod')
IntegerRGB(red=218, green=165, blue=32)

Parameters:	name (`str`) – The color name to convert. spec (`str`) – The specification from which to draw the list of color names; valid values are `'html4'`, `'css2'`, `'css21'` and `'css3'`. Default is `'css3'`.
Return type:	IntegerRGB

webcolors.name_to_rgb_percent(name, spec=u'css3')¶

Convert a color name to a 3-tuple of percentages suitable for use in an rgb() triplet specifying that color.

The color name will be normalized to lower-case before being looked up.

Examples:

>>> name_to_rgb_percent(u'white')
PercentRGB(red=u'100%', green=u'100%', blue=u'100%')
>>> name_to_rgb_percent(u'navy')
PercentRGB(red=u'0%', green=u'0%', blue=u'50%')
>>> name_to_rgb_percent(u'goldenrod')
PercentRGB(red=u'85.49%', green=u'64.71%', blue=u'12.5%')

Parameters:	name (`str`) – The color name to convert. spec (`str`) – The specification from which to draw the list of color names; valid values are `'html4'`, `'css2'`, `'css21'` and `'css3'`. Default is `'css3'`.
Return type:	PercentRGB

Conversion from hexadecimal color values to other formats¶

webcolors.hex_to_name(hex_value, spec=u'css3')¶

Convert a hexadecimal color value to its corresponding normalized color name, if any such name exists.

The hexadecimal value will be normalized before being looked up.

Examples:

>>> hex_to_name(u'#ffffff')
u'white'
>>> hex_to_name(u'#fff')
u'white'
>>> hex_to_name(u'#000080')
u'navy'
>>> hex_to_name(u'#daa520')
u'goldenrod'
>>> hex_to_name(u'#daa520', spec=u'html4')
Traceback (most recent call last):
    ...
ValueError: '#daa520' has no defined color name in html4.

Parameters:	hex_value (str) – The hexadecimal color value to convert. spec (`str`) – The specification from which to draw the list of color names; valid values are `'html4'`, `'css2'`, `'css21'` and `'css3'`. Default is `'css3'`.
Return type:	Unicode string

webcolors.hex_to_rgb(hex_value)¶

Convert a hexadecimal color value to a 3-tuple of integers suitable for use in an rgb() triplet specifying that color.

The hexadecimal value will be normalized before being converted.

Examples:

>>> hex_to_rgb(u'#fff')
IntegerRGB(red=255, green=255, blue=255)
>>> hex_to_rgb(u'#000080')
IntegerRGB(red=0, green=0, blue=128)

Parameters:	hex_value (`str`) – The hexadecimal color value to convert.
Return type:	IntegerRGB

webcolors.hex_to_rgb_percent(hex_value)¶

Convert a hexadecimal color value to a 3-tuple of percentages suitable for use in an rgb() triplet representing that color.

The hexadecimal value will be normalized before being converted.

Examples:

>>> hex_to_rgb_percent(u'#ffffff')
PercentRGB(red=u'100%', green=u'100%', blue=u'100%')
>>> hex_to_rgb_percent(u'#000080')
PercentRGB(red=u'0%', green=u'0%', blue=u'50%')

Parameters:	hex_value (`str`) – The hexadecimal color value to convert.
Return type:	PercentRGB

Conversions from integer `rgb()` triplets to other formats¶

webcolors.rgb_to_name(rgb_triplet, spec=u'css3')¶

Convert a 3-tuple of integers, suitable for use in an rgb() color triplet, to its corresponding normalized color name, if any such name exists.

To determine the name, the triplet will be converted to a normalized hexadecimal value.

Examples:

>>> rgb_to_name((255, 255, 255))
u'white'
>>> rgb_to_name((0, 0, 128))
u'navy'

Parameters:	rgb_triplet (3-tuple of `int`, or `IntegerRGB`) – The `rgb()` triplet spec (`str`) – The specification from which to draw the list of color names; valid values are `'html4'`, `'css2'`, `'css21'` and `'css3'`. Default is `'css3'`.
Return type:	Unicode string

webcolors.rgb_to_hex(rgb_triplet)¶

Convert a 3-tuple of integers, suitable for use in an rgb() color triplet, to a normalized hexadecimal value for that color.

Examples:

>>> rgb_to_hex((255, 255, 255))
u'#ffffff'
>>> rgb_to_hex((0, 0, 128))
u'#000080'

Parameters:	rgb_triplet (3-tuple of `int`, or `IntegerRGB`) – The `rgb()` triplet.
Return type:	Unicode string

webcolors.rgb_to_rgb_percent(rgb_triplet)¶

Convert a 3-tuple of integers, suitable for use in an rgb() color triplet, to a 3-tuple of percentages suitable for use in representing that color.

This function makes some trade-offs in terms of the accuracy of the final representation; for some common integer values, special-case logic is used to ensure a precise result (e.g., integer 128 will always convert to ‘50%’, integer 32 will always convert to ‘12.5%’), but for all other values a standard Python float is used and rounded to two decimal places, which may result in a loss of precision for some values.

Examples:

>>> rgb_to_rgb_percent((255, 255, 255))
PercentRGB(red=u'100%', green=u'100%', blue=u'100%')
>>> rgb_to_rgb_percent((0, 0, 128))
PercentRGB(red=u'0%', green=u'0%', blue=u'50%')
>>> rgb_to_rgb_percent((218, 165, 32))
PercentRGB(red=u'85.49%', green=u'64.71%', blue=u'12.5%')

Parameters:	rgb_triplet (3-tuple of `int`, or `IntegerRGB`) – The `rgb()` triplet.
Return type:	PercentRGB

Conversions from percentage `rgb()` triplets to other formats¶

webcolors.rgb_percent_to_name(rgb_percent_triplet, spec=u'css3')¶

Convert a 3-tuple of percentages, suitable for use in an rgb() color triplet, to its corresponding normalized color name, if any such name exists.

To determine the name, the triplet will be converted to a normalized hexadecimal value.

Examples:

>>> rgb_percent_to_name((u'100%', u'100%', u'100%'))
u'white'
>>> rgb_percent_to_name((u'0%', u'0%', u'50%'))
u'navy'
>>> rgb_percent_to_name((u'85.49%', u'64.71%', u'12.5%'))
u'goldenrod'

Parameters:	rgb_percent_triplet (3-tuple of `str`, or `PercentRGB`) – The `rgb()` triplet. spec (`str`) – The specification from which to draw the list of color names; valid values are `'html4'`, `'css2'`, `'css21'` and `'css3'`. Default is `'css3'`.
Return type:	Unicode string

webcolors.rgb_percent_to_hex(rgb_percent_triplet)¶

Convert a 3-tuple of percentages, suitable for use in an rgb() color triplet, to a normalized hexadecimal color value for that color.

Examples:

>>> rgb_percent_to_hex((u'100%', u'100%', u'0%'))
u'#ffff00'
>>> rgb_percent_to_hex((u'0%', u'0%', u'50%'))
u'#000080'
>>> rgb_percent_to_hex((u'85.49%', u'64.71%', u'12.5%'))
u'#daa520'

Parameters:	rgb_percent_triplet (3-tuple of `str`, or `PercentRGB`) – The `rgb()` triplet.
Return type:	`str`

webcolors.rgb_percent_to_rgb(rgb_percent_triplet)¶

Convert a 3-tuple of percentages, suitable for use in an rgb() color triplet, to a 3-tuple of integers suitable for use in representing that color.

Some precision may be lost in this conversion. See the note regarding precision for rgb_to_rgb_percent() for details.

Examples:

>>> rgb_percent_to_rgb((u'100%', u'100%', u'100%'))
IntegerRGB(red=255, green=255, blue=255)
>>> rgb_percent_to_rgb((u'0%', u'0%', u'50%'))
IntegerRGB(red=0, green=0, blue=128)
>>> rgb_percent_to_rgb((u'85.49%', u'64.71%', u'12.5%'))
IntegerRGB(red=218, green=165, blue=32)

Parameters:	rgb_percent_triplet (3-tuple of `str`, or `PercentRGB`) – The `rgb()` triplet.
Return type:	IntegerRGB

HTML5 color algorithms¶

Warning

There are two versions of the HTML5 standard. Although they have common origins and are extremely similar, one is a living document (maintained by WHATWG) and the other is a W3C Recommendation. The functions documented below implement the HTML5 color algorithms as given in section 2.4.6 of the W3C HTML5 Recommendation.

webcolors.html5_parse_simple_color(input)¶

Apply the HTML5 simple color parsing algorithm.

Note that input must be a Unicode string – on Python 2, bytestrings will not be accepted.

Examples:

>>> html5_parse_simple_color(u'#ffffff')
HTML5SimpleColor(red=255, green=255, blue=255)
>>> html5_parse_simple_color(u'#fff')
Traceback (most recent call last):
    ...
ValueError: An HTML5 simple color must be a string exactly seven characters long.

Parameters:	input (seven-character `str` on Python 3, `unicode` on Python 2, which must consist of exactly the character `#` followed by six hexadecimal digits) – The color to parse.
Return type:	HTML5SimpleColor

webcolors.html5_serialize_simple_color(simple_color)¶

Apply the HTML5 simple color serialization algorithm.

Examples:

>>> html5_serialize_simple_color((0, 0, 0))
u'#000000'
>>> html5_serialize_simple_color((255, 255, 255))
u'#ffffff'

Parameters:	simple_color (3-tuple of `int`, each in the range 0..255, or `IntegerRGB`) – The color to serialize.
Return type:	A valid lowercase simple color, which is a Unicode string exactly seven characters long, beginning with `#` and followed by six lowercase hexadecimal digits.

webcolors.html5_parse_legacy_color(input)¶

Apply the HTML5 legacy color parsing algorithm.

Note that, since this algorithm is intended to handle many types of malformed color values present in real-world Web documents, it is extremely forgiving of input, but the results of parsing inputs with high levels of “junk” (i.e., text other than a color value) may be surprising.

Note also that input must be a Unicode string – on Python 2, bytestrings will not be accepted.

Examples:

>>> html5_parse_legacy_color(u'black')
HTML5SimpleColor(red=0, green=0, blue=0)
>>> html5_parse_legacy_color(u'chucknorris')
HTML5SimpleColor(red=192, green=0, blue=0)
>>> html5_parse_legacy_color(u'Window')
HTML5SimpleColor(red=0, green=13, blue=0)

Parameters:	input (`str` on Python 3, `unicode` on Python 2) – The color to parse.
Return type:	HTML5SimpleColor

Module contents¶

Data types¶

Constants¶

Mappings from names to hexadecimal values¶

Mappings from hexadecimal values to names¶

Normalization functions¶

Conversions from color names to other formats¶

Conversion 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¶

Conversions from integer `rgb()` triplets to other formats¶

Conversions from percentage `rgb()` triplets to other formats¶