From 8922e2050ab3b3994e0852fa314e5bdc43809283 Mon Sep 17 00:00:00 2001 From: Lance Stout Date: Sun, 4 Dec 2011 20:35:17 -0800 Subject: Update the API docs for XMLStream --- sleekxmpp/xmlstream/matcher/xmlmask.py | 68 +++++++++++++++------------------- 1 file changed, 30 insertions(+), 38 deletions(-) (limited to 'sleekxmpp/xmlstream/matcher') diff --git a/sleekxmpp/xmlstream/matcher/xmlmask.py b/sleekxmpp/xmlstream/matcher/xmlmask.py index d72297f6..7977e767 100644 --- a/sleekxmpp/xmlstream/matcher/xmlmask.py +++ b/sleekxmpp/xmlstream/matcher/xmlmask.py @@ -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 + - 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: -- cgit v1.2.3