Commit 8922e205 authored by Lance Stout's avatar Lance Stout

Update the API docs for XMLStream

parent a85891c6
=========
xmlstream
=========
.. module:: sleekxmpp.xmlstream
.. autoclass:: XMLStream
:members:
.. toctree::
stanzabase
tostring
==========
XML Stream
==========
.. module:: sleekxmpp.xmlstream.xmlstream
.. autoexception:: RestartStream
.. autoclass:: XMLStream
:members:
......@@ -116,10 +116,29 @@ API Reference
api/xmlstream/stanzabase
api/xmlstream/handler
api/xmlstream/matcher
api/xmlstream/xmlstream
api/xmlstream/scheduler
api/xmlstream/tostring
api/xmlstream/filesocket
Core Stanzas
~~~~~~~~~~~~
.. toctree::
:maxdepth: 2
api/stanza/rootstanza
api/stanza/message
api/stanza/presence
api/stanza/iq
api/stanza/error
api/stanza/stream_error
Plugins
~~~~~~~
.. toctree::
:maxdepth: 2
Additional Info
---------------
.. toctree::
......
......@@ -30,66 +30,59 @@ class MatchXMLMask(MatcherBase):
XML pattern, or mask. For example, message stanzas with body elements
could be matched using the mask:
.. code-block:: xml
<message xmlns="jabber:client"><body /></message>
Use of XMLMask is discouraged, and XPath or StanzaPath should be used
instead.
Use of XMLMask is discouraged, and
:class:`~sleekxmpp.xmlstream.matcher.xpath.MatchXPath` or
:class:`~sleekxmpp.xmlstream.matcher.stanzapath.StanzaPath`
should be used instead.
The use of namespaces in the mask comparison is controlled by
IGNORE_NS. Setting IGNORE_NS to True will disable namespace based matching
for ALL XMLMask matchers.
``IGNORE_NS``. Setting ``IGNORE_NS`` to ``True`` will disable namespace
based matching for ALL XMLMask matchers.
Methods:
match -- Overrides MatcherBase.match.
setDefaultNS -- Set the default namespace for the mask.
:param criteria: Either an :class:`~xml.etree.ElementTree.Element` XML
object or XML string to use as a mask.
"""
def __init__(self, criteria):
"""
Create a new XMLMask matcher.
Arguments:
criteria -- Either an XML object or XML string to use as a mask.
"""
MatcherBase.__init__(self, criteria)
if isinstance(criteria, str):
self._criteria = ET.fromstring(self._criteria)
self.default_ns = 'jabber:client'
def setDefaultNS(self, ns):
"""
Set the default namespace to use during comparisons.
"""Set the default namespace to use during comparisons.
Arguments:
ns -- The new namespace to use as the default.
:param ns: The new namespace to use as the default.
"""
self.default_ns = ns
def match(self, xml):
"""
Compare a stanza object or XML object against the stored XML mask.
"""Compare a stanza object or XML object against the stored XML mask.
Overrides MatcherBase.match.
Arguments:
xml -- The stanza object or XML object to compare against.
:param xml: The stanza object or XML object to compare against.
"""
if hasattr(xml, 'xml'):
xml = xml.xml
return self._mask_cmp(xml, self._criteria, True)
def _mask_cmp(self, source, mask, use_ns=False, default_ns='__no_ns__'):
"""
Compare an XML object against an XML mask.
Arguments:
source -- The XML object to compare against the mask.
mask -- The XML object serving as the mask.
use_ns -- Indicates if namespaces should be respected during
the comparison.
default_ns -- The default namespace to apply to elements that
do not have a specified namespace.
Defaults to "__no_ns__".
"""Compare an XML object against an XML mask.
:param source: The :class:`~xml.etree.ElementTree.Element` XML object
to compare against the mask.
:param mask: The :class:`~xml.etree.ElementTree.Element` XML object
serving as the mask.
:param use_ns: Indicates if namespaces should be respected during
the comparison.
:default_ns: The default namespace to apply to elements that
do not have a specified namespace.
Defaults to ``"__no_ns__"``.
"""
use_ns = not IGNORE_NS
......@@ -148,14 +141,13 @@ class MatchXMLMask(MatcherBase):
return True
def _get_child(self, xml, tag):
"""
Return a child element given its tag, ignoring namespace values.
"""Return a child element given its tag, ignoring namespace values.
Returns None if the child was not found.
Returns ``None`` if the child was not found.
Arguments:
xml -- The XML object to search for the given child tag.
tag -- The name of the subelement to find.
:param xml: The :class:`~xml.etree.ElementTree.Element` XML object
to search for the given child tag.
:param tag: The name of the subelement to find.
"""
tag = tag.split('}')[-1]
try:
......
This diff is collapsed.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment