API Reference

class cssselect2.Matcher

A CSS selectors storage that can match against HTML elements.

add_selector(selector, payload)

Add a selector and its payload to the matcher.

Parameters:

selector – A compiler.CompiledSelector object.
payload – Some data associated to the selector, such as declarations parsed from the tinycss2.ast.QualifiedRule.content of a style rule. It can be any Python object, and will be returned as-is by match().

match(element)

Match selectors against the given element.

Parameters:: element – An ElementWrapper.
Returns:: A list of the payload objects associated to selectors that match element, in order of lowest to highest compiler.CompiledSelector specificity and in order of addition with add_selector() among selectors of equal specificity.

cssselect2.compile_selector_list(input, namespaces=None)

Compile a (comma-separated) list of selectors.

Parameters:

input – A string, or an iterable of tinycss2 component values such as the tinycss2.ast.QualifiedRule.prelude of a style rule.
namespaces – A optional dictionary of all namespace prefix declarations in scope for this selector. Keys are namespace prefixes as strings, or None for the default namespace. Values are namespace URLs as strings. If omitted, assume that no prefix is declared.

Returns:

A list of opaque compiler.CompiledSelector objects.

class cssselect2.ElementWrapper(etree_element, parent, index, previous, in_html_document, content_language=None)

Wrapper of xml.etree.ElementTree.Element for Selector matching.

This class should not be instanciated directly. from_xml_root() or from_html_root() should be used for the root element of a document, and other elements should be accessed (and wrappers generated) using methods such as iter_children() and iter_subtree().

ElementWrapper objects compare equal if their underlying xml.etree.ElementTree.Element do.

property ancestors

Tuple of existing ancestors.

Tuple of existing ElementWrapper objects for this element’s ancestors, in reversed tree order, from parent to the root.

property classes: The classes of this element, as a set of strings.

property etree_children

Children as a list of xml.etree.ElementTree.Element.

Other ElementTree nodes such as comments and processing instructions are not included.

etree_element: The underlying ElementTree xml.etree.ElementTree.Element

etree_siblings: The parent’s children as a list of ElementTree xml.etree.ElementTree.Elements. For the root (which has no parent)

classmethod from_html_root(root, content_language=None)

Same as from_xml_root() with case-insensitive attribute names.

Useful for documents parsed with an HTML parser like html5lib, which should be the case of documents with the text/html MIME type.

classmethod from_xml_root(root, content_language=None)

Wrap for selector matching the root of an XML or XHTML document.

Parameters:: root – An ElementTree xml.etree.ElementTree.Element for the root element of a document. If the given element is not the root, selector matching will behave is if it were. In other words, selectors will be not be scoped to the subtree rooted at that element.
Returns:: A new ElementWrapper

property id: The ID of this element, as a string.

index: The position within the parent’s children, counting from 0. e.etree_siblings[e.index] is always e.etree_element.

iter_ancestors()

Iterate over ancestors.

Return an iterator of existing ElementWrapper objects for this element’s ancestors, in reversed tree order (from parent to the root).

The element itself is not included, this is an empty sequence for the root element.

This method is deprecated and will be removed in version 0.7.0. Use ancestors instead.

iter_children()

Iterate over children.

Return an iterator of newly-created ElementWrapper objects for this element’s child elements, in tree order.

iter_next_siblings()

Iterate over next siblings.

Return an iterator of newly-created ElementWrapper objects for this element’s next siblings, in tree order.

iter_previous_siblings()

Iterate over previous siblings.

Return an iterator of existing ElementWrapper objects for this element’s previous siblings, in reversed tree order.

The element itself is not included, this is an empty sequence for a first child or the root element.

This method is deprecated and will be removed in version 0.7.0. Use previous_siblings instead.

iter_siblings()

Iterate over siblings.

Return an iterator of newly-created ElementWrapper objects for this element’s siblings, in tree order.

iter_subtree()

Iterate over subtree.

Return an iterator of newly-created ElementWrapper objects for the entire subtree rooted at this element, in tree order.

Unlike in other methods, the element itself is included.

This loops over an entire document:

for element in ElementWrapper.from_root(root_etree).iter_subtree():
    ...

property lang: The language of this element, as a string.

property local_name: The local name of this element, as a string.

matches(*selectors)

Return wether this elememt matches any of the given selectors.

Parameters:: selectors – Each given selector is either a compiler.CompiledSelector, or an argument to compile_selector_list().

property namespace_url: The namespace URL of this element, as a string.

parent: The parent ElementWrapper, or None for the root element.

previous: The previous sibling ElementWrapper, or None for the root element.

property previous_siblings

Tuple of previous siblings.

Tuple of existing ElementWrapper objects for this element’s previous siblings, in reversed tree order.

query(*selectors)

Return first element that matches any of given selectors.

Parameters:: selectors – Each given selector is either a compiler.CompiledSelector, or an argument to compile_selector_list().
Returns:: A newly-created ElementWrapper object, or None if there is no match.

query_all(*selectors)

Return elements, in tree order, that match any of given selectors.

Selectors are scoped to the subtree rooted at this element.

Parameters:: selectors – Each given selector is either a compiler.CompiledSelector, or an argument to compile_selector_list().
Returns:: An iterator of newly-created ElementWrapper objects.

class cssselect2.SelectorError: A specialized ValueError for invalid selectors.

class cssselect2.compiler.CompiledSelector(parsed_selector): Abstract representation of a selector.