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)

A wrapper for an ElementTree 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.

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

etree_children

This element’s children, as a list of ElementTree 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(), but for documents parsed with an HTML parser like html5lib, which should be the case of documents with the text/html MIME type.

Compared to from_xml_root(), this makes element attribute names in Selectors case-insensitive.

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

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()

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.

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

iter_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.

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

iter_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():
    ...

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

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().

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.

query(*selectors)

Return the first element (in tree order) that matches any of the 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 the 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.