base.py 2.87 KB
Newer Older
Nathan Fritz's avatar
Nathan Fritz committed
1

2 3 4 5 6
# slixmpp.xmlstream.handler.base
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Part of Slixmpp: The Slick XMPP Library
# :copyright: (c) 2011 Nathanael C. Fritz
# :license: MIT, see LICENSE for more details
mathieui's avatar
mathieui committed
7 8
from __future__ import annotations

9
import weakref
mathieui's avatar
mathieui committed
10 11 12 13 14 15
from weakref import ReferenceType
from typing import Optional, TYPE_CHECKING
from slixmpp.xmlstream.matcher.base import MatcherBase

if TYPE_CHECKING:
    from slixmpp.xmlstream import XMLStream, StanzaBase
16

17

mathieui's avatar
mathieui committed
18
class BaseHandler:
Nathan Fritz's avatar
Nathan Fritz committed
19

20 21 22 23 24
    """
    Base class for stream handlers. Stream handlers are matched with
    incoming stanzas so that the stanza may be processed in some way.
    Stanzas may be matched with multiple handlers.

25 26 27 28 29 30
    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.
louiz’'s avatar
louiz’ committed
31
    :param matcher: A :class:`~slixmpp.xmlstream.matcher.base.MatcherBase`
32 33
                    derived object that will be used to determine if a
                    stanza should be accepted by this handler.
louiz’'s avatar
louiz’ committed
34
    :param stream: The :class:`~slixmpp.xmlstream.xmlstream.XMLStream`
35
                    instance that the handle will respond to.
36
    """
mathieui's avatar
mathieui committed
37 38 39 40 41
    name: str
    stream: Optional[ReferenceType[XMLStream]]
    _destroy: bool
    _matcher: MatcherBase
    _payload: Optional[StanzaBase]
42

mathieui's avatar
mathieui committed
43
    def __init__(self, name: str, matcher: MatcherBase, stream: Optional[XMLStream] = None):
44
        #: The name of the handler
45
        self.name = name
46 47 48

        #: The XML stream this handler is assigned to
        self.stream = None
49 50
        if stream is not None:
            self.stream = weakref.ref(stream)
51 52
            stream.register_handler(self)

53 54 55 56
        self._destroy = False
        self._payload = None
        self._matcher = matcher

mathieui's avatar
mathieui committed
57
    def match(self, xml: StanzaBase) -> bool:
58
        """Compare a stanza or XML object with the handler's matcher.
59

Lance Stout's avatar
Lance Stout committed
60
        :param xml: An XML or
mathieui's avatar
mathieui committed
61
            :class:`~slixmpp.xmlstream.stanzabase.StanzaBase` object
62 63 64
        """
        return self._matcher.match(xml)

mathieui's avatar
mathieui committed
65
    def prerun(self, payload: StanzaBase) -> None:
66 67
        """Prepare the handler for execution while the XML
        stream is being processed.
68

mathieui's avatar
mathieui committed
69
        :param payload: A :class:`~slixmpp.xmlstream.stanzabase.StanzaBase`
70
                        object.
71 72 73
        """
        self._payload = payload

mathieui's avatar
mathieui committed
74
    def run(self, payload: StanzaBase) -> None:
75
        """Execute the handler after XML stream processing and during the
76 77
        main event loop.

mathieui's avatar
mathieui committed
78
        :param payload: A :class:`~slixmpp.xmlstream.stanzabase.StanzaBase`
79
                        object.
80 81
        """
        self._payload = payload
Nathan Fritz's avatar
Nathan Fritz committed
82

mathieui's avatar
mathieui committed
83
    def check_delete(self) -> bool:
Lance Stout's avatar
Lance Stout committed
84
        """Check if the handler should be removed from the list
85
        of stream handlers.
86 87
        """
        return self._destroy