v1.3.5
This commit is contained in:
@@ -0,0 +1,124 @@
|
||||
########################################################################
|
||||
# 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.im` --- Instant Messaging Utilities and Services
|
||||
###############################################################
|
||||
|
||||
This subpackage provides tools for Instant Messaging applications based on
|
||||
XMPP. The tools are meant to be useful for both user-facing as well as
|
||||
automated IM applications.
|
||||
|
||||
.. warning::
|
||||
|
||||
:mod:`aioxmpp.im` is highly experimental, even more than :mod:`aioxmpp` by
|
||||
itself is. This is not a threat, this is a chance. Please play with the
|
||||
API, try to build an application around it, and let us know how it feels!
|
||||
This is your chance to work with us on the API.
|
||||
|
||||
On the other hand, yes, there is a risk that we’ll restructure the API
|
||||
massively in the next release, even though it works quite well for our
|
||||
applications currently.
|
||||
|
||||
|
||||
Terminology
|
||||
===========
|
||||
|
||||
This is a short overview of the terminology. The full definitions can be found
|
||||
in the glossary and are linked.
|
||||
|
||||
:term:`Conversation`
|
||||
Communication context for two or more parties.
|
||||
:term:`Conversation Member`
|
||||
An entity taking part in a :term:`Conversation`.
|
||||
:term:`Conversation Implementation`
|
||||
A :term:`Service` which provides means to create and manage specific
|
||||
:class:`~.AbstractConversation` subclasses.
|
||||
:term:`Service Member`
|
||||
A :term:`Conversation Member` which represents the service over which the
|
||||
conversation is run inside the conversation.
|
||||
|
||||
.. module:: aioxmpp.im.p2p
|
||||
|
||||
:mod:`.im.p2p` --- One-on-one conversations
|
||||
===========================================
|
||||
|
||||
.. autoclass:: Service
|
||||
|
||||
.. autoclass:: Conversation
|
||||
|
||||
.. autoclass:: Member
|
||||
|
||||
.. currentmodule:: aioxmpp.im
|
||||
|
||||
:mod:`aioxmpp.muc` --- Multi-User-Chats (:xep:`45`)
|
||||
===================================================
|
||||
|
||||
.. seealso::
|
||||
|
||||
:mod:`aioxmpp.muc`
|
||||
has a :term:`Conversation Implementation` for MUCs.
|
||||
|
||||
Core Services
|
||||
=============
|
||||
|
||||
.. autoclass:: ConversationService
|
||||
|
||||
|
||||
Enumerations
|
||||
============
|
||||
|
||||
.. autoclass:: ConversationState
|
||||
|
||||
.. autoclass:: ConversationFeature
|
||||
|
||||
.. autoclass:: InviteMode
|
||||
|
||||
Abstract base classes
|
||||
=====================
|
||||
|
||||
.. module:: aioxmpp.im.conversation
|
||||
|
||||
.. currentmodule:: aioxmpp.im.conversation
|
||||
|
||||
Conversations
|
||||
-------------
|
||||
|
||||
.. autoclass:: AbstractConversation
|
||||
|
||||
.. autoclass:: AbstractConversationMember
|
||||
|
||||
|
||||
Conversation Service
|
||||
--------------------
|
||||
|
||||
.. autoclass:: AbstractConversationService
|
||||
|
||||
"""
|
||||
|
||||
from .conversation import ( # NOQA: F401
|
||||
ConversationState,
|
||||
ConversationFeature,
|
||||
InviteMode,
|
||||
)
|
||||
from .service import ( # NOQA: F401
|
||||
ConversationService,
|
||||
)
|
||||
BIN
Binary file not shown.
Binary file not shown.
BIN
Binary file not shown.
BIN
Binary file not shown.
Binary file not shown.
Binary file not shown.
BIN
Binary file not shown.
@@ -0,0 +1,45 @@
|
||||
########################################################################
|
||||
# File name: body.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 functools
|
||||
|
||||
import aioxmpp.structs
|
||||
|
||||
|
||||
@functools.singledispatch
|
||||
def set_message_body(x, message):
|
||||
raise NotImplementedError(
|
||||
"type {!r} is not supported as message body".format(
|
||||
type(x)
|
||||
)
|
||||
)
|
||||
|
||||
|
||||
@set_message_body.register(str)
|
||||
def set_message_body_str(x, message):
|
||||
message.body.clear()
|
||||
message.body[None] = x
|
||||
|
||||
|
||||
@set_message_body.register(aioxmpp.structs.LanguageMap)
|
||||
def set_message_body_langmap(x, message):
|
||||
message.body.clear()
|
||||
message.body.update(x)
|
||||
@@ -0,0 +1,987 @@
|
||||
########################################################################
|
||||
# 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()
|
||||
@@ -0,0 +1,149 @@
|
||||
########################################################################
|
||||
# File name: dispatcher.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 enum
|
||||
|
||||
import aioxmpp.callbacks
|
||||
import aioxmpp.carbons
|
||||
import aioxmpp.service
|
||||
import aioxmpp.stream
|
||||
|
||||
|
||||
class MessageSource(enum.Enum):
|
||||
STREAM = 0
|
||||
CARBONS = 1
|
||||
|
||||
|
||||
class IMDispatcher(aioxmpp.service.Service):
|
||||
"""
|
||||
Dispatches messages, taking into account carbons.
|
||||
|
||||
.. function:: message_filter(message, peer, sent, source)
|
||||
|
||||
A message was received or sent.
|
||||
|
||||
:param message: Message stanza
|
||||
:type message: :class:`aioxmpp.Message`
|
||||
:param peer: The peer from/to which the stanza was received/sent
|
||||
:type peer: :class:`aioxmpp.JID`
|
||||
:param sent: Whether the mesasge was sent or received.
|
||||
:type sent: :class:`bool`
|
||||
:param source: The source of the message.
|
||||
:type source: :class:`MessageSource`
|
||||
|
||||
`message` is the message stanza which was sent or received.
|
||||
|
||||
`peer` is the JID of the peer involved in the message. If the message
|
||||
was sent, this is the :attr:`~.StanzaBase.to` and otherwise it is the
|
||||
:attr:`~.StanzaBase.from_` attribute of the stanza.
|
||||
|
||||
If `sent` is true, the message was sent from this resource *or* another
|
||||
resource of the same account, if Message Carbons are enabled.
|
||||
|
||||
`source` indicates how the message was sent or received. It may be one
|
||||
of the values of the :class:`MessageSource` enumeration.
|
||||
|
||||
"""
|
||||
|
||||
ORDER_AFTER = [
|
||||
# we want to be loaded after the SimplePresenceDispatcher to ensure
|
||||
# that PresenceClient has updated its data structures before the
|
||||
# dispatch_presence handler runs.
|
||||
# this helps one-to-one conversations a lot, because they can simply
|
||||
# re-use the PresenceClient state
|
||||
aioxmpp.dispatcher.SimplePresenceDispatcher,
|
||||
|
||||
aioxmpp.carbons.CarbonsClient,
|
||||
]
|
||||
|
||||
def __init__(self, client, **kwargs):
|
||||
super().__init__(client, **kwargs)
|
||||
self.message_filter = aioxmpp.callbacks.Filter()
|
||||
self.presence_filter = aioxmpp.callbacks.Filter()
|
||||
|
||||
@aioxmpp.service.depsignal(
|
||||
aioxmpp.node.Client,
|
||||
"before_stream_established")
|
||||
async def enable_carbons(self, *args):
|
||||
carbons = self.dependencies[aioxmpp.carbons.CarbonsClient]
|
||||
try:
|
||||
await carbons.enable()
|
||||
except (RuntimeError, aioxmpp.errors.XMPPError):
|
||||
self.logger.info(
|
||||
"remote server does not support message carbons"
|
||||
)
|
||||
else:
|
||||
self.logger.info(
|
||||
"message carbons enabled successfully"
|
||||
)
|
||||
return True
|
||||
|
||||
@aioxmpp.service.depsignal(
|
||||
aioxmpp.stream.StanzaStream,
|
||||
"on_message_received")
|
||||
def dispatch_message(self, message, *,
|
||||
sent=False,
|
||||
source=MessageSource.STREAM):
|
||||
if message.xep0280_received is not None:
|
||||
if (message.from_ is not None and
|
||||
message.from_ != self.client.local_jid.bare()):
|
||||
return
|
||||
message = message.xep0280_received.stanza
|
||||
source = MessageSource.CARBONS
|
||||
elif message.xep0280_sent is not None:
|
||||
if (message.from_ is not None and
|
||||
message.from_ != self.client.local_jid.bare()):
|
||||
return
|
||||
message = message.xep0280_sent.stanza
|
||||
sent = True
|
||||
source = MessageSource.CARBONS
|
||||
|
||||
peer = message.to if sent else message.from_
|
||||
|
||||
filtered = self.message_filter.filter(
|
||||
message,
|
||||
peer,
|
||||
sent,
|
||||
source,
|
||||
)
|
||||
|
||||
if filtered is not None:
|
||||
self.logger.debug(
|
||||
"message was not processed by any IM handler: %s",
|
||||
filtered,
|
||||
)
|
||||
|
||||
@aioxmpp.service.depsignal(
|
||||
aioxmpp.stream.StanzaStream,
|
||||
"on_presence_received")
|
||||
def dispatch_presence(self, presence, *, sent=False):
|
||||
filtered = self.presence_filter.filter(
|
||||
presence,
|
||||
presence.from_,
|
||||
sent,
|
||||
)
|
||||
|
||||
if filtered is not None:
|
||||
self.logger.debug(
|
||||
"presence was not processed by any IM handler: %s",
|
||||
filtered,
|
||||
)
|
||||
@@ -0,0 +1,26 @@
|
||||
########################################################################
|
||||
# File name: muc.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 aioxmpp.service
|
||||
|
||||
|
||||
class MUCIMService(aioxmpp.service.Service):
|
||||
pass
|
||||
@@ -0,0 +1,229 @@
|
||||
########################################################################
|
||||
# File name: p2p.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 aioxmpp.service
|
||||
|
||||
from .conversation import (
|
||||
AbstractConversationMember,
|
||||
AbstractConversation,
|
||||
AbstractConversationService,
|
||||
ConversationFeature,
|
||||
)
|
||||
|
||||
from .dispatcher import IMDispatcher, MessageSource
|
||||
|
||||
from .service import ConversationService
|
||||
|
||||
|
||||
class Member(AbstractConversationMember):
|
||||
"""
|
||||
Member of a one-on-one conversation.
|
||||
|
||||
.. autoattribute:: direct_jid
|
||||
|
||||
"""
|
||||
|
||||
def __init__(self, peer_jid, is_self):
|
||||
super().__init__(peer_jid, is_self)
|
||||
|
||||
@property
|
||||
def direct_jid(self):
|
||||
"""
|
||||
The JID of the peer.
|
||||
"""
|
||||
|
||||
return self._conversation_jid
|
||||
|
||||
@property
|
||||
def uid(self) -> bytes:
|
||||
return b"xmpp:" + str(self._conversation_jid.bare()).encode("utf-8")
|
||||
|
||||
|
||||
class Conversation(AbstractConversation):
|
||||
"""
|
||||
Implementation of :class:`~.im.conversation.AbstractConversation` for
|
||||
one-on-one conversations.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:class:`.im.conversation.AbstractConversation`
|
||||
for documentation on the interface implemented by this class.
|
||||
"""
|
||||
|
||||
def __init__(self, service, peer_jid, parent=None):
|
||||
super().__init__(service, parent=parent)
|
||||
self.__peer_jid = peer_jid
|
||||
self.__members = (
|
||||
Member(self._client.local_jid, True),
|
||||
Member(peer_jid, False),
|
||||
)
|
||||
|
||||
@property
|
||||
def features(self):
|
||||
return (
|
||||
frozenset([ConversationFeature.SEND_MESSAGE,
|
||||
ConversationFeature.LEAVE]) |
|
||||
super().features
|
||||
)
|
||||
|
||||
def _handle_message(self, msg, peer, sent, source):
|
||||
if sent:
|
||||
member = self.__members[0]
|
||||
else:
|
||||
member = self.__members[1]
|
||||
|
||||
self._service.logger.debug("emitting on_message for %s",
|
||||
self.__peer_jid)
|
||||
self.on_message(msg, member, source)
|
||||
|
||||
@property
|
||||
def jid(self):
|
||||
return self.__peer_jid
|
||||
|
||||
@property
|
||||
def members(self):
|
||||
return self.__members
|
||||
|
||||
@property
|
||||
def me(self):
|
||||
return self.__members[0]
|
||||
|
||||
def send_message(self, msg):
|
||||
msg.autoset_id()
|
||||
msg.to = self.__peer_jid
|
||||
self.on_message(msg, self.me, MessageSource.STREAM)
|
||||
return self._client.enqueue(msg)
|
||||
|
||||
async def send_message_tracked(self, msg):
|
||||
raise self._not_implemented_error("message tracking")
|
||||
|
||||
async def leave(self):
|
||||
self._service._conversation_left(self)
|
||||
|
||||
|
||||
class Service(AbstractConversationService, aioxmpp.service.Service):
|
||||
"""
|
||||
Manage one-to-one conversations.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:class:`~.AbstractConversationService`
|
||||
for useful common signals
|
||||
|
||||
This service manages one-to-one conversations, including private
|
||||
conversations running in the framework of a multi-user chat. In those
|
||||
cases, the respective multi-user chat conversation service requests a
|
||||
conversation from this service to use.
|
||||
|
||||
For each bare JID, there can either be a single conversation for the bare
|
||||
JID or zero or more conversations for full JIDs. Mixing conversations to
|
||||
bare and full JIDs of the same bare JID is not allowed, because it is
|
||||
ambiguous.
|
||||
|
||||
This service creates conversations if it detects them as one-on-one
|
||||
conversations. Subscribe to
|
||||
:meth:`aioxmpp.im.ConversationService.on_conversation_added` to be notified
|
||||
about new conversations being auto-created.
|
||||
|
||||
.. automethod:: get_conversation
|
||||
"""
|
||||
|
||||
ORDER_AFTER = [
|
||||
ConversationService,
|
||||
IMDispatcher,
|
||||
]
|
||||
|
||||
def __init__(self, client, **kwargs):
|
||||
super().__init__(client, **kwargs)
|
||||
self._conversationmap = {}
|
||||
self.on_conversation_new.connect(
|
||||
self.dependencies[ConversationService]._add_conversation
|
||||
)
|
||||
|
||||
def _make_conversation(self, peer_jid, spontaneous):
|
||||
self.logger.debug("creating new conversation for %s (spontaneous=%s)",
|
||||
peer_jid, spontaneous)
|
||||
result = Conversation(self, peer_jid, parent=None)
|
||||
self._conversationmap[peer_jid] = result
|
||||
if spontaneous:
|
||||
self.on_spontaneous_conversation(result)
|
||||
self.on_conversation_new(result)
|
||||
result.on_enter()
|
||||
self.logger.debug("new conversation for %s set up and events emitted",
|
||||
peer_jid)
|
||||
return result
|
||||
|
||||
@aioxmpp.service.depfilter(IMDispatcher, "message_filter")
|
||||
def _filter_message(self, msg, peer, sent, source):
|
||||
try:
|
||||
existing = self._conversationmap[peer]
|
||||
except KeyError:
|
||||
try:
|
||||
existing = self._conversationmap[peer.bare()]
|
||||
except KeyError:
|
||||
existing = None
|
||||
|
||||
if (existing is None and
|
||||
(msg.type_ == aioxmpp.MessageType.CHAT or
|
||||
msg.type_ == aioxmpp.MessageType.NORMAL) and
|
||||
msg.body):
|
||||
conversation_jid = peer.bare()
|
||||
if msg.xep0045_muc_user is not None:
|
||||
conversation_jid = peer
|
||||
existing = self._make_conversation(conversation_jid, True)
|
||||
|
||||
if existing is not None:
|
||||
existing._handle_message(msg, peer, sent, source)
|
||||
return None
|
||||
|
||||
return msg
|
||||
|
||||
def get_conversation(self, peer_jid, *, current_jid=None):
|
||||
"""
|
||||
Get or create a new one-to-one conversation with a peer.
|
||||
|
||||
:param peer_jid: The JID of the peer to converse with.
|
||||
:type peer_jid: :class:`aioxmpp.JID`
|
||||
:param current_jid: The current JID to lock the conversation to (see
|
||||
:rfc:`6121`).
|
||||
:type current_jid: :class:`aioxmpp.JID`
|
||||
:rtype: :class:`Conversation`
|
||||
:return: The new or existing conversation with the peer.
|
||||
|
||||
`peer_jid` must be a full or bare JID. See the :class:`Service`
|
||||
documentation for details.
|
||||
|
||||
.. versionchanged:: 0.10
|
||||
|
||||
In 0.9, this was a coroutine. Sorry.
|
||||
"""
|
||||
|
||||
try:
|
||||
return self._conversationmap[peer_jid]
|
||||
except KeyError:
|
||||
pass
|
||||
return self._make_conversation(peer_jid, False)
|
||||
|
||||
def _conversation_left(self, conv):
|
||||
del self._conversationmap[conv.jid]
|
||||
@@ -0,0 +1,143 @@
|
||||
########################################################################
|
||||
# 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 functools
|
||||
|
||||
import aioxmpp.callbacks
|
||||
import aioxmpp.service
|
||||
|
||||
|
||||
class ConversationService(aioxmpp.service.Service):
|
||||
"""
|
||||
Central place where all :class:`.im.conversation.AbstractConversation`
|
||||
subclass instances are collected.
|
||||
|
||||
It provides discoverability of all existing conversations (in no particular
|
||||
order) and signals on addition and removal of active conversations. This is
|
||||
useful for front ends to track conversations globally without needing to
|
||||
know about the specific conversation providers.
|
||||
|
||||
.. signal:: on_conversation_added(conversation)
|
||||
|
||||
A new conversation has been added.
|
||||
|
||||
:param conversation: The conversation which was added.
|
||||
:type conversation: :class:`~.im.conversation.AbstractConversation`
|
||||
|
||||
This signal is fired when a new conversation is added by a
|
||||
:term:`Conversation Implementation`.
|
||||
|
||||
.. note::
|
||||
|
||||
If you are looking for a "on_conversation_removed" event or similar,
|
||||
there is none. You should use the
|
||||
:meth:`.AbstractConversation.on_exit` event of the `conversation`.
|
||||
|
||||
.. signal:: on_message(conversation,
|
||||
*args, **kwargs)
|
||||
|
||||
Emits whenever any active conversation emits its
|
||||
:meth:`~.im.Conversation.on_message` event. The arguments are forwarded
|
||||
1:1, with the :class:`~.im.AbstractConversation` instance pre-pended to
|
||||
the argument list.
|
||||
|
||||
.. autoattribute:: conversations
|
||||
|
||||
.. automethod:: get_conversation
|
||||
|
||||
For :term:`Conversation Implementations <Conversation Implementation>`, the
|
||||
following methods are intended; they should not be used by applications.
|
||||
|
||||
.. automethod:: _add_conversation
|
||||
|
||||
"""
|
||||
|
||||
on_conversation_added = aioxmpp.callbacks.Signal()
|
||||
on_message = aioxmpp.callbacks.Signal()
|
||||
|
||||
def __init__(self, client, **kwargs):
|
||||
super().__init__(client, **kwargs)
|
||||
self._conversation_meta = {}
|
||||
self._conversation_map = {}
|
||||
|
||||
@property
|
||||
def conversations(self):
|
||||
"""
|
||||
Return an iterable of conversations in which the local client is
|
||||
participating.
|
||||
"""
|
||||
return self._conversation_meta.keys()
|
||||
|
||||
def _remove_conversation(self, conv):
|
||||
del self._conversation_map[conv.jid]
|
||||
tokens, = self._conversation_meta.pop(conv)
|
||||
for signal, token in tokens:
|
||||
signal.disconnect(token)
|
||||
|
||||
def _handle_conversation_exit(self, conv, *args, **kwargs):
|
||||
self._remove_conversation(conv)
|
||||
return False
|
||||
|
||||
def _add_conversation(self, conversation):
|
||||
"""
|
||||
Add the conversation and fire the :meth:`on_conversation_added` event.
|
||||
|
||||
:param conversation: The conversation object to add.
|
||||
:type conversation: :class:`~.AbstractConversation`
|
||||
|
||||
The conversation is added to the internal list of conversations which
|
||||
can be queried at :attr:`conversations`. The
|
||||
:meth:`on_conversation_added` event is fired.
|
||||
|
||||
In addition, the :class:`ConversationService` subscribes to the
|
||||
:meth:`~.AbstractConversation.on_exit` event to remove the conversation
|
||||
from the list automatically. There is no need to remove a conversation
|
||||
from the list explicitly.
|
||||
"""
|
||||
handler = functools.partial(
|
||||
self._handle_conversation_exit,
|
||||
conversation
|
||||
)
|
||||
tokens = []
|
||||
|
||||
def linked_token(signal, handler):
|
||||
return signal, signal.connect(handler)
|
||||
|
||||
tokens.append(linked_token(conversation.on_exit, handler))
|
||||
tokens.append(linked_token(conversation.on_failure, handler))
|
||||
tokens.append(linked_token(conversation.on_message, functools.partial(
|
||||
self.on_message,
|
||||
conversation,
|
||||
)))
|
||||
|
||||
self._conversation_meta[conversation] = (
|
||||
tokens,
|
||||
)
|
||||
self._conversation_map[conversation.jid] = conversation
|
||||
self.on_conversation_added(conversation)
|
||||
|
||||
def get_conversation(self, conversation_address):
|
||||
"""
|
||||
Return the :class:`.im.AbstractConversation` for a given JID.
|
||||
|
||||
:raises KeyError: if there is currently no matching conversation
|
||||
"""
|
||||
return self._conversation_map[conversation_address]
|
||||
Reference in New Issue
Block a user