# Source code for aioxmpp.utils

    ########################################################################
    # 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/>.
    #
    ########################################################################
    """
    :mod:`~aioxmpp.utils` --- Internal utils
    ========================================

    Miscellaneous utilities used throughout the aioxmpp codebase.

    .. data:: namespaces

       Collects all the namespaces from the various standards. Each namespace
       is given a shortname and its value is the namespace string.

       .. note:: This is intended to be promoted to the public API in a
                 future release. Third-party users should not assign
                 short-names for their own namespaces here, but instead
                 use a separate instance of :class:`Namespaces`.

    .. autoclass:: Namespaces

    .. autofunction:: gather_reraise_multi

    .. autofunction:: mkdir_exist_ok

    .. autofunction:: to_nmtoken

    .. autoclass:: LazyTask

    .. autoclass:: AlivenessMonitor

    .. autodecorator:: magicmethod

    .. autofunction:: proxy_property

    """

    import asyncio
    import base64
    import contextlib
    import time
    import types

    import aioxmpp.callbacks
    import aioxmpp.errors

    import lxml.etree as etree

    __all__ = [
        "etree",
        "namespaces",
    ]

    class Namespaces:
        """
        Manage short-hands for XML namespaces.

        Instances of this class may be used to assign mnemonic short-hands
        to XML namespaces, for example:

        .. code-block:: python

            namespaces = Namespaces()
            namespaces.foo = "urn:example:foo"
            namespaces.bar = "urn:example:bar"

        The class ensures that

        1. only one short-hand is bound to each namespace, so continuing the
           example, the following raises :class:`ValueError`:

           .. code-block:: python

               namespace.example_foo = "urn:example:foo"

        2. no short-hand is redefined to point to a different namespace,
           continuing the example, the following raises
           :class:`ValueError`:

           .. code-block:: python

               namespaces.foo = "urn:example:foo:2"

        3. deleting a short-hand is prohibited, the following raises
           :class:`AttributeError`:

           .. code-block:: python

               del namespaces.foo

        The defined short-hands MUST NOT start with an underscore.

        .. note:: This is intended to be promoted to the public API in a
                  future release.
        """

        def __init__(self):
            self._all_namespaces = {}

        def __setattr__(self, attr, value):
            if not attr.startswith("_"):
                try:
                    existing_attr = self._all_namespaces[value]
                    if attr != existing_attr:
                        raise ValueError(
                            "namespace {} already defined as {}".format(
                                value,
                                existing_attr,
                            )
                        )
                except KeyError:
                    try:
                        if getattr(self, attr) != value:
                            raise ValueError("inconsistent namespace redefinition")
                    except AttributeError:
                        pass
                self._all_namespaces[value] = attr
            super().__setattr__(attr, value)

        def __delattr__(self, attr):
            if not attr.startswith("_"):
                raise AttributeError("deleting short-hands is prohibited")
            super().__delattr__(attr)

    namespaces = Namespaces()
    namespaces.xmlstream = "http://etherx.jabber.org/streams"
    namespaces.client = "jabber:client"
    namespaces.starttls = "urn:ietf:params:xml:ns:xmpp-tls"
    namespaces.sasl = "urn:ietf:params:xml:ns:xmpp-sasl"
    namespaces.stanzas = "urn:ietf:params:xml:ns:xmpp-stanzas"
    namespaces.streams = "urn:ietf:params:xml:ns:xmpp-streams"
    namespaces.stream_management = "urn:xmpp:sm:3"
    namespaces.aioxmpp = "https://zombofant.net/xmlns/aioxmpp"
    namespaces.aioxmpp_test = "https://zombofant.net/xmlns/aioxmpp#test"
    namespaces.aioxmpp_internal = "https://zombofant.net/xmlns/aioxmpp#internal"
    namespaces.xml = "http://www.w3.org/XML/1998/namespace"

    @contextlib.contextmanager
    def background_task(coro, logger):
        def log_result(task):
            try:
                result = task.result()
            except asyncio.CancelledError:
                logger.debug("background task terminated by CM exit: %r",
                             task)
            except:  # NOQA
                logger.error("background task failed: %r",
                             task,
                             exc_info=True)
            else:
                if result is not None:
                    logger.info("background task (%r) returned a value: %r",
                                task,
                                result)

        task = asyncio.ensure_future(coro)
        task.add_done_callback(log_result)
        try:
            yield
        finally:
            task.cancel()

    class magicmethod:
        """
        Decorator for methods that makes them work as instance *and* class
        method.  The first argument will be the class if called on the
        class and the instance when called on the instance.
        """

        __slots__ = ("_f",)

        def __init__(self, f):
            super().__init__()
            self._f = f

        def __get__(self, instance, class_):
            if instance is None:
                return types.MethodType(self._f, class_)
            return types.MethodType(self._f, instance)

    def mkdir_exist_ok(path):
        """
        Create a directory (including parents) if it does not exist yet.

        :param path: Path to the directory to create.
        :type path: :class:`pathlib.Path`

        Uses :meth:`pathlib.Path.mkdir`; if the call fails with
        :class:`FileNotFoundError` and `path` refers to a directory, it is treated
        as success.
        """

        try:
            path.mkdir(parents=True)
        except FileExistsError:
            if not path.is_dir():
                raise

    class LazyTask(asyncio.Future):
        """
        :class:`asyncio.Future` subclass which spawns a coroutine when it is first
        awaited.

        :param coroutine_function: The coroutine function to invoke.
        :param args: Arguments to pass to `coroutine_function`.

        :class:`LazyTask` objects are awaitable. When the first attempt to await
        them is made, the `coroutine_function` is started with the given `args` and
        the result is awaited. Any further awaits on the :class:`LazyTask` will
        await the same coroutine.
        """

        def __init__(self, coroutine_function, *args):
            super().__init__()
            self.__coroutine_function = coroutine_function
            self.__args = args
            self.__task = None

        def add_done_callback(self, cb, *args):
            self.__start_task()
            return super().add_done_callback(cb, *args)

        def __start_task(self):
            if self.__task is None:
                self.__task = asyncio.ensure_future(
                    self.__coroutine_function(*self.__args)
                )
                self.__task.add_done_callback(self.__task_done)

        def __task_done(self, task):
            if task.exception():
                self.set_exception(task.exception())
            else:
                self.set_result(task.result())

        def __iter__(self):
            self.__start_task()
            return iter(self.__task)

        if hasattr(asyncio.Future, "__await__"):
            def __await__(self):
                self.__start_task()
                if hasattr(self.__task, "__await__"):
                    return self.__task.__await__()
                else:
                    return super().__await__()

    async def gather_reraise_multi(*fut_or_coros, message="gather_reraise_multi"):
        """
        Wrap all the arguments `fut_or_coros` in futures with
        :func:`asyncio.ensure_future` and wait until all of them are finish or
        fail.

        :param fut_or_coros: the futures or coroutines to wait for
        :type fut_or_coros: future or coroutine
        :param message: the message included with the raised
            :class:`aioxmpp.errors.GatherError` in the case of failure.
        :type message: :class:`str`
        :returns: the list of the results of the arguments.
        :raises aioxmpp.errors.GatherError: if any of the futures or
            coroutines fail.

        If an exception was raised, reraise all exceptions wrapped in a
        :class:`aioxmpp.errors.GatherError` with the message set to
        `message`.

        .. note::

           This is similar to the standard function
           :func:`asyncio.gather`, but avoids the in-band signalling of
           raised exceptions as return values, by raising exceptions bundled
           as a :class:`aioxmpp.errors.GatherError`.

        .. note::

           Use this function only if you are either

           a) not interested in the return values, or

           b) only interested in the return values if all futures are
              successful.
        """
        todo = [asyncio.ensure_future(fut_or_coro) for fut_or_coro in fut_or_coros]
        if not todo:
            return []

        await asyncio.wait(todo)
        results = []
        exceptions = []
        for fut in todo:
            if fut.exception() is not None:
                exceptions.append(fut.exception())
            else:
                results.append(fut.result())
        if exceptions:
            raise aioxmpp.errors.GatherError(message, exceptions)
        return results

    def to_nmtoken(rand_token):
        """
        Convert a (random) token given as raw :class:`bytes` or
        :class:`int` to a valid NMTOKEN
        <https://www.w3.org/TR/xml/#NT-Nmtoken>.

        The encoding as a valid nmtoken is injective, ensuring that two
        different inputs cannot yield the same token. Nevertheless, it is
        recommended to only use one kind of inputs (integers or bytes of a
        consistent length) in one context.
        """

        if isinstance(rand_token, int):
            rand_token = rand_token.to_bytes(
                (rand_token.bit_length() + 7) // 8,
                "little"
            )
            e = base64.urlsafe_b64encode(rand_token).rstrip(b"=").decode("ascii")
            return ":" + e

        if isinstance(rand_token, bytes):
            e = base64.urlsafe_b64encode(rand_token).rstrip(b"=").decode("ascii")
            if not e:
                e = "."
            return  e

        raise TypeError("rand_token musst be a bytes or int instance")

    class AlivenessMonitor:
        """
        Monitors aliveness of a data stream.

        .. versionadded:: 0.10

        :param loop: The event loop to operate the checks in.
        :type loop: :class:`asyncio.BaseEventLoop`

        This class is a utility class to implement a traffic-efficient timeout
        mechanism.

        This class can be used to monitor a stream if it is possible to ask the
        remote party send some data (classic ping mechanism). It works particularly
        well if the remote party will send data even without being specifically
        asked for it (saves traffic).

        It is notabily not a mean to enforce a maximum acceptable round-trip time.
        Quite on the contrary, this class was designed specifically to provide a
        reliable experience even *without* an upper bound on the round-trip time.

        To use this class, the using code has to configure the
        :attr:`deadtime_soft_limit`, :attr:`deadtime_hard_limit`, subscribe to the
        signals below and call :meth:`notify_received` whenever *any* data is
        received from the peer.

        There exist two timers, the *soft limit timer* and the *hard limit timer*
        (configured by the respective limit attributes). When the class is
        instantiated, the timers are reset to zero (*but* they start running
        immediately!).

        When a timer exceeds its respective limit, its corresponding signal is
        emitted. The signal is not re-emitted until the next call of
        :meth:`notfiy_received`.

        When :meth:`notify_received` is called, the timers are reset to zero.

        This allows for the following features:

        - Keep a stream alive on a high-latency link as long as data is pouring in.

          This is very useful on saturated (mobile) links. Imagine firing a MAM
          query and a bunch of avatar requests after connecting. With naive ping
          logic, this would easily cause the stream to be considered dead because
          the round-trip time is extremely high.

          However, with this logic, as long as data is pouring in, the stream is
          considered alive.

        - When using the soft limit to trigger a ping and a reasonable difference
          between the soft and the hard limit timeout, this logic gracefully
          reverts to classic pinging when no traffic is seen on the stream.

        - If the peer is pinging us in an interval which works for us (i.e. is less
          than the soft limit), we don’t need to ping the peer; no extra logic
          required.

        This mechanism is used by :class:`aioxmpp.protocol.XMLStream`.

        .. signal:: on_deadtime_soft_limit_tripped()

            Emits when the :attr:`deadtime_soft_limit` expires.

        .. signal:: on_deadtime_hard_limit_tripped()

            Emits when the :attr:`deadtime_hard_limit` expires.

        .. automethod:: notify_received

        .. autoattribute:: deadtime_soft_limit
            :annotation: = None

        .. autoattribute:: deadtime_hard_limit
            :annotation: = None

        """

        on_deadtime_soft_limit_tripped = aioxmpp.callbacks.Signal()
        on_deadtime_hard_limit_tripped = aioxmpp.callbacks.Signal()

        def __init__(self, loop):
            super().__init__()
            self._loop = loop
            self._soft_limit = None
            self._soft_limit_timer = None
            self._soft_limit_tripped = False
            self._hard_limit = None
            self._hard_limit_timer = None
            self._hard_limit_tripped = False
            self._reset_trips()

        def _trip_soft_limit(self):
            if self._soft_limit_tripped:
                return
            self._soft_limit_tripped = True
            self.on_deadtime_soft_limit_tripped()

        def _trip_hard_limit(self):
            if self._hard_limit_tripped:
                return
            self._hard_limit_tripped = True
            self.on_deadtime_hard_limit_tripped()

        def _retrigger_timers(self):
            now = time.monotonic()

            if self._soft_limit_timer is not None:
                self._soft_limit_timer.cancel()
                self._soft_limit_timer = None

            if self._soft_limit is not None:
                self._soft_limit_timer = self._loop.call_later(
                    self._soft_limit.total_seconds() - (now - self._last_rx),
                    self._trip_soft_limit
                )

            if self._hard_limit_timer is not None:
                self._hard_limit_timer.cancel()
                self._hard_limit_timer = None

            if self._hard_limit is not None:
                self._hard_limit_timer = self._loop.call_later(
                    self._hard_limit.total_seconds() - (now - self._last_rx),
                    self._trip_hard_limit
                )

        def _reset_trips(self):
            self._soft_limit_tripped = False
            self._hard_limit_tripped = False
            self._last_rx = time.monotonic()

        def notify_received(self):
            """
            Inform the aliveness check that something was received.

            Resets the internal soft/hard limit timers.
            """
            self._reset_trips()
            self._retrigger_timers()

        @property
        def deadtime_soft_limit(self):
            """
            Soft limit for the timespan in which no data is received in the stream.

            When the last data reception was longer than this limit ago,
            :meth:`on_deadtime_soft_limit_tripped` emits once.

            Changing this makes the monitor re-check its limits immediately. Setting
            this to :data:`None` disables the soft limit check.

            Note that setting this to a value greater than
            :attr:`deadtime_hard_limit` means that the hard limit will fire first.
            """
            return self._soft_limit

        @deadtime_soft_limit.setter
        def deadtime_soft_limit(self, value):
            if self._soft_limit_timer is not None:
                self._soft_limit_timer.cancel()
            self._soft_limit = value
            self._retrigger_timers()

        @property
        def deadtime_hard_limit(self):
            """
            Hard limit for the timespan in which no data is received in the stream.

            When the last data reception was longer than this limit ago,
            :meth:`on_deadtime_hard_limit_tripped` emits once.

            Changing this makes the monitor re-check its limits immediately. Setting
            this to :data:`None` disables the hard limit check.

            Note that setting this to a value less than
            :attr:`deadtime_soft_limit` means that the hard limit will fire first.
            """
            return self._hard_limit

        @deadtime_hard_limit.setter
        def deadtime_hard_limit(self, value):
            if self._hard_limit_timer is not None:
                self._hard_limit_timer.cancel()
            self._hard_limit = value
            self._retrigger_timers()

    def proxy_property(owner_attr, member_attr, *,
                       readonly=False,
                       allow_delete=False):
        """
        Proxy a property of a member.

        :param owner_attr: The name of the attribute at which the member can
            be found.
        :type owner_attr: :class:`str`
        :param member_attr: The name of the member property to proxy.
        :type member_attr: :class:`str`
        :param readonly: If true, the proxied property will not be writable, even
            if the original property is writable.
        :type readonly: :class:`bool`
        :param allow_delete: If true, the ``del`` operator is allowed on the
            proxy property and will be forwarded to the target property.
        :type allow_delete: :class:`bool`

        .. versionadded:: 0.11.0

        This can be useful when combining classes via composition instead of
        inheritance.

        It is not necessary to set `readonly` to true if the target property is
        already readonly.
        """
        ga = getattr
        sa = setattr
        da = delattr

        def getter(instance):
            return ga(ga(instance, owner_attr), member_attr)

        if readonly:
            setter = None
        else:
            def setter(instance, value):
                return sa(ga(instance, owner_attr), member_attr, value)

        if allow_delete:
            def deleter(instance):
                da(ga(instance, owner_attr), member_attr)
        else:
            deleter = None

        return property(
            getter,
            setter,
            deleter,
        )