Skip to content
Browse files

Document the selectors3 module.

  • Loading branch information...
1 parent 30218e5 commit 91f41b0bb3aba8fa6491ca2a77d8aa65628cf6b5 @SimonSapin committed Mar 31, 2012
Showing with 53 additions and 34 deletions.
  1. +7 −2 docs/css3.rst
  2. +1 −4 docs/parsing.rst
  3. +16 −16 tinycss/css21.py
  4. +1 −1 tinycss/page3.py
  5. +28 −11 tinycss/selectors3.py
View
9 docs/css3.rst
@@ -6,7 +6,13 @@ CSS 3 Modules
Selectors 3
-----------
-TODO
+This module is based on `lxml.cssselect <http://lxml.de/cssselect.html>`_.
+Importing :mod:`tinycss.selectors3` without lxml installed will raise an
+:exc:`~exceptions.ImportError`.
+
+.. autoclass:: CSSSelectors3Parser
+.. autoclass:: Selector
+ :members: match
.. module:: tinycss.color3
@@ -34,7 +40,6 @@ 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
View
5 docs/parsing.rst
@@ -45,10 +45,7 @@ Parser classes have three different methods to parse CSS stylesheet,
depending on whether you have a file, a byte string, or an Unicode string.
.. autoclass:: CSS21Parser
-
- .. automethod:: parse_stylesheet_file
- .. automethod:: parse_stylesheet_bytes
- .. automethod:: parse_stylesheet
+ :members: parse_stylesheet_file, parse_stylesheet_bytes, parse_stylesheet
Parsing a ``style`` attribute
View
32 tinycss/css21.py
@@ -47,7 +47,7 @@ class Stylesheet(object):
.. attribute:: errors
- A list of :class:`ParseError`. Invalid rules and declarations
+ A list of :exc:`ParseError`. Invalid rules and declarations
are ignored, with the details logged in this list.
.. attribute:: encoding
@@ -431,7 +431,7 @@ def parse_style_attr(self, 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 list of :exc:`ParseError`.
"""
return self.parse_declaration_list(tokenize_grouped(css_source))
@@ -443,7 +443,7 @@ def parse_rules(self, tokens, errors, context):
:param tokens:
An iterable of tokens.
:param errors:
- A list where to append encountered :class:`ParseError`
+ A list where to append encountered :exc:`ParseError`
:param context:
Either 'stylesheet' or an at-keyword such as '@media'.
(Some at-rules are only allowed in some contexts.)
@@ -483,7 +483,7 @@ def read_at_rule(self, at_keyword_token, tokens):
:return:
An unparsed :class:`AtRule`
:raises:
- :class:`ParseError` if the head is invalid for the core grammar.
+ :exc:`ParseError` if the head is invalid for the core grammar.
The body is **not** validated. See :class:`AtRule`.
"""
@@ -533,7 +533,7 @@ def parse_at_rule(self, rule, previous_rules, errors, context):
Either 'stylesheet' or an at-keyword such as '@media'.
(Some at-rules are only allowed in some contexts.)
:raises:
- :class:`ParseError` if the rule is invalid.
+ :exc:`ParseError` if the rule is invalid.
:return:
A parsed at-rule or None (ignore)
@@ -613,7 +613,7 @@ def parse_media(self, tokens):
:param tokens:
An non-empty iterable of tokens
:raises:
- :class:`ParseError` on invalid media types/queries
+ :exc:`ParseError` on invalid media types/queries
:returns:
For CSS 2.1, a list of media types as strings
"""
@@ -649,7 +649,7 @@ def parse_page_selector(self, head):
A page selector. For CSS 2.1, this is 'first', 'left', 'right'
or None.
:raises:
- :class:`ParseError` on invalid selectors
+ :exc:`ParseError` on invalid selectors
"""
if not head:
@@ -670,13 +670,13 @@ def parse_page_block(self, body, errors):
:param body:
The ``body`` attribute of an unparsed :class:`AtRule`.
:param errors:
- A list where to append encountered :class:`ParseError`
+ A list where to append encountered :exc:`ParseError`
:returns:
A tuple of:
* A list of :class:`Declaration`
* A list of parsed at-rules (empty for CSS 2.1)
- * A list of :class:`ParseError`
+ * A list of :exc:`ParseError`
"""
at_rules = []
@@ -716,10 +716,10 @@ def parse_ruleset(self, first_token, tokens):
for one ruleset.
:return:
a tuple of a :class:`RuleSet` and an error list.
- The errors are recovered :class:`ParseError` in declarations.
+ The errors are recovered :exc:`ParseError` in declarations.
(Parsing continues from the next declaration on such errors.)
:raises:
- :class:`ParseError` if the selector is invalid for the
+ :exc:`ParseError` if the selector is invalid for the
core grammar.
Note a that a selector can be valid for the core grammar but
not for CSS 2.1 or another level.
@@ -756,7 +756,7 @@ def parse_declaration_list(self, tokens):
of the block, as marked by a '}'.
:return:
a tuple of the list of valid :class`Declaration` and a list
- of :class:`ParseError`
+ of :exc:`ParseError`
"""
# split at ';'
@@ -795,7 +795,7 @@ def parse_declaration(self, tokens):
:returns:
a :class:`Declaration`
:raises:
- :class:`ParseError` if the tokens do not match the 'declaration'
+ :exc:`ParseError` if the tokens do not match the 'declaration'
production of the core grammar.
"""
@@ -857,7 +857,7 @@ def parse_value(self, tokens):
a list of tokens with white space removed at the start and end,
but not in the middle.
:raises:
- :class:`ParseError` if there is any invalid token for the 'value'
+ :exc:`ParseError` if there is any invalid token for the 'value'
production of the core grammar.
"""
@@ -880,7 +880,7 @@ def parse_value(self, tokens):
def validate_block(self, tokens, context):
"""
:raises:
- :class:`ParseError` if there is any invalid token for the 'block'
+ :exc:`ParseError` if there is any invalid token for the 'block'
production of the core grammar.
:param tokens: an iterable of tokens
:param context: a string for the 'unexpected in ...' message
@@ -896,7 +896,7 @@ def validate_block(self, tokens, context):
def validate_any(self, token, context):
"""
:raises:
- :class:`ParseError` if this is an invalid token for the
+ :exc:`ParseError` if this is an invalid token for the
'any' production of the core grammar.
:param token: a single token
:param context: a string for the 'unexpected in ...' message
View
2 tinycss/page3.py
@@ -131,7 +131,7 @@ def parse_page_selector(self, head):
A page selector. For CSS 2.1, this is 'first', 'left', 'right'
or None.
:raises:
- :class:`ParseError` on invalid selectors
+ :exc:`~css21.ParseError` on invalid selectors
"""
if not head:
View
39 tinycss/selectors3.py
@@ -39,19 +39,24 @@ class Selector(object):
In CSS 3, each ruleset has a list of comma-separated selectors.
A :class:`Selector` object represents one of these selectors.
+ These selectors optionally have one *pseudo-element* that must be
+ at the end.
+
+ .. commented for now: this is expected to change
+ .. .. attribute:: parsed_selector
- .. attribute:: parsed_selector
The selector parsed as a tree of cssselect internal objects.
.. attribute:: pseudo_element
- One of ``'before', 'after', 'first-letter', 'first-line', None``
+
+ One of ``'before'``, ``'after'``, ``'first-letter'``, ``'first-line'``
+ or ``None``.
.. attribute:: specificity
+
The specificity of this selector. This is a tuple of four integers,
but these tuples are mostly meant to be compared to each other.
- http://www.w3.org/TR/css3-selectors/#specificity
-
"""
def __init__(self, parsed_selector, pseudo_element, specificity, match):
self.parsed_selector = parsed_selector
@@ -60,18 +65,27 @@ def __init__(self, parsed_selector, pseudo_element, specificity, match):
# Mask the method (class attribute) with a callable instance attribute.
self.match = match
- def match(self, document, **kwargs): # pragma: no cover
- """Returns the list of elements that match the selector.
+ def match(self, lxml_element, **kwargs):
+ """Find elements in an XML or HTML document that match the part
+ of this selector before any *pseudo-element*.
- This works with :mod:`lxml.cssselect`, so the document must
- have been parsed with lxml.
+ This is based on :mod:`lxml.cssselect`, so the document must
+ have been parsed with lxml, not another implementation of the
+ ElementTree API.
Keyword arguments are passed to the underlying
:class:`lxml.etree.XPath` object. In particular, a `namespaces`_
dict can be passed.
.. _namespaces: http://lxml.de/xpathxslt.html#namespaces-and-prefixes
+ :param lxml_element:
+ A lxml :class:`~lxml.etree.Element` or
+ :class:`~lxml.etree.ElementTree`.
+ :returns:
+ The list of elements inside this tree that match the selector.
+ Remember to consider :attr:`pseudo_element` separately.
+
"""
# This dummy method is mostly here to hold its docstring,
# it just calls the instance attribute.
@@ -202,9 +216,12 @@ def _calculate_specificity(parsed_selector):
class CSSSelectors3Parser(CSS21Parser):
- """Adds a ``selector_list`` attribute to the :class:`RuleSet` objects
- returned by a parser. The attribute is a list of :class:`Selector`
- for this ruleset,.as returned by :func:`parse_selector3`
+ """Extend :class:`~.css21.CSS21Parser` to add parsing and matching of
+ `Level 3 Selectors <http://www.w3.org/TR/selectors/>`_.
+
+ Compared to CSS 2.1, :class:`~.css21.RuleSet` objects get a new'
+ ``selector_list`` attribute set to the list of parsed :class:`Selector`
+ objects for this ruleset.
"""
def parse_ruleset(self, first_token, tokens):

0 comments on commit 91f41b0

Please sign in to comment.
Something went wrong with that request. Please try again.