# 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.Element`s. 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.