Polish the docs for CSS 2.1

Author: SimonSapin

README.rst

@@ -15,7 +15,7 @@ It is designed to be easy to extend for new CSS modules.
 Quick facts:
 
 * Free software: BSD licensed
-* Compatible Python 2.6+ and 3.x
+* Compatible with Python 2.6+ and 3.x
 * `Latest documentation <http://packages.python.org/tinycss/>`_
 * Source, issues and pull requests `on Github
 <https://github.com/SimonSapin/tinycss/>`_

docs/parsing.rst

@@ -26,79 +26,68 @@ all the parsed content.
 Parsers
 -------
 
-Parsers are subclasses of :class:`tinycss.css21.CSS21Parser`. Various subclasses
-add support for more syntax. You can choose which features to enable
-by making a new parser class with multiple inheritance, but there is also
-a convenience function to do that:
+Parsers are subclasses of :class:`tinycss.css21.CSS21Parser`. Various
+subclasses add support for more syntax. You can choose which features to
+enable by making a new parser class with multiple inheritance, but there
+is also a convenience function to do that:
 
 .. module:: tinycss
 
 .. autofunction:: make_parser(*base_classes, with_selectors3=False, with_page3=False, **kwargs)
 
 
-.. module:: tinycss.core
+.. module:: tinycss.css21
 
 Parsing a stylesheet
 ~~~~~~~~~~~~~~~~~~~~
 
 Parser classes have three different methods to parse CSS stylesheet,
 depending on whether you have a file, a byte string, or an Unicode string.
 
-.. automethod:: CoreParser.parse_stylesheet_file
-.. automethod:: CoreParser.parse_stylesheet_bytes
-.. automethod:: CoreParser.parse_stylesheet
+.. automethod:: CSS21Parser.parse_stylesheet_file
+.. automethod:: CSS21Parser.parse_stylesheet_bytes
+.. automethod:: CSS21Parser.parse_stylesheet
 
 
 Parsing a ``style`` attribute
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. automethod:: CoreParser.parse_style_attr
+.. automethod:: CSS21Parser.parse_style_attr
 
 
-Tokens
-------
+Parsed objects
+--------------
 
-Some parts of a stylesheet (such as property values) are not parsed
-by tinycss. They appear as tokens instead.
+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.
 
-tinycss does not know which properties and which values a given User Agent
-wants to support: it is the UA’s responsibility to ignore unknown and
-unsupported values, and fall back on any previous declaration.
+.. autoclass:: Stylesheet()
+.. autoclass:: ParseError()
+.. autoclass:: RuleSet()
+.. autoclass:: ImportRule()
+.. autoclass:: MediaRule()
+.. autoclass:: PageRule()
+.. autoclass:: Declaration()
+
+
+Tokens
+------
+
+Some parts of a stylesheet (such as selectors in CSS 2.1 or property values)
+are not parsed by tinycss. They appear as tokens instead.
 
 .. module:: tinycss.token_data
 
 .. autoclass:: Token()
 .. autoclass:: tinycss.speedups.CToken()
 .. autoclass:: ContainerToken()
 
+ .. autoattribute:: as_css
+
  .. method:: __iter__, __len__
 
  Shortcuts for accessing :attr:`content`.
 
 .. autoclass:: FunctionToken()
-
-
-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.
-
-.. currentmodule:: tinycss.core
-
-.. autoclass:: Stylesheet()
-.. autoclass:: ParseError()
-.. autoclass:: RuleSet()
-.. autoclass:: Declaration()
-
-.. module:: tinycss.css21
-
-.. autoclass:: PropertyDeclaration()
-.. autoclass:: PageRule()
-.. autoclass:: MediaRule()
-.. autoclass:: ImportRule()

tinycss/css21.py

@@ -41,7 +41,9 @@ class Stylesheet(object):
 
  .. attribute:: rules
 
- A mixed list of :class:`RuleSet` and various at-rules, in source order.
+ A mixed list, in source order, of :class:`RuleSet` and various
+ at-rules such as :class:`ImportRule`, :class:`MediaRule`
+ and :class:`PageRule`.
  Use their :obj:`at_keyword` attribute to distinguish them.
 
  .. attribute:: errors
