cssselect.txt 3.6 KB

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