Commits

James Bennett committed 6f03370

Sync up examples and doctests.

  • Participants
  • Parent commits dda849e

Comments (0)

Files changed (2)

File docs/index.rst

 
    Examples::
 
-    >>> name_to_hex('white')
-    '#ffffff'
-    >>> name_to_hex('navy')
-    '#000080'
-    >>> name_to_hex('goldenrod')
-    '#daa520'
-    >>> name_to_hex('goldenrod', spec='html4')
-    Traceback (most recent call last):
-        ...
-    ValueError: 'goldenrod' is not defined as a named color in html4.
+       >>> name_to_hex('white')
+       '#ffffff'
+       >>> name_to_hex('navy')
+       '#000080'
+       >>> name_to_hex('goldenrod')
+       '#daa520'
+       >>> name_to_hex('goldenrod', spec='html4')
+       Traceback (most recent call last):
+           ...
+       ValueError: 'goldenrod' is not defined as a named color in html4.
 
    :param name: The color name to convert.
    :type name: str
        (255, 255, 255)
        >>> rgb_percent_to_rgb(('0%', '0%', '50%'))
        (0, 0, 128)
-       >>> webcolors.rgb_percent_to_rgb(('85.49%', '64.71%', '12.5%'))
+       >>> rgb_percent_to_rgb(('85.49%', '64.71%', '12.5%'))
        (218, 165, 32)
 
    :param rgb_percent_triplet: The ``rgb()`` triplet.

