sleekxmpp/xmlstream/handler/base.py

   1 # -*- coding: utf-8 -*-
   2 """
   3     sleekxmpp.xmlstream.handler.base
   4     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   5
   6     Part of SleekXMPP: The Sleek XMPP Library
   7
   8     :copyright: (c) 2011 Nathanael C. Fritz
   9     :license: MIT, see LICENSE for more details
  10 """
  11
  12 import weakref
  13
  14
  15 class BaseHandler(object):
  16
  17     """
  18     Base class for stream handlers. Stream handlers are matched with
  19     incoming stanzas so that the stanza may be processed in some way.
  20     Stanzas may be matched with multiple handlers.
  21
  22     Handler execution may take place in two phases: during the incoming
  23     stream processing, and in the main event loop. The :meth:`prerun()`
  24     method is executed in the first case, and :meth:`run()` is called
  25     during the second.
  26
  27     :param string name: The name of the handler.
  28     :param matcher: A :class:`~sleekxmpp.xmlstream.matcher.base.MatcherBase`
  29                     derived object that will be used to determine if a
  30                     stanza should be accepted by this handler.
  31     :param stream: The :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream`
  32                     instance that the handle will respond to.
  33     """
  34
  35     def __init__(self, name, matcher, stream=None):
  36         #: The name of the handler
  37         self.name = name
  38
  39         #: The XML stream this handler is assigned to
  40         self.stream = None
  41         if stream is not None:
  42             self.stream = weakref.ref(stream)
  43             stream.register_handler(self)
  44
  45         self._destroy = False
  46         self._payload = None
  47         self._matcher = matcher
  48
  49     def match(self, xml):
  50         """Compare a stanza or XML object with the handler's matcher.
  51
  52         :param xml: An XML or
  53             :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` object
  54         """
  55         return self._matcher.match(xml)
  56
  57     def prerun(self, payload):
  58         """Prepare the handler for execution while the XML
  59         stream is being processed.
  60
  61         :param payload: A :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
  62                         object.
  63         """
  64         self._payload = payload
  65
  66     def run(self, payload):
  67         """Execute the handler after XML stream processing and during the
  68         main event loop.
  69
  70         :param payload: A :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
  71                         object.
  72         """
  73         self._payload = payload
  74
  75     def check_delete(self):
  76         """Check if the handler should be removed from the list
  77         of stream handlers.
  78         """
  79         return self._destroy
  80
  81
  82 # To comply with PEP8, method names now use underscores.
  83 # Deprecated method names are re-mapped for backwards compatibility.
  84 BaseHandler.checkDelete = BaseHandler.check_delete