Permalink
Browse files

Document the color3 module.

  • Loading branch information...
1 parent 40d1820 commit dd04504e586e1a1a7672004851772ff1bd8127a3 @SimonSapin SimonSapin committed Mar 31, 2012
Showing with 75 additions and 20 deletions.
  1. +48 −0 docs/css3.rst
  2. +1 −0 docs/index.rst
  3. +6 −3 docs/parsing.rst
  4. +13 −13 tinycss/color3.py
  5. +1 −1 tinycss/css21.py
  6. +1 −1 tinycss/speedups.pyx
  7. +5 −2 tinycss/token_data.py
View
@@ -0,0 +1,48 @@
+CSS 3 Modules
+=============
+
+.. module:: tinycss.selectors3
+
+Selectors 3
+-----------
+
+TODO
+
+
+.. module:: tinycss.color3
+
+Color 3
+-------
+
+This module implements parsing for the *<color>* values defined in
+`CSS 3 Color <http://www.w3.org/TR/css3-color/>`_.
+
+The (deprecated) CSS2 system colors are not supported, but you can
+easily test for them if you want as they are simple ``IDENT`` tokens::
+
+ if token.type == 'IDENT' and token.value == 'ButtonText':
+ return ...
+
+Other values types are supported:
+
+* Basic, extended (X11) and transparent color keywords;
+* 3-digit and 6-digit hexadecimal notations;
+* ``rgb()``, ``rgba()``, ``hsl()`` and ``hsla()`` functional notations.
+* ``currentColor``
+
+This module does not integrate with a parser class. Instead, it provides
+a function that can help parse property values, as
+:attr:`.css21.Declaration.value` is provided as a list of unparsed tokens.
+
+
+.. autofunction:: parse_color
+.. autofunction:: parse_color_string
+.. autoclass:: RGBA
+
+
+.. module:: tinycss.page3
+
+Paged Media 3
+-------------
+
+TODO
View
@@ -47,6 +47,7 @@ Documentation
:maxdepth: 2
parsing
+ css3
extending
hacking
changelog
View
@@ -59,12 +59,15 @@ Parsed objects
--------------
These data structures make up the results of the various parsing methods.
-All of these objects have :obj:`line` and :obj:`column` attributes (not
-repeated every time fore brevity) that indicate where in the CSS source this
-object was read.
.. autoclass:: Stylesheet()
.. autoclass:: ParseError()
+
+.. note::
+ All subsequent objects have :obj:`line` and :obj:`column` attributes (not
+ repeated every time fore brevity) that indicate where in the CSS source
+ this object was read.
+
.. autoclass:: RuleSet()
.. autoclass:: ImportRule()
.. autoclass:: MediaRule()
View
@@ -24,8 +24,7 @@
class RGBA(collections.namedtuple('RGBA', ['red', 'green', 'blue', 'alpha'])):
"""An RGBA color.
- A tuple of four floats in the 0..1 range: ``(r, g, b, a)``
-
+ A tuple of four floats in the 0..1 range: ``(r, g, b, a)``.
Also has ``red``, ``green``, ``blue`` and ``alpha`` attributes to access
the same values.
@@ -35,6 +34,9 @@ class RGBA(collections.namedtuple('RGBA', ['red', 'green', 'blue', 'alpha'])):
def parse_color_string(css_string):
"""Parse a CSS string as a color value.
+ This is a convenience wrapper around :func:`parse_color` in case you
+ have a string that is not from a CSS stylesheet.
+
:param css_string:
An unicode string in CSS syntax.
:returns:
@@ -49,19 +51,17 @@ def parse_color_string(css_string):
def parse_color(token):
"""Parse single token as a color value.
- The (deprecated) CSS2 system colors are not supported, but you can
- easily test for them if you want as they are simple IDENT tokens.
-
:param token:
- A single :class:`Token` or :class:`ContainerToken`, as found eg.
- in a property value.
+ A single :class:`~.token_data.Token` or
+ :class:`~.token_data.ContainerToken`, as found eg. in a
+ property value.
:returns:
- * None, if the string is not a valid CSS 3 color value.
+ * ``None``, if the token is not a valid CSS 3 color value.
(No exception is raised.)
- * For the currentColor keyword: the string 'currentColor'
- * Every other values (including HSL and HSLA) is converted to RGBA
- and returned as an :class:`RGBA` object (a 4-tuple with attribute
- access).
+ * For the *currentColor* keyword: the string ``'currentColor'``
+ * Every other values (including keywords, HSL and HSLA) is converted
+ to RGBA and returned as an :class:`RGBA` object (a 4-tuple with
+ attribute access).
The alpha channel is clipped to [0, 1], but R, G, or B can be
out of range (eg. ``rgb(-51, 306, 0)`` is represented as
``(-.2, 1.2, 0, 1)``.)
@@ -122,7 +122,7 @@ def parse_rgb(args, alpha):
def parse_hsl(args, alpha):
"""
If args is a list of 1 INTEGER token and 2 PERCENTAGE tokens,
- return RGBA values as a tuple of 3 floats in 0..1.
+ return RGB values as a tuple of 3 floats in 0..1.
Otherwise, return None.
"""
types = [arg.type for arg in args]
View
@@ -185,7 +185,7 @@ class Declaration(object):
unknown or unsupported properties or values, and fall back
on any previous declaration.
- :mod:`tinycss.colors3` parses color values, but other values
+ :mod:`tinycss.color3` parses color values, but other values
will need specific parsing/validation code.
.. attribute:: priority
@@ -24,7 +24,7 @@ COMPILED_TOKEN_INDEXES = dict(
cdef class CToken:
"""A token built by the Cython speedups. Identical to
- :class:`~tinycss.token_data.Token`.
+ :class:`~.token_data.Token`.
"""
is_container = False
@@ -197,8 +197,8 @@ class Token(object):
``IDENT``
An identifier: a name that does not start with a digit.
- A name is a sequence of letters, digits, escaped characters
- and non-ASCII characters. Eg: ``margin-left``
+ A name is a sequence of letters, digits, ``_``, ``-``, escaped
+ characters and non-ASCII characters. Eg: ``margin-left``
``HASH``
``#`` followed immediately by a name. Eg: ``#ff8800``
@@ -235,6 +235,9 @@ class Token(object):
``DELIM``
A single character not matched in another token. Eg: ``,``
+ See the source of the :mod:`.token_data` module for the precise
+ regular expressions that match various tokens.
+
Note that other token types exist in the early tokenization steps,
but these are ignored, are syntax errors, or are later transformed
into :class:`ContainerToken` or :class:`FunctionToken`.

0 comments on commit dd04504

Please sign in to comment.