| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126 |
- ==============
- lxml.cssselect
- ==============
- lxml supports a number of interesting languages for tree traversal and element
- selection. The most important is obviously XPath_, but there is also
- ObjectPath_ in the `lxml.objectify`_ module. The newest child of this family
- is `CSS selection`_, which is made available in form of the ``lxml.cssselect``
- module.
- Although it started its life in lxml, cssselect_ is now an independent project.
- It translates CSS selectors to XPath 1.0 expressions that can be used with
- lxml's XPath engine. ``lxml.cssselect`` adds a few convenience shortcuts into
- that package.
- To install ``cssselect``, run
- ::
- pip install cssselect
- lxml will then import and use it automatically.
- .. _XPath: xpathxslt.html#xpath
- .. _ObjectPath: objectify.html#objectpath
- .. _`lxml.objectify`: objectify.html
- .. _`CSS selection`: http://www.w3.org/TR/CSS21/selector.html
- .. _cssselect: http://packages.python.org/cssselect/
- .. contents::
- ..
- 1 The CSSSelector class
- 2 CSS Selectors
- 2.1 Namespaces
- 3 Limitations
- The CSSSelector class
- =====================
- The most important class in the ``lxml.cssselect`` module is ``CSSSelector``. It
- provides the same interface as the XPath_ class, but accepts a CSS selector
- expression as input:
- .. sourcecode:: pycon
- >>> from lxml.cssselect import CSSSelector
- >>> sel = CSSSelector('div.content')
- >>> sel #doctest: +ELLIPSIS
- <CSSSelector ... for 'div.content'>
- >>> sel.css
- 'div.content'
- The selector actually compiles to XPath, and you can see the
- expression by inspecting the object:
- .. sourcecode:: pycon
- >>> sel.path
- "descendant-or-self::div[@class and contains(concat(' ', normalize-space(@class), ' '), ' content ')]"
- To use the selector, simply call it with a document or element
- object:
- .. sourcecode:: pycon
- >>> from lxml.etree import fromstring
- >>> h = fromstring('''<div id="outer">
- ... <div id="inner" class="content body">
- ... text
- ... </div></div>''')
- >>> [e.get('id') for e in sel(h)]
- ['inner']
- Using ``CSSSelector`` is equivalent to translating with ``cssselect``
- and using the ``XPath`` class:
- .. sourcecode:: pycon
- >>> from cssselect import GenericTranslator
- >>> from lxml.etree import XPath
- >>> sel = XPath(GenericTranslator().css_to_xpath('div.content'))
- ``CSSSelector`` takes a ``translator`` parameter to let you choose which
- translator to use. It can be ``'xml'`` (the default), ``'xhtml'``, ``'html'``
- or a `Translator object`_.
- .. _Translator object: http://packages.python.org/cssselect/#cssselect.GenericTranslator
- The cssselect method
- ====================
- lxml ``Element`` objects have a ``cssselect`` convenience method.
- .. sourcecode:: pycon
- >>> h.cssselect('div.content') == sel(h)
- True
- Note however that pre-compiling the expression with the ``CSSSelector`` or
- ``XPath`` class can provide a substantial speedup.
- The method also accepts a ``translator`` parameter. On ``HtmlElement``
- objects, the default is changed to ``'html'``.
- Supported Selectors
- ===================
- Most `Level 3`_ selectors are supported. The details are in the
- `cssselect documentation`_.
- .. _Level 3: http://www.w3.org/TR/2011/REC-css3-selectors-20110929/
- .. _cssselect documentation: http://packages.python.org/cssselect/#supported-selectors
- Namespaces
- ==========
- In CSS you can use ``namespace-prefix|element``, similar to
- ``namespace-prefix:element`` in an XPath expression. In fact, it maps
- one-to-one, and the same rules are used to map namespace prefixes to
- namespace URIs: the ``CSSSelector`` class accepts a dictionary as its
- ``namespaces`` argument.
|