pep/slixmpp
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages 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
Show stats Download patch file Download diff file Expand all files Collapse all files

24
docs/api/xmlstream/handler.rst Normal file
View file

@ -0,0 +1,24 @@
Stanza Handlers
===============
The Basic Handler
-----------------
.. module:: sleekxmpp.xmlstream.handler.base
.. autoclass:: BaseHandler
:members:
Callback
--------
.. module:: sleekxmpp.xmlstream.handler.callback
.. autoclass:: Callback
:members:
Waiter
------
.. module:: sleekxmpp.xmlstream.handler.waiter
.. autoclass:: Waiter
:members:

0
docs/api/jid.rst → docs/api/xmlstream/jid.rst
View file

41
docs/api/xmlstream/matcher.rst Normal file
View file

@ -0,0 +1,41 @@
Stanza Matchers
===============
The Basic Matcher
-----------------
.. module:: sleekxmpp.xmlstream.matcher.base
.. autoclass:: MatcherBase
:members:
ID Matching
-----------
.. module:: sleekxmpp.xmlstream.matcher.id
.. autoclass:: MatcherId
:members:
Stanza Path Matching
--------------------
.. module:: sleekxmpp.xmlstream.matcher.stanzapath
.. autoclass:: StanzaPath
:members:
XPath
-----
.. module:: sleekxmpp.xmlstream.matcher.xpath
.. autoclass:: MatchXPath
:members:
XMLMask
-------
.. module:: sleekxmpp.xmlstream.matcher.xmlmask
.. autoclass:: MatchXMLMask
:members:

4
docs/index.rst
View file

@ -112,8 +112,10 @@ API Reference
api/clientxmpp api/clientxmpp
api/componentxmpp api/componentxmpp
api/basexmpp api/basexmpp
api/jid api/xmlstream/jid
api/xmlstream/stanzabase api/xmlstream/stanzabase
api/xmlstream/handler
api/xmlstream/matcher
api/xmlstream/tostring api/xmlstream/tostring
api/xmlstream/filesocket api/xmlstream/filesocket

83
sleekxmpp/xmlstream/handler/base.py
View file

@ -1,9 +1,12 @@
# -*- coding: utf-8 -*-
""" """
SleekXMPP: The Sleek XMPP Library sleekxmpp.xmlstream.handler.base
Copyright (C) 2010 Nathanael C. Fritz ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This file is part of SleekXMPP.
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
""" """
import weakref import weakref
@ -16,78 +19,62 @@ class BaseHandler(object):
incoming stanzas so that the stanza may be processed in some way. incoming stanzas so that the stanza may be processed in some way.
Stanzas may be matched with multiple handlers. Stanzas may be matched with multiple handlers.
Handler execution may take place in two phases. The first is during Handler execution may take place in two phases: during the incoming
the stream processing itself. The second is after stream processing stream processing, and in the main event loop. The :meth:`prerun()`
and during SleekXMPP's main event loop. The prerun method is used method is executed in the first case, and :meth:`run()` is called
for execution during stream processing, and the run method is used during the second.
during the main event loop.
Attributes: :param string name: The name of the handler.
name -- The name of the handler. :param matcher: A :class:`~sleekxmpp.xmlstream.matcher.base.MatcherBase`
stream -- The stream this handler is assigned to. derived object that will be used to determine if a
stanza should be accepted by this handler.
Methods: :param stream: The :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream`
match -- Compare a stanza with the handler's matcher. instance that the handle will respond to.
prerun -- Handler execution during stream processing.
run -- Handler execution during the main event loop.
check_delete -- Indicate if the handler may be removed from use.
""" """
def __init__(self, name, matcher, stream=None): def __init__(self, name, matcher, stream=None):
""" #: The name of the handler
Create a new stream handler.
Arguments:
name -- The name of the handler.
matcher -- A matcher object from xmlstream.matcher that will be
used to determine if a stanza should be accepted by
this handler.
stream -- The XMLStream instance the handler should monitor.
"""
self.name = name self.name = name
#: The XML stream this handler is assigned to
self.stream = None
if stream is not None: if stream is not None:
self.stream = weakref.ref(stream) self.stream = weakref.ref(stream)
else: stream.register_handler(self)
self.stream = None
self._destroy = False self._destroy = False
self._payload = None self._payload = None
self._matcher = matcher self._matcher = matcher
if stream is not None:
stream.registerHandler(self)
def match(self, xml): def match(self, xml):
""" """Compare a stanza or XML object with the handler's matcher.
Compare a stanza or XML object with the handler's matcher.
Arguments :param xml: An XML or
xml -- An XML or stanza object. :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` object
""" """
return self._matcher.match(xml) return self._matcher.match(xml)
def prerun(self, payload): def prerun(self, payload):
""" """Prepare the handler for execution while the XML
Prepare the handler for execution while the XML stream is being stream is being processed.
processed.
Arguments: :param payload: A :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
payload -- A stanza object. object.
""" """
self._payload = payload self._payload = payload
def run(self, payload): def run(self, payload):
""" """Execute the handler after XML stream processing and during the
Execute the handler after XML stream processing and during the
main event loop. main event loop.
Arguments: :param payload: A :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
payload -- A stanza object. object.
""" """
self._payload = payload self._payload = payload
def check_delete(self): def check_delete(self):
""" """Check if the handler should be removed from the list
Check if the handler should be removed from the list of stream of stream handlers.
handlers.
""" """
return self._destroy return self._destroy

