v1.3.5

2026-08-02 18:57:40 +02:00
parent 5e5ab8681a
commit 6fa59321c0
5759 changed files with 712133 additions and 66 deletions
@@ -0,0 +1,152 @@
+########################################################################
+# File name: utils.py
+# This file is part of: aioxmpp
+#
+# LICENSE
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this program.  If not, see
+# <http://www.gnu.org/licenses/>.
+#
+########################################################################
+from abc import ABCMeta, abstractproperty
+
+from . import xso as chatstates_xso
+
+
+class ChatStateStrategy(metaclass=ABCMeta):
+
+    @abstractproperty
+    def sending(self):
+        """
+        Return whether to send chat state notifications.
+        """
+        raise NotImplementedError  # pragma: no cover
+
+    def reset(self):
+        """
+        Reset the strategy (called after a reconnect).
+        """
+        pass
+
+    def no_reply(self):
+        """
+        Called when the replies did not include a chat state.
+        """
+        pass
+
+
+class DoNotEmit(ChatStateStrategy):
+    """
+    Chat state strategy: Do not emit chat state notifications.
+    """
+
+    @property
+    def sending(self):
+        return False
+
+
+class DiscoverSupport(ChatStateStrategy):
+    """
+    Chat state strategy: Discover support for chat state notifications
+    as per section 5.1 of :xep:`0085`.
+    """
+    def __init__(self):
+        self.state = True
+
+    def reset(self):
+        self.state = True
+
+    def no_reply(self):
+        self.state = False
+
+    @property
+    def sending(self):
+        return self.state
+
+
+class AlwaysEmit(ChatStateStrategy):
+    """
+    Chat state strategy: Always emit chat state notifications.
+    """
+
+    @property
+    def sending(self):
+        return True
+
+
+class ChatStateManager:
+    """
+    Manage the state of our chat state.
+
+    :param strategy: the strategy used to decide whether to send
+                     notifications (defaults to :class:`DiscoverSupport`)
+    :type strategy: a subclass of :class:`ChatStateStrategy`
+
+    .. automethod:: handle
+
+    Methods to pass in protocol level information:
+
+    .. automethod:: no_reply
+
+    .. automethod:: reset
+    """
+
+    def __init__(self, strategy=None):
+        self._state = chatstates_xso.ChatState.ACTIVE
+        if strategy is None:
+            strategy = DiscoverSupport()
+        self._strategy = strategy
+
+    def handle(self, state, message=False):
+        """
+        Handle a state update.
+
+        :param state: the new chat state
+        :type state: :class:`~aioxmpp.chatstates.ChatState`
+
+        :param message: pass true to indicate that we handle the
+                        :data:`ACTIVE` state that is implied by
+                        sending a content message.
+        :type message: :class:`bool`
+
+        :returns: whether a standalone notification must be sent for
+                  this state update, respective if a chat state
+                  notification must be included with the message.
+
+        :raises ValueError: if `message` is true and a state other
+                            than :data:`ACTIVE` is passed.
+        """
+        if message:
+            if state != chatstates_xso.ChatState.ACTIVE:
+                raise ValueError(
+                    "Only the state ACTIVE can be sent with messages."
+                )
+        elif self._state == state:
+            return False
+
+        self._state = state
+        return self._strategy.sending
+
+    def no_reply(self):
+        """
+        Call this method if the peer did not include a chat state
+        notification.
+        """
+        self._strategy.no_reply()
+
+    def reset(self):
+        """
+        Call this method on connection reset.
+        """
+        self._strategy.reset()