summaryrefslogtreecommitdiff
path: root/sleekxmpp/xmlstream/handler/base.py
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/handler/base.py
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/handler/base.py')
-rw-r--r--sleekxmpp/xmlstream/handler/base.py85
1 files changed, 36 insertions, 49 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