Skip to content
Back to top
View this page

# Stanza Matchers

## The Basic Matcher

class slixmpp.xmlstream.matcher.base.MatcherBase(criteria)

  Base class for stanza matchers. Stanza matchers are used to pick stanzas out of the XML stream and pass them to the appropriate stream handlers.

  Parameters:

    criteria (`Any`) – Object to compare some aspect of a stanza against.

  match(xml)

    Check if a stanza matches the stored criteria.

    Meant to be overridden.

    Return type:

      `bool`

## ID Matching

class slixmpp.xmlstream.matcher.id.MatcherId(criteria)

  The ID matcher selects stanzas that have the same stanza ‘id’ interface value as the desired ID.

  match(xml)

    Compare the given stanza’s `'id'` attribute to the stored `id` value.

    Parameters:

      xml (`StanzaBase`) – The `StanzaBase` stanza to compare against.

    Return type:

      `bool`

## Stanza Path Matching

class slixmpp.xmlstream.matcher.stanzapath.StanzaPath(criteria)

  The StanzaPath matcher selects stanzas that match a given “stanza path”, which is similar to a normal XPath except that it uses the interfaces and plugins of the stanza instead of the actual, underlying XML.

  Parameters:

    criteria (`str`) – Object to compare some aspect of a stanza against.

  match(stanza)

    Compare a stanza against a “stanza path”. A stanza path is similar to an XPath expression, but uses the stanza’s interfaces and plugins instead of the underlying XML. See the documentation for the stanza `match()` method for more information.

    Parameters:

      stanza (`StanzaBase`) – The `StanzaBase` stanza to compare against.

    Return type:

      `bool`

## XPath

class slixmpp.xmlstream.matcher.xpath.MatchXPath(criteria)

  The XPath matcher selects stanzas whose XML contents matches a given XPath expression.

  If the value of `IGNORE_NS` is set to `True`, then XPath expressions will be matched without using namespaces.

  match(xml)

    Compare a stanza’s XML contents to an XPath expression.

    If the value of `IGNORE_NS` is set to `True`, then XPath expressions will be matched without using namespaces.

    Parameters:

      xml (`StanzaBase`) – The `StanzaBase` stanza to compare against.

    Return type:

      `bool`

## XMLMask

class slixmpp.xmlstream.matcher.xmlmask.MatchXMLMask(criteria, default_ns='jabber:client')

  The XMLMask matcher selects stanzas whose XML matches a given XML pattern, or mask. For example, message stanzas with body elements could be matched using the mask:

      <message xmlns="jabber:client"><body /></message>

  Use of XMLMask is discouraged, and `MatchXPath` or `StanzaPath` should be used instead.

  Parameters:

    criteria (`str`) – Either an `Element` XML object or XML string to use as a mask.

  match(xml)

    Compare a stanza object or XML object against the stored XML mask.

    Overrides MatcherBase.match.

    Parameters:

      xml (`StanzaBase`) – The stanza object or XML object to compare against.

    Return type:

      `bool`

  setDefaultNS(ns)

    Set the default namespace to use during comparisons.

    Parameters:

      ns (`str`) – The new namespace to use as the default.

    Return type:

      `None`