cssselect.txt 3.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118
  1. ==============
  2. lxml.cssselect
  3. ==============
  4. lxml supports a number of interesting languages for tree traversal and element
  5. selection. The most important is obviously XPath_, but there is also
  6. ObjectPath_ in the `lxml.objectify`_ module. The newest child of this family
  7. is `CSS selection`_, which is made available in form of the ``lxml.cssselect``
  8. module.
  9. Although it started its life in lxml, cssselect_ is now an independent project.
  10. It translates CSS selectors to XPath 1.0 expressions that can be used with
  11. lxml's XPath engine. ``lxml.cssselect`` adds a few convenience shortcuts into
  12. that package.
  13. .. _XPath: xpathxslt.html#xpath
  14. .. _ObjectPath: objectify.html#objectpath
  15. .. _`lxml.objectify`: objectify.html
  16. .. _`CSS selection`: http://www.w3.org/TR/CSS21/selector.html
  17. .. _cssselect: http://packages.python.org/cssselect/
  18. .. contents::
  19. ..
  20. 1 The CSSSelector class
  21. 2 CSS Selectors
  22. 2.1 Namespaces
  23. 3 Limitations
  24. The CSSSelector class
  25. =====================
  26. The most important class in the ``lxml.cssselect`` module is ``CSSSelector``. It
  27. provides the same interface as the XPath_ class, but accepts a CSS selector
  28. expression as input:
  29. .. sourcecode:: pycon
  30. >>> from lxml.cssselect import CSSSelector
  31. >>> sel = CSSSelector('div.content')
  32. >>> sel #doctest: +ELLIPSIS
  33. <CSSSelector ... for 'div.content'>
  34. >>> sel.css
  35. 'div.content'
  36. The selector actually compiles to XPath, and you can see the
  37. expression by inspecting the object:
  38. .. sourcecode:: pycon
  39. >>> sel.path
  40. "descendant-or-self::div[@class and contains(concat(' ', normalize-space(@class), ' '), ' content ')]"
  41. To use the selector, simply call it with a document or element
  42. object:
  43. .. sourcecode:: pycon
  44. >>> from lxml.etree import fromstring
  45. >>> h = fromstring('''<div id="outer">
  46. ... <div id="inner" class="content body">
  47. ... text
  48. ... </div></div>''')
  49. >>> [e.get('id') for e in sel(h)]
  50. ['inner']
  51. Using ``CSSSelector`` is equivalent to translating with ``cssselect``
  52. and using the ``XPath`` class:
  53. .. sourcecode:: pycon
  54. >>> from cssselect import GenericTranslator
  55. >>> from lxml.etree import XPath
  56. >>> sel = XPath(GenericTranslator().css_to_xpath('div.content'))
  57. ``CSSSelector`` takes a ``translator`` parameter to let you choose which
  58. translator to use. It can be ``'xml'`` (the default), ``'xhtml'``, ``'html'``
  59. or a `Translator object`_.
  60. .. _Translator object: http://packages.python.org/cssselect/#cssselect.GenericTranslator
  61. The cssselect method
  62. ====================
  63. lxml ``Element`` objects have a ``cssselect`` convenience method.
  64. .. sourcecode:: pycon
  65. >>> h.cssselect('div.content') == sel(h)
  66. True
  67. Note however that pre-compiling the expression with the ``CSSSelector`` or
  68. ``XPath`` class can provide a substantial speedup.
  69. The method also accepts a ``translator`` parameter. On ``HtmlElement``
  70. objects, the default is changed to ``'html'``.
  71. Supported Selectors
  72. ===================
  73. Most `Level 3`_ selectors are supported. The details are in the
  74. `cssselect documentation`_.
  75. .. _Level 3: http://www.w3.org/TR/2011/REC-css3-selectors-20110929/
  76. .. _cssselect documentation: http://packages.python.org/cssselect/#supported-selectors
  77. Namespaces
  78. ==========
  79. In CSS you can use ``namespace-prefix|element``, similar to
  80. ``namespace-prefix:element`` in an XPath expression. In fact, it maps
  81. one-to-one, and the same rules are used to map namespace prefixes to
  82. namespace URIs: the ``CSSSelector`` class accepts a dictionary as its
  83. ``namespaces`` argument.