summaryrefslogtreecommitdiff
path: root/sleekxmpp/xmlstream
diff options
context:
space:
mode:
authorLance Stout <lancestout@gmail.com>2011-12-04 16:26:14 -0800
committerLance Stout <lancestout@gmail.com>2011-12-04 16:26:14 -0800
commit2586fdffda9dac5ee56664c74e71bd54ae47ee18 (patch)
tree8c3eff0ed8ed6539b7eace355a90e8ede9634d0a /sleekxmpp/xmlstream
parentc9dc9ec11e8ef141234d8376fe8882ae13babbf8 (diff)
downloadslixmpp-2586fdffda9dac5ee56664c74e71bd54ae47ee18.tar.gz
slixmpp-2586fdffda9dac5ee56664c74e71bd54ae47ee18.tar.bz2
slixmpp-2586fdffda9dac5ee56664c74e71bd54ae47ee18.tar.xz
slixmpp-2586fdffda9dac5ee56664c74e71bd54ae47ee18.zip
Update api docs for handlers and matchers
Diffstat (limited to 'sleekxmpp/xmlstream')
-rw-r--r--sleekxmpp/xmlstream/handler/base.py85
-rw-r--r--sleekxmpp/xmlstream/handler/callback.py82
-rw-r--r--sleekxmpp/xmlstream/handler/waiter.py78
-rw-r--r--sleekxmpp/xmlstream/matcher/base.py23
-rw-r--r--sleekxmpp/xmlstream/matcher/id.py25
-rw-r--r--sleekxmpp/xmlstream/matcher/stanzapath.py28
-rw-r--r--sleekxmpp/xmlstream/matcher/xpath.py43
7 files changed, 160 insertions, 204 deletions
diff --git a/sleekxmpp/xmlstream/handler/base.py b/sleekxmpp/xmlstream/handler/base.py
index 7f05c757..59dcb306 100644
--- a/sleekxmpp/xmlstream/handler/base.py
+++ b/sleekxmpp/xmlstream/handler/base.py
@@ -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.handler.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
"""
import weakref
@@ -16,78 +19,62 @@ class BaseHandler(object):
incoming stanzas so that the stanza may be processed in some way.
Stanzas may be matched with multiple handlers.
- Handler execution may take place in two phases. The first is during
- the stream processing itself. The second is after stream processing
- and during SleekXMPP's main event loop. The prerun method is used
- for execution during stream processing, and the run method is used
- during the main event loop.
-
- Attributes:
- name -- The name of the handler.
- stream -- The stream this handler is assigned to.
-
- Methods:
- match -- Compare a stanza with the handler's matcher.
- 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.
+ Handler execution may take place in two phases: during the incoming
+ stream processing, and in the main event loop. The :meth:`prerun()`
+ method is executed in the first case, and :meth:`run()` is called
+ during the second.
+
+ :param string name: The name of the handler.
+ :param matcher: A :class:`~sleekxmpp.xmlstream.matcher.base.MatcherBase`
+ derived object that will be used to determine if a
+ stanza should be accepted by this handler.
+ :param stream: The :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream`
+ instance that the handle will respond to.
"""
def __init__(self, name, matcher, stream=None):
- """
- 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.
- """
+ #: The name of the handler
self.name = name
+
+ #: The XML stream this handler is assigned to
+ self.stream = None
if stream is not None:
self.stream = weakref.ref(stream)
- else:
- self.stream = None
+ stream.register_handler(self)
+
self._destroy = False
self._payload = None
self._matcher = matcher
- if stream is not None:
- stream.registerHandler(self)
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
- xml -- An XML or stanza object.
+ :param xml: An XML or
+ :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` object
"""
return self._matcher.match(xml)
def prerun(self, payload):
- """
- Prepare the handler for execution while the XML stream is being
- processed.
+ """Prepare the handler for execution while the XML
+ stream is being processed.
- Arguments:
- payload -- A stanza object.
+ :param payload: A :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
+ object.
"""
self._payload = 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.
- Arguments:
- payload -- A stanza object.
+ :param payload: A :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
+ object.
"""
self._payload = payload
def check_delete(self):
- """
- Check if the handler should be removed from the list of stream
- handlers.
+ """Check if the handler should be removed from the list
+ of stream handlers.
"""
return self._destroy
diff --git a/sleekxmpp/xmlstream/handler/callback.py b/sleekxmpp/xmlstream/handler/callback.py
index 7fadab43..37f53335 100644
--- a/sleekxmpp/xmlstream/handler/callback.py
+++ b/sleekxmpp/xmlstream/handler/callback.py
@@ -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.handler.callback
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- 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
@@ -18,48 +21,42 @@ class Callback(BaseHandler):
The handler may execute the callback either during stream
processing or during the main event loop.
- Callback functions are all executed in the same thread, so be
- aware if you are executing functions that will block for extended
- periods of time. Typically, you should signal your own events using the
- SleekXMPP object's event() method to pass the stanza off to a threaded
- event handler for further processing.
-
- Methods:
- prerun -- Overrides BaseHandler.prerun
- run -- Overrides BaseHandler.run
+ Callback functions are all executed in the same thread, so be aware if
+ you are executing functions that will block for extended periods of
+ time. Typically, you should signal your own events using the SleekXMPP
+ object's :meth:`~sleekxmpp.xmlstream.xmlstream.XMLStream.event()`
+ method to pass the stanza off to a threaded event handler for further
+ processing.
+
+
+ :param string name: The name of the handler.
+ :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,
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)
self._pointer = pointer
self._once = once
self._instream = instream
def prerun(self, payload):
- """
- Execute the callback during stream processing, if
- the callback was created with instream=True.
-
- Overrides BaseHandler.prerun
+ """Execute the callback during stream processing, if
+ the callback was created with ``instream=True``.
- Arguments:
- payload -- The matched stanza object.
+ :param payload: The matched
+ :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` object.
"""
if self._once:
self._destroy = True
@@ -67,16 +64,13 @@ class Callback(BaseHandler):
self.run(payload, True)
def run(self, payload, instream=False):
- """
- Execute the callback function with the matched stanza payload.
-
- Overrides BaseHandler.run
+ """Execute the callback function with the matched stanza payload.
- Arguments:
- payload -- The matched stanza object.
- instream -- Force the handler to execute during
- stream processing. Used only by prerun.
- Defaults to False.
+ :param payload: The matched
+ :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` object.
+ :param bool instream: Force the handler to execute during stream
+ processing. This should only be used by
+ :meth:`prerun()`. Defaults to ``False``.
"""
if not self._instream or instream:
self._pointer(payload)
diff --git a/sleekxmpp/xmlstream/handler/waiter.py b/sleekxmpp/xmlstream/handler/waiter.py
index a64b6a9b..01ff5d67 100644
--- a/sleekxmpp/xmlstream/handler/waiter.py
+++ b/sleekxmpp/xmlstream/handler/waiter.py
@@ -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.handler.waiter
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- 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
@@ -22,67 +25,46 @@ log = logging.getLogger(__name__)
class Waiter(BaseHandler):
"""
- The Waiter handler allows an event handler to block
- until a particular stanza has been received. The handler
- will either be given the matched stanza, or False if the
- waiter has timed out.
-
- Methods:
- check_delete -- Overrides BaseHandler.check_delete
- prerun -- Overrides BaseHandler.prerun
- run -- Overrides BaseHandler.run
- wait -- Wait for a stanza to arrive and return it to
- an event handler.
+ The Waiter handler allows an event handler to block until a
+ particular stanza has been received. The handler will either be
+ given the matched stanza, or ``False`` if the waiter has timed out.
+
+ :param string name: The name of the handler.
+ :param matcher: A :class:`~sleekxmpp.xmlstream.matcher.base.MatcherBase`
+ derived object for matching stanza objects.
+ :param stream: The :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream`
+ instance this handler should monitor.
"""
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)
self._payload = queue.Queue()
def prerun(self, payload):
- """
- Store the matched stanza.
-
- Overrides BaseHandler.prerun
+ """Store the matched stanza when received during processing.
- Arguments:
- payload -- The matched stanza object.
+ :param payload: The matched
+ :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` object.
"""
self._payload.put(payload)
def run(self, payload):
- """
- Do not process this handler during the main event loop.
-
- Overrides BaseHandler.run
-
- Arguments:
- payload -- The matched stanza object.
- """
+ """Do not process this handler during the main event loop."""
pass
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
non-threaded event handler.
- Will return either the received stanza, or False if the waiter
- timed out.
+ Will return either the received stanza, or ``False`` if the
+ waiter timed out.
- Arguments:
- timeout -- The number of seconds to wait for the stanza to
- arrive. Defaults to the global default timeout
- value sleekxmpp.xmlstream.RESPONSE_TIMEOUT.
+ :param int timeout: The number of seconds to wait for the stanza
+ to arrive. Defaults to the the stream's
+ :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream.response_timeout`
+ value.
"""
if timeout is None:
timeout = self.stream().response_timeout
@@ -101,9 +83,5 @@ class Waiter(BaseHandler):
return stanza
def check_delete(self):
- """
- Always remove waiters after use.
-
- Overrides BaseHandler.check_delete
- """
+ """Always remove waiters after use."""
return True
diff --git a/sleekxmpp/xmlstream/matcher/base.py b/sleekxmpp/xmlstream/matcher/base.py
index 701ab32f..83c26688 100644
--- a/sleekxmpp/xmlstream/matcher/base.py
+++ b/sleekxmpp/xmlstream/matcher/base.py
@@ -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.
"""
diff --git a/sleekxmpp/xmlstream/matcher/id.py b/sleekxmpp/xmlstream/matcher/id.py
index 0c8ce2d8..11ab70bb 100644
--- a/sleekxmpp/xmlstream/matcher/id.py
+++ b/sleekxmpp/xmlstream/matcher/id.py
@@ -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.
-
- Overrides MatcherBase.match.
+ """Compare the given stanza's ``'id'`` attribute to the stored
+ ``id`` value.
- Arguments:
- xml -- The stanza to compare against.
+ :param xml: The :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
+ stanza to compare against.
"""
return xml['id'] == self._criteria
diff --git a/sleekxmpp/xmlstream/matcher/stanzapath.py b/sleekxmpp/xmlstream/matcher/stanzapath.py
index f8ff283d..61c5332c 100644
--- a/sleekxmpp/xmlstream/matcher/stanzapath.py
+++ b/sleekxmpp/xmlstream/matcher/stanzapath.py
@@ -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.
-
- Overrides MatcherBase.match.
+ instead of the underlying XML. See the documentation for the stanza
+ :meth:`~sleekxmpp.xmlstream.stanzabase.ElementBase.match()` method
+ for more information.
- 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)
diff --git a/sleekxmpp/xmlstream/matcher/xpath.py b/sleekxmpp/xmlstream/matcher/xpath.py
index 669c9f16..b6af0609 100644
--- a/sleekxmpp/xmlstream/matcher/xpath.py
+++ b/sleekxmpp/xmlstream/matcher/xpath.py
@@ -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.
+
+ .. warning::
- Note that in Python 2.6 and 3.1 the ElementTree find method does
- not support attribute selectors in the XPath expression.
+ 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.
- Arguments:
- xml -- The stanza object to compare against.
+ :param xml: The :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
+ stanza to compare against.
"""
if hasattr(xml, 'xml'):
xml = xml.xml