# Source code for aioxmpp.im.conversation

    ########################################################################
    # File name: conversation.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 abc
    import asyncio
    import enum

    import aioxmpp.callbacks

    class InviteMode(enum.Enum):
        """
        Represent different possible modes for sending an invitation.

        .. attribute:: DIRECT

           The invitation is sent directly to the invitee, without going through a
           service specific to the conversation.

        .. attribute:: MEDIATED

           The invitation is sent indirectly through a service which is providing
           the conversation. Advantages of using this mode include most notably
           that the service can automatically add the invitee to the list of
           allowed participants in configurations where such restrictions exist (or
           deny the request if the inviter does not have the permissions to do so).
        """

        DIRECT = 0
        MEDIATED = 1

    class ConversationFeature(enum.Enum):
        """
        Represent individual features of a :term:`Conversation` of a
        :term:`Conversation Implementation`.

        .. seealso::

           The :attr:`.AbstractConversation.features` provides a set of features
           offered by a specific :term:`Conversation`.

        .. attribute:: BAN

           Allows use of :meth:`~.AbstractConversation.ban`.

        .. attribute:: BAN_WITH_KICK

           Explicit support for setting the `request_kick` argument to :data:`True`
           in :meth:`~.AbstractConversation.ban`.

        .. attribute:: INVITE

           Allows use of :meth:`~.AbstractConversation.invite`.

        .. attribute:: INVITE_DIRECT

           Explicit support for the :attr:`~.InviteMode.DIRECT` invite mode when
           calling :meth:`~.AbstractConversation.invite`.

        .. attribute:: INVITE_DIRECT_CONFIGURE

           Explicit support for configuring the conversation to allow the invitee
           to join when using :attr:`~.InviteMode.DIRECT` with
           :meth:`~.AbstractConversation.invite`.

        .. attribute:: INVITE_MEDIATED

           Explicit support for the :attr:`~.InviteMode.MEDIATED` invite mode when
           calling :meth:`~.AbstractConversation.invite`.

        .. attribute:: INVITE_UPGRADE

           Explicit support and requirement for `allow_upgrade` when
           calling :meth:`~.AbstractConversation.invite`.

        .. attribute:: KICK

           Allows use of :meth:`~.AbstractConversation.kick`.

        .. attribute:: LEAVE

           Allows use of :meth:`~.AbstractConversation.leave`.

        .. attribute:: SEND_MESSAGE

           Allows use of :meth:`~.AbstractConversation.send_message`.

        .. attribute:: SEND_MESSAGE_TRACKED

           Allows use of :meth:`~.AbstractConversation.send_message_tracked`.

        .. attribute:: SET_NICK

           Allows use of :meth:`~.AbstractConversation.set_nick`.

        .. attribute:: SET_NICK_OF_OTHERS

           Explicit support for changing the nickname of other members when calling
           :meth:`~.AbstractConversation.set_nick`.

        .. attribute:: SET_TOPIC

           Allows use of :meth:`~.AbstractConversation.set_topic`.

        """

        BAN = 'ban'
        BAN_WITH_KICK = 'ban-with-kick'
        INVITE = 'invite'
        INVITE_DIRECT = 'invite-direct'
        INVITE_DIRECT_CONFIGURE = 'invite-direct-configure'
        INVITE_MEDIATED = 'invite-mediated'
        INVITE_UPGRADE = 'invite-upgrade'
        KICK = 'kick'
        LEAVE = 'leave'
        SEND_MESSAGE = 'send-message'
        SEND_MESSAGE_TRACKED = 'send-message-tracked'
        SET_TOPIC = 'set-topic'
        SET_NICK = 'set-nick'
        SET_NICK_OF_OTHERS = 'set-nick-of-others'

    class ConversationState(enum.Enum):
        """
        State of a conversation.

        .. note::

           The members of this enumeration closely mirror the states of :xep:`85`,
           with the addition of the internal :attr:`PENDING` state. The reason is
           that :xep:`85` is a Final Standard and is state-of-the-art for
           conversation states in XMPP.

        .. attribute:: PENDING

           The conversation has been created, possibly automatically, and the
           application has not yet set the conversation state.

        .. attribute:: ACTIVE

           .. epigraph::

              User accepts an initial content message, sends a content message,
              gives focus to the chat session interface (perhaps after being
              inactive), or is otherwise paying attention to the conversation.

              -- from :xep:`85`

        .. attribute:: INACTIVE

           .. epigraph::

              User has not interacted with the chat session interface for an
              intermediate period of time (e.g., 2 minutes).

              -- from :xep:`85`

        .. attribute:: GONE

           .. epigraph::

              User has not interacted with the chat session interface, system, or
              device for a relatively long period of time (e.g., 10 minutes).

              -- from :xep:`85`

        .. attribute:: COMPOSING

           .. epigraph::

              User is actively interacting with a message input interface specific
              to this chat session (e.g., by typing in the input area of a chat
              window).

              -- from :xep:`85`

        .. attribute:: PAUSED

           .. epigraph::

              User was composing but has not interacted with the message input
              interface for a short period of time (e.g., 30 seconds).

              -- from :xep:`85`

        When any of the above states is entered, a notification is sent out to the
        participants of the conversation.
        """

        PENDING = 0
        ACTIVE = 1
        INACTIVE = 2
        GONE = 3
        COMPOSING = 4
        PAUSED = 5

    class AbstractConversationMember(metaclass=abc.ABCMeta):
        """
        Represent a member in a :class:`~.AbstractConversation`.

        While all :term:`implementations <Conversation Implementation>` will have
        their own additional attributes, the following attributes must exist on
        all subclasses:

        .. autoattribute:: conversation_jid

        .. autoattribute:: direct_jid

        .. autoattribute:: is_self

        .. autoattribute:: uid
        """

        def __init__(self,
                     conversation_jid,
                     is_self):
            super().__init__()
            self._conversation_jid = conversation_jid
            self._is_self = is_self

        @property
        def direct_jid(self):
            """
            If available, this is the :class:`~aioxmpp.JID` address of the member
            for direct contact, outside of the conversation. It is independent of
            the conversation itself.

            If not available, this attribute reads as :data:`None`.
            """
            return None

        @property
        def conversation_jid(self):
            """
            The :class:`~aioxmpp.JID` of the conversation member relative to the
            conversation.
            """
            return self._conversation_jid

        @property
        def is_self(self):
            """
            True if the member refers to ourselves in the conversation, false
            otherwise.
            """
            return self._is_self

        @abc.abstractproperty
        def uid(self) -> bytes:
            """
            This is a unique ID for the occupant. It can be used across sessions
            and restarts to assert equality between occupants. It is guaranteed
            to be equal if and only if the entity is the same (up to a uncertainty
            caused by the limited length of the unique ID, somewhere in the order
            of ``2**(-120)``).

            The identifier is always a :class:`bytes` and **must** be treated as
            opaque by users. The only guarantee which is given is that its length
            will be less than 4096 bytes.
            """

    class AbstractConversation(metaclass=abc.ABCMeta):
        """
        Interface for a conversation.

        .. note::

           All signals may receive additional keyword arguments depending on the
           specific subclass implementing them. Handlers connected to the signals
           **must** support arbitrary keyword arguments.

           To support future extensions to the base specification, subclasses must
           prefix all keyword argument names with a common, short prefix which ends
           with an underscore. For example, a MUC implementation could use
           ``muc_presence``.

           Future extensions to the base class will use either names without
           underscores or the ``base_`` prefix.

        .. note::

           In the same spirit, methods defined on subclasses should use the same
           prefix. However, the base class does not guarantee that it won’t use
           names with underscores in future extensions.

           To prevent collisions, subclasses should avoid the use of prefixes which
           are verbs in the english language.

        Signals:

        .. note::

            The `member` argument common to many signals is never :data:`None` and
            always an instance of a subclass of
            :class:`~.AbstractConversationMember`. However, the `member` may not be
            part of the :attr:`members` of the conversation. For example, it may be
            the :attr:`service_member` object which is never part of
            :attr:`members`. Other cases where a non-member is passed as `member`
            may exist depending on the conversation subclass.

        .. signal:: on_message(msg, member, source, tracker=None, **kwargs)

           A message occurred in the conversation.

           :param msg: Message which was received.
           :type msg: :class:`aioxmpp.Message`
           :param member: The member object of the sender.
           :type member: :class:`.AbstractConversationMember`
           :param source: How the message was acquired
           :type source: :class:`~.MessageSource`
           :param tracker: A message tracker which tracks an outbound message.
           :type tracker: :class:`aioxmpp.tracking.MessageTracker`

           This signal is emitted on the following events:

           * A message was sent to the conversation and delivered directly to us.
             This is the classic case of "a message was received". In this case,
             `source` is :attr:`~.MessageSource.STREAM` and `member` is the
             :class:`~.AbstractConversationMember` of the originator.

           * A message was sent from this client. This is the classic case of "a
             message was sent". In this case, `source` is
             :attr:`~.MessageSource.STREAM` and `member` refers to ourselves.

           * A carbon-copy of a message received by another resource of our account
             which belongs to this conversation was received. `source` is
             :attr:`~.MessageSource.CARBONS` and `member` is the
             :class:`~.AbstractConversationMember` of the originator.

           * A carbon-copy of a message sent by another resource of our account was
             sent to this conversation. In this case, `source` is
             :attr:`~.MessageSource.CARBONS` and `member` refers to ourselves.

           Often, you don’t need to distinguish between carbon-copied and
           non-carbon-copied messages.

           All messages which are not handled otherwise (and for example dispatched
           as :meth:`on_state_changed` signals) are dispatched to this event. This
           may include messages not understood and/or which carry no textual
           payload.

           `tracker` is set only for messages sent by the local member. If a
           message is sent from the client without tracking, `tracker` is
           :data:`None`; otherwise, the `tracker` is always set, even for messages
           sent by other clients. It depends on the conversation implementation as
           well as timing in which state a tracker is at the time the event is
           emitted.

        .. signal:: on_state_changed(member, new_state, msg, **kwargs)

           The conversation state of a member has changed.

           :param member: The member object of the member whose state changed.
           :type member: :class:`.AbstractConversationMember`
           :param new_state: The new conversation state of the member.
           :type new_state: :class:`~.ConversationState`
           :param msg: The stanza which conveyed the state change.
           :type msg: :class:`aioxmpp.Message`

           This signal also fires for state changes of the local occupant. The
           exact point at which this signal fires for the local occupant is
           determined by the implementation.

        .. signal:: on_presence_changed(member, resource, presence, **kwargs)

           The presence state of a member has changed.

           :param member: The member object of the affected member.
           :type member: :class:`~.AbstractConversationMember`
           :param resource: The resource of the member which changed presence.
           :type resource: :class:`str` or :data:`None`
           :param presence: The presence stanza
           :type presence: :class:`aioxmpp.Presence`

           If the `presence` stanza affects multiple resources, `resource` holds
           the affected resource and the event is emitted once per affected
           resource.

           However, the `presence` stanza affects only a single resource,
           `resource` is :data:`None`; the affected resource can be extracted from
           the :attr:`~.StanzaBase.from_` of the `presence` stanza in that case.
           This is to help implementations to know whether a bunch of resources was
           shot offline by a single presence (`resource` is not :data:`None`), e.g.
           due to an error or whether a single resource went offline by itself.
           Implementations may want to only show the former case.

           .. note::

              In some implementations, unavailable presence implies that a
              participant leaves the room, in which case :meth:`on_leave` is
              emitted instead.

        .. signal:: on_nick_changed(member, old_nick, new_nick, **kwargs)

           The nickname of a member has changed

           :param member: The member object of the member whose nick has changed.
           :type member: :class:`~.AbstractConversationMember`
           :param old_nick: The old nickname of the member.
           :type old_nick: :class:`str` or :data:`None`
           :param new_nick: The new nickname of the member.
           :type new_nick: :class:`str`

           The new nickname is already set in the `member` object, if the `member`
           object has an accessor for the nickname.

           In some cases, `old_nick` may be :data:`None`. These cases include those
           where it is not trivial for the protocol to actually determine the old
           nickname or where no nickname was set before.

        .. signal:: on_topic_changed(member, new_topic, **kwargs)

            The topic of the conversation has changed.

            :param member: The member object who changed the topic.
            :type member: :class:`~.AbstractConversationMember`
            :param new_topic: The new topic of the conversation.
            :type new_topic: :class:`.LanguageMap`

        .. signal:: on_uid_changed(member, old_uid, **kwargs)

            This rare signal notifies that the
            :attr:`~.AbstractConversationMember.uid` of a member has changed.

            :param member: The member object for which the UID has changed.
            :type member: :class:`~.AbstractConversationMember`
            :param old_uid: The old UID of the member.
            :type old_uid: :class:`bytes`

            The new uid is already available at the members
            :attr:`~.AbstractConversationMember.uid` attribute.

            This signal can only fire for multi-user conversations where the
            visibility of identifying information changes. In many cases, it will
            be irrelevant for the application, but for some use-cases it might be
            important to be able to re-write historical messages to use the new
            uid.

        .. signal:: on_enter()

            The conversation was entered.

            This event is emitted up to once for a :class:`AbstractConversation`.

            One of :meth:`on_enter` and :meth:`on_failure` is emitted exactly
            once for each :class:`AbstractConversation` instance.

            .. seealso::

                :func:`aioxmpp.callbacks.first_signal` can be used nicely to await
                the completion of entering a conversation::

                    conv = ... # let this be your conversation
                    await first_signal(conv.on_enter, conv.on_failure)
                    # await first_signal() will either return None (success) or
                    # raise the exception passed to :meth:`on_failure`.

            .. note::

                This and :meth:`on_failure` are the only signals which **must not**
                receive keyword arguments, so that they continue to work with
                :attr:`.AdHocSignal.AUTO_FUTURE` and
                :func:`~.callbacks.first_signal`.

            .. versionadded:: 0.10

        .. signal:: on_failure(exc)

            The conversation could not be entered.

            :param exc: The exception which caused the operation to fail.
            :type exc: :class:`Exception`

            Often, `exc` will be a :class:`aioxmpp.errors.XMPPError` indicating
            an error emitted from an involved server, such as permission problems,
            conflicts or non-existent peers.

            This signal can only be emitted instead of :meth:`on_enter` and not
            after the room has been entered. If the conversation is terminated
            due to a remote cause at a later point, :meth:`on_exit` is used.

            One of :meth:`on_enter` and :meth:`on_failure` is emitted exactly
            once for each :class:`AbstractConversation` instance.

            .. note::

                This and :meth:`on_failure` are the only signals which **must not**
                receive keyword arguments, so that they continue to work with
                :attr:`.AdHocSignal.AUTO_FUTURE` and
                :func:`~.callbacks.first_signal`.

            .. versionadded:: 0.10

        .. signal:: on_join(member, **kwargs)

           A new member has joined the conversation.

           :param member: The member object of the new member.
           :type member: :class:`~.AbstractConversationMember`

           When this signal is called, the `member` is already included in the
           :attr:`members`.

        .. signal:: on_leave(member, **kwargs)

           A member has left the conversation.

           :param member: The member object of the previous member.
           :type member: :class:`~.AbstractConversationMember`

           When this signal is called, the `member` has already been removed from
           the :attr:`members`.

        .. signal:: on_exit(**kwargs)

           The local user has left the conversation.

           When this signal fires, the conversation is defunct in the sense that it
           cannot be used to send messages anymore. A new conversation needs to be
           started.

        Properties:

        .. autoattribute:: features

        .. autoattribute:: jid

        .. autoattribute:: members

        .. autoattribute:: me

        .. autoattribute:: service_member

        Methods:

        .. note::

           See :attr:`features` for discovery of support for individual methods at
           a given conversation instance.

        .. automethod:: ban

        .. automethod:: invite

        .. automethod:: kick

        .. automethod:: leave

        .. automethod:: send_message

        .. automethod:: send_message_tracked

        .. automethod:: set_nick

        .. automethod:: set_topic

        Interface solely for subclasses:

        .. attribute:: _client

           The `client` as passed to the constructor.

        """

        on_message = aioxmpp.callbacks.Signal()
        on_state_changed = aioxmpp.callbacks.Signal()
        on_presence_changed = aioxmpp.callbacks.Signal()
        on_join = aioxmpp.callbacks.Signal()
        on_leave = aioxmpp.callbacks.Signal()
        on_exit = aioxmpp.callbacks.Signal()
        on_failed = aioxmpp.callbacks.Signal()
        on_nick_changed = aioxmpp.callbacks.Signal()
        on_enter = aioxmpp.callbacks.Signal()
        on_failure = aioxmpp.callbacks.Signal()
        on_topic_changed = aioxmpp.callbacks.Signal()

        def __init__(self, service, parent=None, **kwargs):
            super().__init__(**kwargs)
            self._service = service
            self._client = service.client
            self.__parent = parent

        def _not_implemented_error(self, what):
            return NotImplementedError(
                "{} not supported for this type of conversation".format(what)
            )

        @property
        def parent(self):
            """
            The conversation to which this conversation belongs. Read-only.

            When the parent is closed, the sub-conversations are also closed.
            """
            return self.__parent

        @abc.abstractproperty
        def members(self):
            """
            An iterable of members of this conversation.
            """

        @abc.abstractproperty
        def me(self):
            """
            The member representing the local member.
            """

        @abc.abstractproperty
        def jid(self):
            """
            The address of the conversation.
            """

        @property
        def service_member(self):
            """
            The member representing the service on which the conversation is
            hosted, if available.

            This is never included in :attr:`members`. It may be used as member
            argument in events to make it clear that the message originates from
            the service and not an unknown occupant.

            This may be :data:`None`.

            .. versionadded:: 0.10
            """

        @property
        def features(self):
            """
            A set of features supported by this :term:`Conversation`.

            The members of the set are usually drawn from the
            :class:`~.ConversationFeature` :mod:`enumeration <enum>`;
            :term:`Conversation  Implementations <Conversation Implementation>` are
            free to add custom elements from other enumerations to this set.

            Unless stated otherwise, the methods of :class:`~.AbstractConversation`
            and its subclasses always may throw one of the following exceptions,
            **unless** support for those methods is explicitly stated with an
            appropriate :class:`~.ConversationFeature` member in the
            :attr:`features`.

            * :class:`NotImplementedError` if the :term:`Conversation
              Implementation` does not support the method at all.
            * :class:`RuntimeError` if the server does not support the method.
            * :class:`aioxmpp.XMPPCancelError` with ``feature-not-implemented``
              condition.

            *If* support for the method is claimed in :attr:`features`, these
            exceptions **must not** be raised (for the given reason; of course, a
            method may still raise an :class:`aioxmpp.XMPPCancelError` due for
            other conditions such as ``item-not-found``).
            """
            return frozenset()

        def send_message(self, body):
            """
            Send a message to the conversation.

            :param msg: The message to send.
            :type msg: :class:`aioxmpp.Message`
            :return: The stanza token obtained from sending.
            :rtype: :class:`~aioxmpp.stream.StanzaToken`

            The default implementation simply calls :meth:`send_message_tracked`
            and immediately cancels the tracking object, returning only the stanza
            token.

            There is no need to provide proper address attributes on `msg`.
            Implementations will override those attributes with the values
            appropriate for the conversation. Some implementations may allow the
            user to choose a :attr:`~aioxmpp.Message.type_`, but others may simply
            stamp it over.

            Subclasses may override this method with a more specialised
            implementation. Subclasses which do not provide tracked message sending
            **must** override this method to provide untracked message sending.

            .. seealso::

               The corresponding feature is
               :attr:`.ConversationFeature.SEND_MESSAGE`. See :attr:`features` for
               details.

            """
            token, tracker = self.send_message_tracked(body)
            tracker.cancel()
            return token

        @abc.abstractmethod
        def send_message_tracked(self, msg, *, timeout=None):
            """
            Send a message to the conversation with tracking.

            :param msg: The message to send.
            :type msg: :class:`aioxmpp.Message`
            :param timeout: Timeout for the tracking.
            :type timeout: :class:`numbers.RealNumber`, :class:`datetime.timedelta`
                           or :data:`None`
            :raise NotImplementedError: if tracking is not implemented
            :return: The stanza token obtained from sending and the
                :class:`aioxmpp.tracking.MessageTracker` tracking the delivery.
            :rtype: :class:`~aioxmpp.stream.StanzaToken`,
                :class:`~aioxmpp.tracking.MessageTracker`

            There is no need to provide proper address attributes on `msg`.
            Implementations will override those attributes with the values
            appropriate for the conversation. Some implementations may allow the
            user to choose a :attr:`~aioxmpp.Message.type_`, but others may simply
            stamp it over.

            Tracking may not be supported by all implementations, and the degree of
            support varies with implementation. Please check the documentation
            of the respective subclass.

            `timeout` is the number of seconds (or a :class:`datetime.timedelta`
            object which defines the timespan) after which the tracking expires and
            is closed if no response has been received in the mean time. If
            `timeout` is set to :data:`None`, the tracking never expires.

            .. warning::

                Read :ref:`api-tracking-memory`.

            .. seealso::

               The corresponding feature is
               :attr:`.ConversationFeature.SEND_MESSAGE_TRACKED`. See
               :attr:`features` for details.

            """

        async def kick(self, member, reason=None):
            """
            Kick a member from the conversation.

            :param member: The member to kick.
            :param reason: A reason to show to the members of the conversation
                including the kicked member.
            :type reason: :class:`str`
            :raises aioxmpp.errors.XMPPError: if the server returned an error for
                                              the kick command.

            .. seealso::

               The corresponding feature is
               :attr:`.ConversationFeature.KICK`. See :attr:`features` for details.
            """
            raise self._not_implemented_error("kicking members")

        async def ban(self, member, reason=None, *, request_kick=True):
            """
            Ban a member from re-joining the conversation.

            :param member: The member to ban.
            :param reason: A reason to show to the members of the conversation
                including the banned member.
            :type reason: :class:`str`
            :param request_kick: A flag indicating that the member should be
                removed from the conversation immediately, too.
            :type request_kick: :class:`bool`

            If `request_kick` is true, the implementation attempts to kick the
            member from the conversation, too, if that does not happen
            automatically. There is no guarantee that the member is not removed
            from the conversation even if `request_kick` is false.

            Additional features:

            :attr:`~.ConversationFeature.BAN_WITH_KICK`
               If `request_kick` is true, the member is kicked from the
               conversation.

            .. seealso::

               The corresponding feature for this method is
               :attr:`.ConversationFeature.BAN`. See :attr:`features` for details
               on the semantics of features.
            """
            raise self._not_implemented_error("banning members")

        async def invite(self, address, text=None, *,
                         mode=InviteMode.DIRECT,
                         allow_upgrade=False):
            """
            Invite another entity to the conversation.

            :param address: The address of the entity to invite.
            :type address: :class:`aioxmpp.JID`
            :param text: A reason/accompanying text for the invitation.
            :param mode: The invitation mode to use.
            :type mode: :class:`~.im.InviteMode`
            :param allow_upgrade: Whether to allow creating a new conversation to
                satisfy the invitation.
            :type allow_upgrade: :class:`bool`
            :raises NotImplementedError: if the requested `mode` is not supported
            :raises ValueError: if `allow_upgrade` is false, but a new conversation
                is required.
            :return: The stanza token for the invitation and the possibly new
                conversation object
            :rtype: tuple of :class:`~.StanzaToken` and
                :class:`~.AbstractConversation`

            .. note::

                Even though this is a coroutine, it returns a stanza token. The
                coroutine-ness may be needed to generate the invitation in the
                first place. Sending the actual invitation is done non-blockingly
                and the stanza token for that is returned. To wait until the
                invitation has been sent, unpack the stanza token from the result
                and await it.

            Return the new conversation object to use. In many cases, this will
            simply be the current conversation object, but in some cases (e.g. when
            someone is invited to a one-on-one conversation), a new conversation
            must be created and used.

            If `allow_upgrade` is false and a new conversation would be needed to
            invite an entity, :class:`ValueError` is raised.

            Additional features:

            :attr:`~.ConversationFeature.INVITE_DIRECT`
               Support for :attr:`~.im.InviteMode.DIRECT` mode.

            :attr:`~.ConversationFeature.INVITE_DIRECT_CONFIGURE`
               If a direct invitation is used, the conversation will be configured
               to allow the invitee to join before the invitation is sent. This may
               fail with a :class:`aioxmpp.errors.XMPPError`, in which case the
               error is re-raised and the invitation not sent.

            :attr:`~.ConversationFeature.INVITE_MEDIATED`
               Support for :attr:`~.im.InviteMode.MEDIATED` mode.

            :attr:`~.ConversationFeature.INVITE_UPGRADE`
               If `allow_upgrade` is :data:`True`, an upgrade will be performed and
               a new conversation is returned. If `allow_upgrade` is :data:`False`,
               the invite will fail.

            .. seealso::

               The corresponding feature for this method is
               :attr:`.ConversationFeature.INVITE`. See :attr:`features` for
               details on the semantics of features.
            """
            raise self._not_implemented_error("inviting entities")

        async def set_nick(self, new_nickname):
            """
            Change our nickname.

            :param new_nickname: The new nickname for the member.
            :type new_nickname: :class:`str`
            :raises ValueError: if the nickname is not a valid nickname

            Sends the request to change the nickname and waits for the request to
            be sent.

            There is no guarantee that the nickname change will actually be
            applied; listen to the :meth:`on_nick_changed` event.

            Implementations may provide a different method which provides more
            feedback.

            .. seealso::

               The corresponding feature for this method is
               :attr:`.ConversationFeature.SET_NICK`. See :attr:`features` for
               details on the semantics of features.

            """
            raise self._not_implemented_error("changing the nickname")

        async def set_topic(self, new_topic):
            """
            Change the (possibly publicly) visible topic of the conversation.

            :param new_topic: The new topic for the conversation.
            :type new_topic: :class:`str`

            Sends the request to change the topic and waits for the request to
            be sent.

            There is no guarantee that the topic change will actually be
            applied; listen to the :meth:`on_topic_chagned` event.

            Implementations may provide a different method which provides more
            feedback.

            .. seealso::

               The corresponding feature for this method is
               :attr:`.ConversationFeature.SET_TOPIC`. See :attr:`features` for
               details on the semantics of features.

            """
            raise self._not_implemented_error("changing the topic")

        async def leave(self):
            """
            Leave the conversation.

            .. seealso::

               The corresponding feature is
               :attr:`.ConversationFeature.LEAVE`. See :attr:`features` for
               details.
            """

    class AbstractConversationService(metaclass=abc.ABCMeta):
        """
        Abstract base class for
        :term:`Conversation Services <Conversation Service>`.

        Useful implementations:

        .. autosummary::

            aioxmpp.im.p2p.Service
            aioxmpp.muc.MUCClient

        In general, conversation services should provide a method (*not* a
        coroutine method) to start a conversation using the service. That method
        should return the fresh :class:`~.AbstractConversation` object immediately
        and start possibly needed background tasks to actually initiate the
        conversation. The caller should use the
        :meth:`~.AbstractConversation.on_enter` and
        :meth:`~.AbstractConversation.on_failure` signals to be notified of the
        result of the join operation.

        Signals:

        .. signal:: on_conversation_new(conversation)

            Fires when a new conversation is created in the service.

            :param conversation: The new conversation.
            :type conversation: :class:`AbstractConversation`

            .. seealso::

                :meth:`.ConversationService.on_conversation_added`
                    is a signal shared among all :term:`Conversation
                    Implementations <Conversation Implementation>` which gets
                    emitted whenever a new conversation is added. If you need all
                    conversations, that is the signal to listen for.

        .. signal:: on_spontaneous_conversation(conversation)

            Like :meth:`on_conversation_new`, but is only emitted for conversations
            which are created without local interaction.

            :param conversation: The new conversation.
            :type conversation: :class:`AbstractConversation`

            .. versionadded:: 0.10

        """

        on_conversation_new = aioxmpp.callbacks.Signal()
        on_spontaneous_conversation = aioxmpp.callbacks.Signal()