<commit_before>==============
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 implemented in the new ``lxml.cssselect`` module.

.. _XPath: xpathxslt.html#xpath
.. _ObjectPath: objectify.html#objectpath
.. _`lxml.objectify`: objectify.html
.. _`CSS selection`: http://www.w3.org/TR/CSS21/selector.html

.. contents::
..
   1  The CSSSelector class
   2  CSS Selectors
     2.1  Namespaces
   3  Limitations


The CSSSelector class
=====================

The most important class in the ``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[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']


CSS Selectors
=============

This libraries attempts to implement CSS selectors `as described in
the w3c specification
<http://www.w3.org/TR/2001/CR-css3-selectors-20011113/>`_.  Many of
the pseudo-classes do not apply in this context, including all
`dynamic pseudo-classes
<http://www.w3.org/TR/2001/CR-css3-selectors-20011113/#dynamic-pseudos>`_.
In particular these will not be available:

* link state: ``:link``, ``:visited``, ``:target``
* actions: ``:hover``, ``:active``, ``:focus``
* UI states: ``:enabled``, ``:disabled``, ``:indeterminate``
  (``:checked`` and ``:unchecked`` *are* available)

Also, none of the psuedo-elements apply, because the selector only
returns elements and psuedo-elements select portions of text, like
``::first-line``.


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.


Limitations
===========

These applicable pseudoclasses are not yet implemented:

* ``:lang(language)``
* ``:root``
* ``*:first-of-type``, ``*:last-of-type``, ``*:nth-of-type``,
  ``*:nth-last-of-type``, ``*:only-of-type``.  All of these work when
  you specify an element type, but not with ``*``

Unlike XPath you cannot provide parameters in your expressions -- all
expressions are completely static.
<commit_msg>[svn r3597] r4067@delle:  sbehnel | 2008-04-24 19:38:29 +0200  rst fix<commit_after>==============
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 implemented in the new ``lxml.cssselect`` module.

.. _XPath: xpathxslt.html#xpath
.. _ObjectPath: objectify.html#objectpath
.. _`lxml.objectify`: objectify.html
.. _`CSS selection`: http://www.w3.org/TR/CSS21/selector.html

.. contents::
..
   1  The CSSSelector class
   2  CSS Selectors
     2.1  Namespaces
   3  Limitations


The CSSSelector class
=====================

The most important class in the ``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[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']


CSS Selectors
=============

This libraries attempts to implement CSS selectors `as described in
the w3c specification
<http://www.w3.org/TR/2001/CR-css3-selectors-20011113/>`_.  Many of
the pseudo-classes do not apply in this context, including all
`dynamic pseudo-classes
<http://www.w3.org/TR/2001/CR-css3-selectors-20011113/#dynamic-pseudos>`_.
In particular these will not be available:

* link state: ``:link``, ``:visited``, ``:target``
* actions: ``:hover``, ``:active``, ``:focus``
* UI states: ``:enabled``, ``:disabled``, ``:indeterminate``
  (``:checked`` and ``:unchecked`` *are* available)

Also, none of the psuedo-elements apply, because the selector only
returns elements and psuedo-elements select portions of text, like
``::first-line``.


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.


Limitations
===========

These applicable pseudoclasses are not yet implemented:

* ``:lang(language)``
* ``:root``
* ``*:first-of-type``, ``*:last-of-type``, ``*:nth-of-type``,
  ``*:nth-last-of-type``, ``*:only-of-type``.  All of these work when
  you specify an element type, but not with ``*``

Unlike XPath you cannot provide parameters in your expressions -- all
expressions are completely static.

{'fraction_non_alphanumeric': 0.16437913773615373, 'fraction_numerical': 0.016147263038914905, 'mean_word_length': 4.019448946515397, 'pattern_counts': {'":': 0, '<': 17, '<?xml version=': 0, '>': 65, 'https://': 0, 'lorem ipsum': 0, 'www.': 6, 'xml': 14}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '574485', 'n_tokens_mistral': 2002, 'n_tokens_neox': 1896, 'n_words': 652}