@@ -74,7 +76,7 @@ def pretty(self): # pragma: no cover
 classParseError(ValueError):
 """Details about a CSS syntax error. Usually indicates that something
  (a rule or a declaration) was ignored and will not appear as a parsed
-objects.
+object.
 
  .. attribute:: line
 
@@ -161,13 +163,12 @@ class RuleSet(object):
 
  .. attribute:: selector
 
-A (possibly empty) :class:`ContainerToken` object.
+The selecor as a :class:`~tinycss.token_data.ContainerToken` object.
  In CSS 3 terminology, this is actually a selector group.
 
  .. attribute:: declarations
 
- The list of :class:`Declaration` as returned by
- :func:`parse_declaration_list`, in source order.
+ The list of :class:`Declaration`, in source order.
 
  """
 def__init__(self, selector, declarations, line, column):
@@ -201,19 +202,33 @@ class Declaration(object):
 
  .. attribute:: value
 
- The property value: a list of tokens as returned by
- :func:`parse_value`.
+ The property value as a :class:`~tinycss.token_data.ContainerToken`.
+
+ The value is not parsed. UAs using tinycss may only support
+ some properties or some values and tinycss does not know which.
+ They need to parse values themselves and ignore declarations with
+ unknown or unsupported properties or values, and fall back
+ on any previous declaration.
+
+ :mod:`tinycss.colors3` parses color values, but other values
+ will need specific parsing/validation code.
+
+ .. attribute:: priority
+
+ Either the string ``'important'`` or ``None``.
 
  """
-def__init__(self, name, value, line, column):
+def__init__(self, name, value, priority, line, column):
 self.name=name
 self.value=value
+self.priority=priority
 self.line=line
 self.column=column
 
 def__repr__(self): # pragma: no cover
+priority=' !'+self.priorityifself.priorityelse''
 return ('<{0.__class__.__name__}{0.line}:{0.column}'
-'{0.name}:{0.value.as_css}>'.format(self))
+'{0.name}:{0.value.as_css}{1}>'.format(self, priority))
 
 defpretty(self): # pragma: no cover
 """Return an indented string representation for debugging"""
@@ -224,26 +239,6 @@ def pretty(self): # pragma: no cover
 return'\n'.join(lines)
 
 
-classPropertyDeclaration(Declaration):
-"""A CSS 2.1 property declaration.
-
- Same as :class:`Declaration` with an additional attribute:
-
- .. attribute:: priority
-
- Either the string ``'important'`` or ``None``.
-
- """
-def__init__(self, name, value, priority, line, column):
-super(PropertyDeclaration, self).__init__(name, value, line, column)
-self.priority=priority
-
-def__repr__(self): # pragma: no cover
-priority=' !'+self.priorityifself.priorityelse''
-return ('<{0.__class__.__name__}{0.line}:{0.column}'
-'{0.name}:{0.value.as_css}{1}>'.format(self, priority))
-
-
 classPageRule(object):
 """A parsed CSS 2.1 @page rule.
 
@@ -265,11 +260,11 @@ class PageRule(object):
 
  .. attribute:: declarations
 
- A list of :class:`PropertyDeclaration`
+ A list of :class:`Declaration`, in source order.
 
  .. attribute:: at_rules
 
- The list of parsed at-rules inside the @page block.
+ The list of parsed at-rules inside the @page block, in source order.
  Always empty for CSS 2.1.
 
  """
@@ -303,7 +298,8 @@ class MediaRule(object):
 
  .. attribute:: rules
 
- The list rulesets and at-rules inside the @media block.
+ The list :class:`RuleSet` and various at-rules inside the @media
+ block, in source order.
 
  """
 at_keyword='@media'