80
sleekxmpp/xmlstream/handler/callback.py
View file

@ -1,9 +1,12 @@
# -*- coding: utf-8 -*-
""" """
SleekXMPP: The Sleek XMPP Library sleekxmpp.xmlstream.handler.callback
Copyright (C) 2010 Nathanael C. Fritz ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This file is part of SleekXMPP.
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.handler.base import BaseHandler from sleekxmpp.xmlstream.handler.base import BaseHandler
@ -18,48 +21,42 @@ class Callback(BaseHandler):
The handler may execute the callback either during stream The handler may execute the callback either during stream
processing or during the main event loop. processing or during the main event loop.
Callback functions are all executed in the same thread, so be Callback functions are all executed in the same thread, so be aware if
aware if you are executing functions that will block for extended you are executing functions that will block for extended periods of
periods of time. Typically, you should signal your own events using the time. Typically, you should signal your own events using the SleekXMPP
SleekXMPP object's event() method to pass the stanza off to a threaded object's :meth:`~sleekxmpp.xmlstream.xmlstream.XMLStream.event()`
event handler for further processing. method to pass the stanza off to a threaded event handler for further
processing.
Methods:
prerun -- Overrides BaseHandler.prerun :param string name: The name of the handler.
run -- Overrides BaseHandler.run :param matcher: A :class:`~sleekxmpp.xmlstream.matcher.base.MatcherBase`
derived object for matching stanza objects.
:param pointer: The function to execute during callback.
:param bool thread: **DEPRECATED.** Remains only for
backwards compatibility.
:param bool once: Indicates if the handler should be used only
once. Defaults to False.
:param bool instream: Indicates if the callback should be executed
during stream processing instead of in the
main event loop.
:param stream: The :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream`
instance this handler should monitor.
""" """
def __init__(self, name, matcher, pointer, thread=False, def __init__(self, name, matcher, pointer, thread=False,
once=False, instream=False, stream=None): once=False, instream=False, stream=None):
"""
Create a new callback handler.
Arguments:
name -- The name of the handler.
matcher -- A matcher object for matching stanza objects.
pointer -- The function to execute during callback.
thread -- DEPRECATED. Remains only for backwards compatibility.
once -- Indicates if the handler should be used only
once. Defaults to False.
instream -- Indicates if the callback should be executed
during stream processing instead of in the
main event loop.
stream -- The XMLStream instance this handler should monitor.
"""
BaseHandler.__init__(self, name, matcher, stream) BaseHandler.__init__(self, name, matcher, stream)
self._pointer = pointer self._pointer = pointer
self._once = once self._once = once
self._instream = instream self._instream = instream
def prerun(self, payload): def prerun(self, payload):
""" """Execute the callback during stream processing, if
Execute the callback during stream processing, if the callback was created with ``instream=True``.
the callback was created with instream=True.
Overrides BaseHandler.prerun :param payload: The matched
:class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` object.
Arguments:
payload -- The matched stanza object.
""" """
if self._once: if self._once:
self._destroy = True self._destroy = True
@ -67,16 +64,13 @@ class Callback(BaseHandler):
self.run(payload, True) self.run(payload, True)
def run(self, payload, instream=False): def run(self, payload, instream=False):
""" """Execute the callback function with the matched stanza payload.
Execute the callback function with the matched stanza payload.
Overrides BaseHandler.run :param payload: The matched
:class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` object.
Arguments: :param bool instream: Force the handler to execute during stream
payload -- The matched stanza object. processing. This should only be used by
instream -- Force the handler to execute during :meth:`prerun()`. Defaults to ``False``.
stream processing. Used only by prerun.
Defaults to False.
""" """
if not self._instream or instream: if not self._instream or instream:
self._pointer(payload) self._pointer(payload)

76
sleekxmpp/xmlstream/handler/waiter.py
View file

@ -1,9 +1,12 @@
# -*- coding: utf-8 -*-
""" """
SleekXMPP: The Sleek XMPP Library sleekxmpp.xmlstream.handler.waiter
Copyright (C) 2010 Nathanael C. Fritz ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This file is part of SleekXMPP.
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
""" """
import logging import logging
@ -22,67 +25,46 @@ log = logging.getLogger(__name__)
class Waiter(BaseHandler): class Waiter(BaseHandler):
""" """
The Waiter handler allows an event handler to block The Waiter handler allows an event handler to block until a
until a particular stanza has been received. The handler particular stanza has been received. The handler will either be
will either be given the matched stanza, or False if the given the matched stanza, or ``False`` if the waiter has timed out.
waiter has timed out.
Methods: :param string name: The name of the handler.
check_delete -- Overrides BaseHandler.check_delete :param matcher: A :class:`~sleekxmpp.xmlstream.matcher.base.MatcherBase`
prerun -- Overrides BaseHandler.prerun derived object for matching stanza objects.
run -- Overrides BaseHandler.run :param stream: The :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream`
wait -- Wait for a stanza to arrive and return it to instance this handler should monitor.
an event handler.
""" """
def __init__(self, name, matcher, stream=None): def __init__(self, name, matcher, stream=None):
"""
Create a new Waiter.
Arguments:
name -- The name of the waiter.
matcher -- A matcher object to detect the desired stanza.
stream -- Optional XMLStream instance to monitor.
"""
BaseHandler.__init__(self, name, matcher, stream=stream) BaseHandler.__init__(self, name, matcher, stream=stream)
self._payload = queue.Queue() self._payload = queue.Queue()
def prerun(self, payload): def prerun(self, payload):
""" """Store the matched stanza when received during processing.
Store the matched stanza.
Overrides BaseHandler.prerun :param payload: The matched
:class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` object.
Arguments:
payload -- The matched stanza object.
""" """
self._payload.put(payload) self._payload.put(payload)
def run(self, payload): def run(self, payload):
""" """Do not process this handler during the main event loop."""
Do not process this handler during the main event loop.
Overrides BaseHandler.run
Arguments:
payload -- The matched stanza object.
"""
pass pass
def wait(self, timeout=None): def wait(self, timeout=None):
""" """Block an event handler while waiting for a stanza to arrive.
Block an event handler while waiting for a stanza to arrive.
Be aware that this will impact performance if called from a Be aware that this will impact performance if called from a
non-threaded event handler. non-threaded event handler.
Will return either the received stanza, or False if the waiter Will return either the received stanza, or ``False`` if the
timed out. waiter timed out.
Arguments: :param int timeout: The number of seconds to wait for the stanza
timeout -- The number of seconds to wait for the stanza to to arrive. Defaults to the the stream's
arrive. Defaults to the global default timeout :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream.response_timeout`
value sleekxmpp.xmlstream.RESPONSE_TIMEOUT. value.
""" """
if timeout is None: if timeout is None:
timeout = self.stream().response_timeout timeout = self.stream().response_timeout
@ -101,9 +83,5 @@ class Waiter(BaseHandler):
return stanza return stanza
def check_delete(self): def check_delete(self):
""" """Always remove waiters after use."""
Always remove waiters after use.
Overrides BaseHandler.check_delete
"""
return True return True

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

