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,47 @@
+########################################################################
+# 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.version` --- Software Version (XEP-0092) support
+###############################################################
+
+This subpackage provides support for querying and answering queries adhering to
+the :xep:`92` (Software Support) protocol.
+
+.. versionadded:: 0.10
+
+The protocol allows entities to find out the software version and operating
+system of other entities in the XMPP network.
+
+.. currentmodule:: aioxmpp
+
+.. autoclass:: aioxmpp.VersionServer()
+
+.. currentmodule:: aioxmpp.version
+
+.. autofunction:: query_version
+
+.. automodule:: aioxmpp.version.xso
+"""
+from .service import (  # NOQA: F401
+    VersionServer,
+    query_version,
+)
@@ -0,0 +1,208 @@
+########################################################################
+# File name: service.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 asyncio
+import typing
+
+import aioxmpp
+import aioxmpp.disco
+import aioxmpp.errors
+import aioxmpp.service
+
+from . import xso as version_xso
+
+
+class VersionServer(aioxmpp.service.Service):
+    """
+    :class:`~aioxmpp.service.Service` which handles inbound :xep:`92` Software
+    Version requests.
+
+    .. warning::
+
+        Do **not** depend on this service in another service. This service
+        exposes possibly private or sensitive information over the XMPP
+        network without any filtering. Implicitly summoning this service via
+        a dependency is thus discouraged.
+
+        *If* you absolutely need to do this for the implementation of another
+        published XEP, please file an issue against :mod:`aioxmpp` so that we
+        can work out a good solution.
+
+    .. warning::
+
+        This service does answer version queries, no matter who asks. This may
+        not be desirable, in which case this service is not for you.
+
+    .. seealso::
+
+        :func:`~.version.query_version`
+            for a function to obtain another entities software version.
+
+    .. note::
+
+        By default, this service does not reply to version queries. The
+        :attr:`name` attribute needs to be set first.
+
+    The response can be configured with the following attributes:
+
+    .. autoattribute:: name
+        :annotation: = None
+
+    .. autoattribute:: version
+        :annotation: = None
+
+    .. autoattribute:: os
+        :annotation: = distro.name() or platform.system()
+    """
+
+    ORDER_AFTER = [
+        aioxmpp.disco.DiscoServer,
+    ]
+
+    disco_feature = aioxmpp.disco.register_feature(
+        "jabber:iq:version",
+    )
+
+    def __init__(self, client, **kwargs):
+        super().__init__(client, **kwargs)
+        try:
+            import distro
+        except ImportError:
+            import platform
+            self._os = platform.system()
+        else:
+            self._os = distro.name()
+
+        self._name = None
+        self._version = None
+
+    @property
+    def os(self) -> typing.Optional[str]:
+        """
+        The operating system of this entity.
+
+        Defaults to :func:`distro.name` or :func:`platform.system` (if
+        :mod:`distro` is not available).
+
+        This attribute can be set to :data:`None` or deleted to prevent
+        inclusion of the OS element in the reply.
+        """
+        return self._os
+
+    @os.setter
+    def os(self, value: typing.Optional[str]):
+        if value is None:
+            self._os = None
+        else:
+            self._os = str(value)
+
+    @os.deleter
+    def os(self):
+        self._os = None
+
+    @property
+    def name(self) -> typing.Optional[str]:
+        """
+        The software name of this entity.
+
+        Defaults to :data:`None`.
+
+        If this attribute is :data:`None`, version requests are not answered
+        but fail with a ``service-unavailable`` error.
+        """
+        return self._name
+
+    @name.setter
+    def name(self, value: typing.Optional[str]):
+        if value is None:
+            self._name = None
+        else:
+            self._name = str(value)
+
+    @name.deleter
+    def name(self):
+        self._name = None
+
+    @property
+    def version(self) -> typing.Optional[str]:
+        """
+        The software version of this entity.
+
+        Defaults to :data:`None`.
+
+        If this attribute is :data:`None` or the empty string, the version will
+        be shown as ``"unspecified"`` to other entities. This can be used to
+        avoid disclosing the specific version of the software.
+        """
+        return self._version
+
+    @version.setter
+    def version(self, value: typing.Optional[str]):
+        if value is None:
+            self._version = None
+        else:
+            self._version = str(value)
+
+    @version.deleter
+    def version(self):
+        self._version = None
+
+    @aioxmpp.service.iq_handler(aioxmpp.IQType.GET,
+                                version_xso.Query)
+    async def handle_query(self, iq: aioxmpp.IQ) -> version_xso.Query:
+        if self._name is None:
+            raise aioxmpp.errors.XMPPCancelError(
+                aioxmpp.errors.ErrorCondition.SERVICE_UNAVAILABLE,
+            )
+
+        result = version_xso.Query()
+        result.name = self._name
+        result.os = self._os
+        result.version = self._version or "unspecified"
+        return result
+
+
+async def query_version(stream: aioxmpp.stream.StanzaStream,
+                        target: aioxmpp.JID) -> version_xso.Query:
+    """
+    Query the software version of an entity.
+
+    :param stream: A stanza stream to send the query on.
+    :type stream: :class:`aioxmpp.stream.StanzaStream`
+    :param target: The address of the entity to query.
+    :type target: :class:`aioxmpp.JID`
+    :raises OSError: if a connection issue occurred before a reply was received
+    :raises aioxmpp.errors.XMPPError: if an XMPP error was returned instead
+        of a reply.
+    :rtype: :class:`aioxmpp.version.xso.Query`
+    :return: The response from the peer.
+
+    The response is returned as :class:`~aioxmpp.version.xso.Query` object. The
+    attributes hold the data returned by the peer. Each attribute may be
+    :data:`None` if the peer chose to omit that information. In an extreme
+    case, all attributes are :data:`None`.
+    """
+
+    return await stream.send(aioxmpp.IQ(
+        type_=aioxmpp.IQType.GET,
+        to=target,
+        payload=version_xso.Query(),
+    ))
@@ -0,0 +1,70 @@
+########################################################################
+# 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/>.
+#
+########################################################################
+"""
+XSO Definitions
+===============
+
+.. autoclass:: Query
+"""
+import aioxmpp
+import aioxmpp.xso as xso
+
+from aioxmpp.utils import namespaces
+
+
+namespaces.xep0092_version = "jabber:iq:version"
+
+
+@aioxmpp.IQ.as_payload_class
+class Query(xso.XSO):
+    """
+    :xep:`92` Software Version query :class:`~aioxmpp.xso.XSO`.
+
+    .. attribute:: name
+
+        Software name as string. May be :data:`None`.
+
+    .. attribute:: version
+
+        Software version as string. May be :data:`None`.
+
+    .. attribute:: os
+
+        Operating system as string. May be :data:`None`.
+    """
+
+    TAG = namespaces.xep0092_version, "query"
+
+    version = xso.ChildText(
+        (namespaces.xep0092_version, "version"),
+        default=None,
+    )
+
+    name = xso.ChildText(
+        (namespaces.xep0092_version, "name"),
+        default=None,
+    )
+
+    os = xso.ChildText(
+        (namespaces.xep0092_version, "os"),
+        default=None,
+    )