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,58 @@
+########################################################################
+# File name: __init__.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/>.
+#
+########################################################################
+"""
+:mod:`~aioxmpp.chatstates` – Chat State Notification support (:xep:`0085`)
+##########################################################################
+
+This module provides support to implement :xep:`Chat State
+Notifications <85>`.
+
+XSOs
+====
+
+The module registers an attribute ``xep0085_chatstate`` with
+:class:`aioxmpp.Message` to represent the chat state
+notification tags, it takes values from the following enumeration (or
+:data:`None` if no tag is present):
+
+.. autoclass:: ChatState
+
+Helpers
+=======
+
+The module provides the following helper class, that handles the state
+management for chat state notifications:
+
+.. autoclass:: ChatStateManager
+
+Its operation is controlled by one of the chat state strategies:
+
+.. autoclass:: DoNotEmit
+
+.. autoclass:: DiscoverSupport
+
+.. autoclass:: AlwaysEmit
+
+"""
+from .xso import ChatState  # NOQA: F401
+from .utils import (ChatStateManager, DoNotEmit, AlwaysEmit,  # NOQA: F401
+                    DiscoverSupport)
@@ -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()
@@ -0,0 +1,54 @@
+########################################################################
+# File name: xso.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/>.
+#
+########################################################################
+import enum
+
+import aioxmpp.xso as xso
+import aioxmpp.stanza as stanza
+
+from aioxmpp.utils import namespaces
+
+
+namespaces.xep0085 = "http://jabber.org/protocol/chatstates"
+
+
+class ChatState(enum.Enum):
+    """
+    Enumeration of the chat states defined by :xep:`0085`:
+
+    .. attribute:: ACTIVE
+
+    .. attribute:: COMPOSING
+
+    .. attribute:: PAUSED
+
+    .. attribute:: INACTIVE
+
+    .. attribute:: GONE
+    """
+    ACTIVE = (namespaces.xep0085, "active")
+    COMPOSING = (namespaces.xep0085, "composing")
+    PAUSED = (namespaces.xep0085, "paused")
+    INACTIVE = (namespaces.xep0085, "inactive")
+    GONE = (namespaces.xep0085, "gone")
+
+
+stanza.Message.xep0085_chatstate = xso.ChildTag(ChatState, allow_none=True)