########################################################################
# 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'
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
[docs]class AbstractConversationMember(metaclass=abc.ABCMeta):
def __init__(self,
conversation_jid,
is_self):
super().__init__()
self._conversation_jid = conversation_jid
self._is_self = is_self
@property
def direct_jid(self):
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):
return self._is_self
[docs]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:
.. signal:: on_message(msg, member, source, **kwargs)
A message occured 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`
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.
.. 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 emmited 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_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
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()
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
[docs] def members(self):
"""
An iterable of members of this conversation.
"""
@abc.abstractproperty
[docs] def me(self):
"""
The member representing the local member.
"""
@abc.abstractproperty
[docs] def jid(self):
"""
The address of the conversation.
"""
@property
[docs] 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 set()
[docs] 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 = yield from self.send_message_tracked(body)
tracker.cancel()
return token
@abc.abstractmethod
[docs] 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.
"""
@asyncio.coroutine
[docs] 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")
@asyncio.coroutine
[docs] 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")
@asyncio.coroutine
[docs] def invite(self, jid, *,
preferred_mode=InviteMode.DIRECT,
allow_upgrade=False):
"""
Invite another entity to the conversation.
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`
If `preferred_mode` is :attr:`~.im.InviteMode.DIRECT`, a direct
invitation will be used.
: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`
If `preferred_mode` is :attr:`~.im.InviteMode.MEDIATED`, a mediated
invitation will be used.
: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")
@asyncio.coroutine
[docs] 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")
@asyncio.coroutine
[docs] 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")
@asyncio.coroutine
[docs] def leave(self):
"""
Leave the conversation.
.. seealso::
The corresponding feature is
:attr:`.ConversationFeature.LEAVE`. See :attr:`features` for
details.
"""
class AbstractConversationService(metaclass=abc.ABCMeta):
on_conversation_new = aioxmpp.callbacks.Signal()
on_conversation_left = aioxmpp.callbacks.Signal()