jshiffer/slixmpp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update api docs for handlers and matchers

Browse Source
This commit is contained in:
Lance Stout
2011-12-04 16:26:14 -08:00
parent c9dc9ec11e
commit 2586fdffda
11 changed files with 225 additions and 202 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
sleekxmpp/xmlstream/matcher/base.py
View File

@@ -1,9 +1,12 @@
# -*- coding: utf-8 -*-
"""
SleekXMPP: The Sleek XMPP Library
Copyright (C) 2010 Nathanael C. Fritz
This file is part of SleekXMPP.
sleekxmpp.xmlstream.matcher.base
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
See the file LICENSE for copying permission.
Part of SleekXMPP: The Sleek XMPP Library
:copyright: (c) 2011 Nathanael C. Fritz
:license: MIT, see LICENSE for more details
"""
@@ -13,21 +16,15 @@ class MatcherBase(object):
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.
:param criteria: Object to compare some aspect of a stanza against.
"""
def __init__(self, criteria):
"""
Create a new stanza matcher.
Arguments:
criteria -- Object to compare some aspect of a stanza
against.
"""
self._criteria = criteria
def match(self, xml):
"""
Check if a stanza matches the stored criteria.
"""Check if a stanza matches the stored criteria.
Meant to be overridden.
"""

25
sleekxmpp/xmlstream/matcher/id.py
View File

@@ -1,9 +1,12 @@
# -*- coding: utf-8 -*-
"""
SleekXMPP: The Sleek XMPP Library
Copyright (C) 2010 Nathanael C. Fritz
This file is part of SleekXMPP.
sleekxmpp.xmlstream.matcher.id
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
See the file LICENSE for copying permission.
Part of SleekXMPP: The Sleek XMPP Library
:copyright: (c) 2011 Nathanael C. Fritz
:license: MIT, see LICENSE for more details
"""
from sleekxmpp.xmlstream.matcher.base import MatcherBase
@@ -14,19 +17,13 @@ class MatcherId(MatcherBase):
"""
The ID matcher selects stanzas that have the same stanza 'id'
interface value as the desired ID.
Methods:
match -- Overrides MatcherBase.match.
"""
def match(self, xml):
"""
Compare the given stanza's 'id' attribute to the stored
id value.
"""Compare the given stanza's ``'id'`` attribute to the stored
``id`` value.
Overrides MatcherBase.match.
Arguments:
xml -- The stanza to compare against.
:param xml: The :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
stanza to compare against.
"""
return xml['id'] == self._criteria

28
sleekxmpp/xmlstream/matcher/stanzapath.py
View File

@@ -1,9 +1,12 @@
# -*- coding: utf-8 -*-
"""
SleekXMPP: The Sleek XMPP Library
Copyright (C) 2010 Nathanael C. Fritz
This file is part of SleekXMPP.
sleekxmpp.xmlstream.matcher.stanzapath
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
See the file LICENSE for copying permission.
Part of SleekXMPP: The Sleek XMPP Library
:copyright: (c) 2011 Nathanael C. Fritz
:license: MIT, see LICENSE for more details
"""
from sleekxmpp.xmlstream.matcher.base import MatcherBase
@@ -15,24 +18,17 @@ class StanzaPath(MatcherBase):
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.
In most cases, the stanza path and XPath should be identical, but be
aware that differences may occur.
Methods:
match -- Overrides MatcherBase.match.
"""
def match(self, 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. For most cases, the stanza path and
XPath should be identical, but be aware that differences may occur.
instead of the underlying XML. See the documentation for the stanza
:meth:`~sleekxmpp.xmlstream.stanzabase.ElementBase.match()` method
for more information.
Overrides MatcherBase.match.
Arguments:
stanza -- The stanza object to compare against.
:param stanza: The :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
stanza to compare against.
"""
return stanza.match(self._criteria)

43
sleekxmpp/xmlstream/matcher/xpath.py
View File

@@ -1,9 +1,12 @@
# -*- coding: utf-8 -*-
"""
SleekXMPP: The Sleek XMPP Library
Copyright (C) 2010 Nathanael C. Fritz
This file is part of SleekXMPP.
sleekxmpp.xmlstream.matcher.xpath
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
See the file LICENSE for copying permission.
Part of SleekXMPP: The Sleek XMPP Library
:copyright: (c) 2011 Nathanael C. Fritz
:license: MIT, see LICENSE for more details
"""
from sleekxmpp.xmlstream.stanzabase import ET
@@ -22,30 +25,34 @@ class MatchXPath(MatcherBase):
The XPath matcher selects stanzas whose XML contents matches a given
XPath expression.
Note that using this matcher may not produce expected behavior when using
attribute selectors. For Python 2.6 and 3.1, the ElementTree find method
does not support the use of attribute selectors. If you need to support
Python 2.6 or 3.1, it might be more useful to use a StanzaPath matcher.
.. warning::
If the value of IGNORE_NS is set to true, then XPath expressions will
be matched without using namespaces.
Using this matcher may not produce expected behavior when using
attribute selectors. For Python 2.6 and 3.1, the ElementTree
:meth:`~xml.etree.ElementTree.Element.find()` method does
not support the use of attribute selectors. If you need to
support Python 2.6 or 3.1, it might be more useful to use a
:class:`~sleekxmpp.xmlstream.matcher.stanzapath.StanzaPath` matcher.
Methods:
match -- Overrides MatcherBase.match.
If the value of :data:`IGNORE_NS` is set to ``True``, then XPath
expressions will be matched without using namespaces.
"""
def match(self, 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.
If the value of :data:`IGNORE_NS` is set to ``True``, then XPath
expressions will be matched without using namespaces.
Note that in Python 2.6 and 3.1 the ElementTree find method does
not support attribute selectors in the XPath expression.
.. warning::
Arguments:
xml -- The stanza object to compare against.
In Python 2.6 and 3.1 the ElementTree
:meth:`~xml.etree.ElementTree.Element.find()` method does not
support attribute selectors in the XPath expression.
:param xml: The :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
stanza to compare against.
"""
if hasattr(xml, 'xml'):
xml = xml.xml