@@ -390,11 +386,11 @@ class CSS21Parser(object):
 # User API:
 
 defparse_stylesheet_file(self, css_file, protocol_encoding=None,
-linking_encoding=None, document_encoding=None):
+linking_encoding=None, document_encoding=None):
 """Parse a stylesheet from a file or filename.
 
-The character encoding is determined as in
- :meth:`parse_stylesheet_bytes`.
+Character encoding-related parameters and behavior are the same
+as in :meth:`parse_stylesheet_bytes`.
 
  :param css_file:
  Either a file (any object with a :meth:`~file.read` method)
@@ -417,6 +413,8 @@ def parse_stylesheet_bytes(self, css_bytes, protocol_encoding=None,
 
  The character encoding is determined from the passed metadata and the
  ``@charset`` rule in the stylesheet (if any).
+ If no encoding information is available or decoding fails,
+ decoding defaults to UTF-8 and then fall back on ISO-8859-1.
 
  :param css_bytes:
  A CSS stylesheet as a byte string.
@@ -428,8 +426,6 @@ def parse_stylesheet_bytes(self, css_bytes, protocol_encoding=None,
  (if any)
  :param document_encoding:
  Encoding of the referring style sheet or document (if any)
- :raises:
- :class:`UnicodeDecodeError` if decoding failed
  :return:
  A :class:`Stylesheet`.
 
@@ -467,8 +463,8 @@ def parse_style_attr(self, css_source):
  :param css_source:
  The attribute value, as an unicode string.
  :return:
- A tuple of the list of valid :class:`Declaration` and a list
- of :class:`ParseError`.
+ A tuple of the list of valid :class:`Declaration` and
+a list of :class:`ParseError`.
  """
 returnself.parse_declaration_list(tokenize_grouped(css_source))
 
@@ -711,7 +707,7 @@ def parse_page_block(self, body, errors):
  :returns:
  A tuple of:
 
- * A list of :class:`PropertyDeclaration`
+ * A list of :class:`Declaration`
  * A list of parsed at-rules (empty for CSS 2.1)
  * A list of :class:`ParseError`
 
@@ -864,7 +860,7 @@ def parse_declaration(self, tokens):
 value, priority=self.parse_value_priority(value)
 value=ContainerToken(
 'VALUES', '', '', value, value[0].line, value[0].column)
-returnPropertyDeclaration(
+returnDeclaration(
 property_name, value, priority, name_token.line, name_token.column)
 
 defparse_value_priority(self, original_value):

tinycss/decoding.py

@@ -34,6 +34,8 @@ def decode(css_bytes, protocol_encoding=None,
 """
  Determine the character encoding from the passed metadata and the
  ``@charset`` rule in the stylesheet (if any); and decode accordingly.
+ If no encoding information is available or decoding fails,
+ decoding defaults to UTF-8 and then fall back on ISO-8859-1.
 
  :param css_bytes:
  a CSS stylesheet as a byte string
@@ -45,8 +47,6 @@ def decode(css_bytes, protocol_encoding=None,
  (if any)
  :param document_encoding:
  Encoding of the referring style sheet or document (if any)
- :raises:
- :class:`UnicodeDecodeError` if decoding failed
  :return:
  A tuple of an Unicode string, with any BOM removed, and the
  encoding that was used.

tinycss/token_data.py

@@ -203,9 +203,6 @@ class Token(object):
  ``HASH``
  ``#`` followed immediately by a name. Eg: ``#ff8800``
 
- ``FUNCTION``
- An identifier followed immediately by ``(``. Eg: ``rgba(``
-
  ``ATKEYWORD``
  ``@`` followed immediately by an identifier. Eg: ``@page``
 
@@ -250,16 +247,18 @@ class Token(object):
 
  The parsed value:
 
- * All backslash-escapes are unescaped.
  * INTEGER, NUMBER, PERCENTAGE or DIMENSION tokens: the numeric value
  as an int or float.
  * STRING tokens: the unescaped string without quotes
  * URI tokens: the unescaped URI without quotes or
  ``url(`` and ``)`` markers.
- * IDENT, ATKEYWORD, HASH or FUNCTION tokens: the unescaped token,
- with ``@``, ``#`` or ``(`` markers left as-is
+ * IDENT, ATKEYWORDor HASH tokens: the unescaped token,
+ with ``@``or ``#`` markers left as-is
  * Other tokens: same as :attr:`as_css`
 
+ *Unescaped* refers to the various escaping methods based on the
+ backslash ``\`` character in CSS syntax.
+
  .. attribute:: unit
 
  * DIMENSION tokens: the normalized (unescaped, lower-case)
@@ -311,11 +310,13 @@ class ContainerToken(object):
 
  .. attribute:: css_start
 
- The string for the opening token as it was read from the CSS source
+ The string for the opening token as it was read from the CSS source.
+ Eg: ``{``
 
  .. attribute:: css_end
 
  The string for the closing token as it was read from the CSS source
+ Eg: ``}``
 
  .. attribute:: content