File webcolors.py

 """
-A simple library for working with the color names and color codes
-defined by the HTML and CSS specifications.
+Utility functions for with the color names and color value formats
+defined by the HTML and CSS specifications for use in documents on the
+Web.
 
-An overview of HTML and CSS colors
-----------------------------------
-
-Colors on the Web are specified in `the sRGB color space`_, where each
-color is made up of a red component, a green component and a blue
-component. This is useful because it maps (fairly) cleanly to the red,
-green and blue components of pixels on a computer display, and to the
-cone cells of a human eye, which come in three sets roughly
-corresponding to the wavelengths of light associated with red, green
-and blue.
-
-`The HTML 4 standard`_ defines two ways to specify sRGB colors:
-
-* A hash mark ('#') followed by three pairs of hexdecimal digits,
-  specifying values for red, green and blue components in that order;
-  for example, ``#0099cc``. Since each pair of hexadecimal digits can
-  express 256 different values, this allows up to 256**3 or 16,777,216
-  unique colors to be specified (though, due to differences in display
-  technology, not all of these colors may be clearly distinguished on
-  any given physical display).
-
-* A set of predefined color names which correspond to specific
-  hexadecimal values; for example, ``white``. HTML 4 defines sixteen
-  such colors.
-
-`The CSS 2 standard`_ allows any valid HTML 4 color specification, and
-adds three new ways to specify sRGB colors:
-
-* A hash mark followed by three hexadecimal digits, which is expanded
-  into three hexadecimal pairs by repeating each digit; thus ``#09c``
-  is equivalent to ``#0099cc``.
-
-* The string 'rgb', followed by parentheses, between which are three
-  numeric values each between 0 and 255, inclusive, which are taken to
-  be the values of the red, green and blue components in that order;
-  for example, ``rgb(0, 153, 204)``.
-
-* The same as above, except using percentages instead of numeric
-  values; for example, ``rgb(0%, 60%, 80%)``.
-
-`The CSS 2.1 revision`_ does not add any new methods of specifying
-sRGB colors, but does add one additional named color.
-
-`The CSS 3 color module`_ (currently a W3C Candidate Recommendation)
-adds one new way to specify sRGB colors:
-
-* A hue-saturation-lightness triple (HSL), using the construct
-  ``hsl()``.
-
-It also adds support for variable opacity of colors, by allowing the
-specification of alpha-channel information, through the ``rgba()`` and
-``hsla()`` constructs, which are identical to ``rgb()`` and ``hsl()``
-with one exception: a fourth value is supplied, indicating the level
-of opacity from ``0.0`` (completely transparent) to ``1.0``
-(completely opaque). Though not technically a color, the keyword
-``transparent`` is also made available in lieu of a color value, and
-corresponds to ``rgba(0,0,0,0)``.
-
-Additionally, CSS3 defines a new set of color names; this set is taken
-directly from the named colors defined for SVG (Scalable Vector
-Graphics) markup, and is a proper superset of the named colors defined
-in CSS 2.1. This set also has significant overlap with traditional X11
-color sets as defined by the ``rgb.txt`` file on many Unix and
-Unix-like operating systems, though the correspondence is not exact;
-the set of X11 colors is not standardized, and the set of CSS3 colors
-contains some definitions which diverge significantly from customary
-X11 definitions (for example, CSS3's ``green`` is not equivalent to
-X11's ``green``; the value which X11 designates ``green`` is
-designated ``lime`` in CSS3).
-
-.. _the sRGB color space: http://www.w3.org/Graphics/Color/sRGB
-.. _The HTML 4 standard: http://www.w3.org/TR/html401/types.html#h-6.5
-.. _The CSS 2 standard: http://www.w3.org/TR/REC-CSS2/syndata.html#value-def-color
-.. _The CSS 2.1 revision: http://www.w3.org/TR/CSS21/
-.. _The CSS 3 color module: http://www.w3.org/TR/css3-color/
 
 What this module supports
 -------------------------
 
-The mappings and functions within this module support the following
-methods of specifying sRGB colors, and conversions between them:
+This module supports the following methods of specifying sRGB colors,
+and conversions between them:
 
 * Six-digit hexadecimal.
 
 
 * Percentage ``rgb()`` triplet.
 
-* Varying selections of predefined color names (see below).
+* Varying selections of predefined color names.
 
 This module does not support ``hsl()`` triplets, nor does it support
 opacity/alpha-channel information via ``rgba()`` or ``hsla()``.
 If you need to convert between RGB-specified colors and HSL-specified
 colors, or colors specified via other means, consult `the colorsys
 module`_ in the Python standard library, which can perform conversions
-amongst several common color spaces.
+amongst several common color systems.
 
 .. _the colorsys module: http://docs.python.org/library/colorsys.html
 
-Normalization
--------------
+
+Normalization and conventions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 For colors specified via hexadecimal values, this module will accept
 input in the following formats:
 
-* A hash mark (#) followed by three hexadecimal digits, where letters
-  may be upper- or lower-case.
+* A hash mark (#) followed by three hexadecimal digits, where digits
+  A-F may be upper- or lower-case.
 
-* A hash mark (#) followed by six hexadecimal digits, where letters
+* A hash mark (#) followed by six hexadecimal digits, where digits A-F
   may be upper- or lower-case.
 
 For output which consists of a color specified via hexadecimal values,
 before returning a result in another format, this module always
 normalizes such values to the following format:
 
-* A hash mark (#) followed by six hexadecimal digits, with letters
+* A hash mark (#) followed by six hexadecimal digits, with digits A-F
   forced to lower-case.
 
-The function ``normalize_hex()`` in this module can be used to perform
-this normalization manually if desired; see its documentation for an
-explanation of the normalization process.
+The function :func:`normalize_hex` in this module can be used to
+perform this normalization manually if desired.
 
 For colors specified via predefined names, this module will accept
 input in the following formats:
 
 * An entirely lower-case name, such as ``aliceblue``.
 
-* A name using initial capitals, such as ``AliceBlue``.
+* A name using CamelCase, such as ``AliceBlue``.
 
 For output which consists of a color specified via a predefined name,
 and for functions which perform intermediate conversion to a
 predefined name before returning a result in another format, this
 module always normalizes such values to be entirely lower-case.
 
+For purposes of identifying the specification from which to draw the
+selection of defined color names, this module recognizes the following
+identifiers:
+
+``html4``
+    The HTML 4 named colors.
+
+``css2``
+    The CSS 2 named colors.
+
+``css21``
+    The CSS 2.1 named colors.
+
+``css3``
+    The CSS 3/SVG named colors.
+
+The CSS 1 specification is not represented here, as it merely
+"suggested" a set of color names, and declined to provide values for
+them.
+
+
 Mappings of color names
 -----------------------
 
 
     Examples:
 
+    >>> normalize_hex('#0099cc')
+    '#0099cc'
+    >>> normalize_hex('#0099CC')
+    '#0099cc'
     >>> normalize_hex('#09c')
     '#0099cc'
-    >>> normalize_hex('#0099cc')
-    '#0099cc'
     >>> normalize_hex('#09C')
     '#0099cc'
-    >>> normalize_hex('#0099CC')
-    '#0099cc'
     >>> normalize_hex('0099cc')
     Traceback (most recent call last):
         ...
     ValueError: '0099cc' is not a valid hexadecimal color value.
-    >>> normalize_hex('#0099QX')
-    Traceback (most recent call last):
-        ...
-    ValueError: '#0099QX' is not a valid hexadecimal color value.
-    >>> normalize_hex('foobarbaz')
-    Traceback (most recent call last):
-        ...
-    ValueError: 'foobarbaz' is not a valid hexadecimal color value.
-    >>> normalize_hex('#0')
-    Traceback (most recent call last):
-        ...
-    ValueError: '#0' is not a valid hexadecimal color value.
 
     """
     try:
 
     Examples:
 
-    >>> name_to_hex('deepskyblue')
-    '#00bfff'
-    >>> name_to_hex('DeepSkyBlue')
-    '#00bfff'
-    >>> name_to_hex('white', spec='html4')
+    >>> name_to_hex('white')
     '#ffffff'
-    >>> name_to_hex('white', spec='css2')
-    '#ffffff'
-    >>> name_to_hex('white', spec='css21')
-    '#ffffff'
-    >>> name_to_hex('white', spec='css3')
-    '#ffffff'
-    >>> name_to_hex('white', spec='css4')
+    >>> name_to_hex('navy')
+    '#000080'
+    >>> name_to_hex('goldenrod')
+    '#daa520'
+    >>> name_to_hex('goldenrod', spec='html4')
     Traceback (most recent call last):
         ...