@ -1,9 +1,12 @@
# -*- coding: utf-8 -*-
""" """
SleekXMPP: The Sleek XMPP Library sleekxmpp.xmlstream.matcher.base
Copyright (C) 2010 Nathanael C. Fritz ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This file is part of SleekXMPP.
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 Base class for stanza matchers. Stanza matchers are used to pick
stanzas out of the XML stream and pass them to the appropriate stanzas out of the XML stream and pass them to the appropriate
stream handlers. stream handlers.
:param criteria: Object to compare some aspect of a stanza against.
""" """
def __init__(self, criteria): def __init__(self, criteria):
"""
Create a new stanza matcher.
Arguments:
criteria -- Object to compare some aspect of a stanza
against.
"""
self._criteria = criteria self._criteria = criteria
def match(self, xml): def match(self, xml):
""" """Check if a stanza matches the stored criteria.
Check if a stanza matches the stored criteria.
Meant to be overridden. Meant to be overridden.
""" """

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

@ -1,9 +1,12 @@
# -*- coding: utf-8 -*-
""" """
SleekXMPP: The Sleek XMPP Library sleekxmpp.xmlstream.matcher.id
Copyright (C) 2010 Nathanael C. Fritz ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This file is part of SleekXMPP.
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 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' The ID matcher selects stanzas that have the same stanza 'id'
interface value as the desired ID. interface value as the desired ID.
Methods:
match -- Overrides MatcherBase.match.
""" """
def match(self, xml): def match(self, xml):
""" """Compare the given stanza's ``'id'`` attribute to the stored
Compare the given stanza's 'id' attribute to the stored ``id`` value.
id value.
Overrides MatcherBase.match. :param xml: The :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
stanza to compare against.
Arguments:
xml -- The stanza to compare against.
""" """
return xml['id'] == self._criteria 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 sleekxmpp.xmlstream.matcher.stanzapath
Copyright (C) 2010 Nathanael C. Fritz ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This file is part of SleekXMPP.
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 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", 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 which is similar to a normal XPath except that it uses the interfaces and
plugins of the stanza instead of the actual, underlying XML. 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): def match(self, stanza):
""" """
Compare a stanza against a "stanza path". A stanza path is similar to Compare a stanza against a "stanza path". A stanza path is similar to
an XPath expression, but uses the stanza's interfaces and plugins an XPath expression, but uses the stanza's interfaces and plugins
instead of the underlying XML. For most cases, the stanza path and instead of the underlying XML. See the documentation for the stanza
XPath should be identical, but be aware that differences may occur. :meth:`~sleekxmpp.xmlstream.stanzabase.ElementBase.match()` method
for more information.
Overrides MatcherBase.match. :param stanza: The :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
stanza to compare against.
Arguments:
stanza -- The stanza object to compare against.
""" """
return stanza.match(self._criteria) 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 sleekxmpp.xmlstream.matcher.xpath
Copyright (C) 2010 Nathanael C. Fritz ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This file is part of SleekXMPP.
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 from sleekxmpp.xmlstream.stanzabase import ET
@ -22,30 +25,34 @@ class MatchXPath(MatcherBase):
The XPath matcher selects stanzas whose XML contents matches a given The XPath matcher selects stanzas whose XML contents matches a given
XPath expression. XPath expression.
Note that using this matcher may not produce expected behavior when using .. warning::
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.
If the value of IGNORE_NS is set to true, then XPath expressions will Using this matcher may not produce expected behavior when using
be matched without using namespaces. 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: If the value of :data:`IGNORE_NS` is set to ``True``, then XPath
match -- Overrides MatcherBase.match. expressions will be matched without using namespaces.
""" """
def match(self, xml): def match(self, xml):
""" """
Compare a stanza's XML contents to an XPath expression. Compare a stanza's XML contents to an XPath expression.
If the value of IGNORE_NS is set to true, then XPath expressions If the value of :data:`IGNORE_NS` is set to ``True``, then XPath
will be matched without using namespaces. expressions will be matched without using namespaces.
Note that in Python 2.6 and 3.1 the ElementTree find method does .. warning::
not support attribute selectors in the XPath expression.
Arguments: In Python 2.6 and 3.1 the ElementTree
xml -- The stanza object to compare against. :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'): if hasattr(xml, 'xml'):
xml = xml.xml xml = xml.xml