cssselect.txt 3.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108
  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 implemented in the new ``lxml.cssselect`` module.
  8. .. _XPath: xpathxslt.html#xpath
  9. .. _ObjectPath: objectify.html#objectpath
  10. .. _`lxml.objectify`: objectify.html
  11. .. _`CSS selection`: http://www.w3.org/TR/CSS21/selector.html
  12. .. contents::
  13. ..
  14. 1 The CSSSelector class
  15. 2 CSS Selectors
  16. 2.1 Namespaces
  17. 3 Limitations
  18. The CSSSelector class
  19. =====================
  20. The most important class in the ``cssselect`` module is ``CSSSelector``. It
  21. provides the same interface as the XPath_ class, but accepts a CSS selector
  22. expression as input:
  23. .. sourcecode:: pycon
  24. >>> from lxml.cssselect import CSSSelector
  25. >>> sel = CSSSelector('div.content')
  26. >>> sel #doctest: +ELLIPSIS
  27. <CSSSelector ... for 'div.content'>
  28. >>> sel.css
  29. 'div.content'
  30. The selector actually compiles to XPath, and you can see the
  31. expression by inspecting the object:
  32. .. sourcecode:: pycon
  33. >>> sel.path
  34. "descendant-or-self::div[contains(concat(' ', normalize-space(@class), ' '), ' content ')]"
  35. To use the selector, simply call it with a document or element
  36. object:
  37. .. sourcecode:: pycon
  38. >>> from lxml.etree import fromstring
  39. >>> h = fromstring('''<div id="outer">
  40. ... <div id="inner" class="content body">
  41. ... text
  42. ... </div></div>''')
  43. >>> [e.get('id') for e in sel(h)]
  44. ['inner']
  45. CSS Selectors
  46. =============
  47. This libraries attempts to implement CSS selectors `as described in
  48. the w3c specification
  49. <http://www.w3.org/TR/2001/CR-css3-selectors-20011113/>`_. Many of
  50. the pseudo-classes do not apply in this context, including all
  51. `dynamic pseudo-classes
  52. <http://www.w3.org/TR/2001/CR-css3-selectors-20011113/#dynamic-pseudos>`_.
  53. In particular these will not be available:
  54. * link state: ``:link``, ``:visited``, ``:target``
  55. * actions: ``:hover``, ``:active``, ``:focus``
  56. * UI states: ``:enabled``, ``:disabled``, ``:indeterminate``
  57. (``:checked`` and ``:unchecked`` *are* available)
  58. Also, none of the psuedo-elements apply, because the selector only
  59. returns elements and psuedo-elements select portions of text, like
  60. ``::first-line``.
  61. Namespaces
  62. ==========
  63. In CSS you can use ``namespace-prefix|element``, similar to
  64. ``namespace-prefix:element`` in an XPath expression. In fact, it maps
  65. one-to-one, and the same rules are used to map namespace prefixes to
  66. namespace URIs.
  67. Limitations
  68. ===========
  69. These applicable pseudoclasses are not yet implemented:
  70. * ``:lang(language)``
  71. * ``:root``
  72. * ``*:first-of-type``, ``*:last-of-type``, ``*:nth-of-type``,
  73. ``*:nth-last-of-type``, ``*:only-of-type``. All of these work when
  74. you specify an element type, but not with ``*``
  75. Unlike XPath you cannot provide parameters in your expressions -- all
  76. expressions are completely static.
  77. XPath has underspecified string quoting rules (there seems to be no
  78. string quoting at all), so if you use expressions that contain
  79. characters that requiring quoting you might have problems with the
  80. translation from CSS to XPath.