-    TypeError: 'css4' is not a supported specification for color name lookups; supported specifications are: html4, css2, css21, css3.
-    >>> name_to_hex('deepskyblue', spec='css2')
-    Traceback (most recent call last):
-        ...
-    ValueError: 'deepskyblue' is not defined as a named color in css2.
+    ValueError: 'goldenrod' is not defined as a named color in html4.
 
     """
     if spec not in SUPPORTED_SPECIFICATIONS:
 
     Examples:
 
+    >>> name_to_rgb('white')
+    (255, 255, 255)
     >>> name_to_rgb('navy')
     (0, 0, 128)
-    >>> name_to_rgb('cadetblue')
-    (95, 158, 160)
-    >>> name_to_rgb('cadetblue', spec='html4')
-    Traceback (most recent call last):
-        ...
-    ValueError: 'cadetblue' is not defined as a named color in html4.
+    >>> name_to_rgb('goldenrod')
+    (218, 165, 32)
 
     """
     return hex_to_rgb(name_to_hex(name, spec=spec))
 
     Examples:
 
+    >>> hex_to_name('#ffffff')
+    'white'
+    >>> hex_to_name('#fff')
+    'white'
     >>> hex_to_name('#000080')
     'navy'
-    >>> hex_to_name('#000080', spec='html4')
-    'navy'
-    >>> hex_to_name('#000080', spec='css2')
-    'navy'
-    >>> hex_to_name('#000080', spec='css21')
-    'navy'
-    >>> hex_to_name('#8b4513')
-    'saddlebrown'
-    >>> hex_to_name('#8b4513', spec='html4')
+    >>> hex_to_name('#daa520')
+    'goldenrod'
+    >>> hex_to_name('#daa520', spec='html4')
     Traceback (most recent call last):
         ...
-    ValueError: '#8b4513' has no defined color name in html4.
-    >>> hex_to_name('#8b4513', spec='css4')
-    Traceback (most recent call last):
-        ...
-    TypeError: 'css4' is not a supported specification for color name lookups; supported specifications are: html4, css2, css21, css3.
+    ValueError: '#daa520' has no defined color name in html4.
 
     """
     if spec not in SUPPORTED_SPECIFICATIONS:
 
     Examples:
 
+    >>> hex_to_rgb('#fff')
+    (255, 255, 255)
     >>> hex_to_rgb('#000080')
     (0, 0, 128)
-    >>> hex_to_rgb('#ffff00')
-    (255, 255, 0)
-    >>> hex_to_rgb('#f00')
-    (255, 0, 0)
-    >>> hex_to_rgb('#deb887')
-    (222, 184, 135)
 
     """
     hex_digits = normalize_hex(hex_value)
 
     Examples:
 
-    >>> rgb_to_name((0, 0, 0))
-    'black'
+    >>> rgb_to_name((255, 255, 255))
+    'white'
     >>> rgb_to_name((0, 0, 128))
     'navy'
-    >>> rgb_to_name((95, 158, 160))
-    'cadetblue'
 
     """
     return hex_to_name(rgb_to_hex(rgb_triplet), spec=spec)
     '#ffffff'
     >>> rgb_to_hex((0, 0, 128))
     '#000080'
-    >>> rgb_to_hex((33, 56, 192))
-    '#2138c0'
 
     """
     return '#%02x%02x%02x' % rgb_triplet
     ('100%', '100%', '100%')
     >>> rgb_to_rgb_percent((0, 0, 128))
     ('0%', '0%', '50%')
-    >>> rgb_to_rgb_percent((33, 56, 192))
-    ('12.94%', '21.96%', '75.29%')
-    >>> rgb_to_rgb_percent((64, 32, 16))
-    ('25%', '12.5%', '6.25%')
+    >>> rgb_to_rgb_percent((218, 165, 32))
+    ('85.49%', '64.71%', '12.5%')
 
     """
     # In order to maintain precision for common values,
 
     Examples:
 
-    >>> rgb_percent_to_name(('0%', '0%', '0%'))
-    'black'
+    >>> rgb_percent_to_name(('100%', '100%', '100%'))
+    'white'
     >>> rgb_percent_to_name(('0%', '0%', '50%'))
     'navy'
     >>> rgb_percent_to_name(('85.49%', '64.71%', '12.5%'))
     (255, 255, 255)
     >>> rgb_percent_to_rgb(('0%', '0%', '50%'))
     (0, 0, 128)
-    >>> rgb_percent_to_rgb(('25%', '12.5%', '6.25%'))
-    (64, 32, 16)
-    >>> rgb_percent_to_rgb(('12.94%', '21.96%', '75.29%'))
-    (33, 56, 192)
+    >>> rgb_percent_to_rgb(('85.49%', '64.71%', '12.5%'))
+    (218, 165, 32)
 
     """
     return tuple(map(_percent_to_integer, rgb_percent_triplet))