summaryrefslogtreecommitdiff
path: root/slixmpp/xmlstream/handler/collector.py
blob: a5ee109cdb3d3b58c0656330fe803820a23d56c5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

# slixmpp.xmlstream.handler.collector
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Part of Slixmpp: The Slick XMPP Library
# :copyright: (c) 2012 Nathanael C. Fritz, Lance J.T. Stout
# :license: MIT, see LICENSE for more details
from __future__ import annotations

import logging
from typing import List, Optional, TYPE_CHECKING

from slixmpp.xmlstream.stanzabase import StanzaBase
from slixmpp.xmlstream.handler.base import BaseHandler
from slixmpp.xmlstream.matcher.base import MatcherBase

if TYPE_CHECKING:
    from slixmpp.xmlstream.xmlstream import XMLStream

log = logging.getLogger(__name__)


class Collector(BaseHandler):

    """
    The Collector handler allows for collecting a set of stanzas
    that match a given pattern. Unlike the Waiter handler, a
    Collector does not block execution, and will continue to
    accumulate matching stanzas until told to stop.

    :param string name: The name of the handler.
    :param matcher: A :class:`~slixmpp.xmlstream.matcher.base.MatcherBase`
                    derived object for matching stanza objects.
    :param stream: The :class:`~slixmpp.xmlstream.xmlstream.XMLStream`
                   instance this handler should monitor.
    """
    _stanzas: List[StanzaBase]

    def __init__(self, name: str, matcher: MatcherBase, stream: Optional[XMLStream] = None):
        BaseHandler.__init__(self, name, matcher, stream=stream)
        self._stanzas = []

    def prerun(self, payload: StanzaBase) -> None:
        """Store the matched stanza when received during processing.

        :param payload: The matched
            :class:`~slixmpp.xmlstream.stanzabase.StanzaBase` object.
        """
        self._stanzas.append(payload)

    def run(self, payload: StanzaBase) -> None:
        """Do not process this handler during the main event loop."""
        pass

    def stop(self) -> List[StanzaBase]:
        """
        Stop collection of matching stanzas, and return the ones that
        have been stored so far.
        """
        stream_ref = self.stream
        if stream_ref is None:
            raise ValueError('stop() called without a stream!')
        stream = stream_ref()
        if stream is None:
            raise ValueError('stop() called without a stream!')
        self._destroy = True
        stream.remove_handler(self.name)
        return self._stanzas