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
aioxmpp.im
is highly experimental, even more than 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.
- Conversation
Communication context for two or more parties.
- Conversation Member
An entity taking part in a Conversation.
- Conversation Implementation
A Service which provides means to create and manage specific
AbstractConversation
subclasses.- Service Member
A Conversation Member which represents the service over which the conversation is run inside the conversation.
im.p2p
— One-on-one conversations¶
-
class
aioxmpp.im.p2p.
Service
(client, **kwargs)[source]¶ Manage one-to-one conversations.
See also
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
aioxmpp.im.ConversationService.on_conversation_added()
to be notified about new conversations being auto-created.-
get_conversation
(peer_jid, *, current_jid=None)[source]¶ Get or create a new one-to-one conversation with a peer.
- Parameters
peer_jid (
aioxmpp.JID
) – The JID of the peer to converse with.current_jid (
aioxmpp.JID
) – The current JID to lock the conversation to (see RFC 6121).
- Return type
- Returns
The new or existing conversation with the peer.
peer_jid must be a full or bare JID. See the
Service
documentation for details.Changed in version 0.10: In 0.9, this was a coroutine. Sorry.
-
class
aioxmpp.im.p2p.
Conversation
(service, peer_jid, parent=None)[source]¶ Implementation of
AbstractConversation
for one-on-one conversations.See also
im.conversation.AbstractConversation
for documentation on the interface implemented by this class.
aioxmpp.muc
— Multi-User-Chats (XEP-0045)¶
See also
aioxmpp.muc
has a Conversation Implementation for MUCs.
Core Services¶
-
class
aioxmpp.im.
ConversationService
(client, **kwargs)[source]¶ Central place where all
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.
- Parameters
conversation (
AbstractConversation
) – The conversation which was added.
This signal is fired when a new conversation is added by a Conversation Implementation.
Note
If you are looking for a “on_conversation_removed” event or similar, there is none. You should use the
AbstractConversation.on_exit()
event of the conversation.
-
on_message(conversation,
-
*args, **kwargs)
Emits whenever any active conversation emits its
on_message()
event. The arguments are forwarded 1:1, with theAbstractConversation
instance pre-pended to the argument list.
-
conversations
¶ Return an iterable of conversations in which the local client is participating.
-
get_conversation
(conversation_address)[source]¶ Return the
im.AbstractConversation
for a given JID.- Raises
KeyError – if there is currently no matching conversation
For Conversation Implementations, the following methods are intended; they should not be used by applications.
-
_add_conversation
(conversation)[source]¶ Add the conversation and fire the
on_conversation_added()
event.- Parameters
conversation (
AbstractConversation
) – The conversation object to add.
The conversation is added to the internal list of conversations which can be queried at
conversations
. Theon_conversation_added()
event is fired.In addition, the
ConversationService
subscribes to theon_exit()
event to remove the conversation from the list automatically. There is no need to remove a conversation from the list explicitly.
-
signal
Enumerations¶
-
class
aioxmpp.im.
ConversationState
(value)[source]¶ State of a conversation.
Note
The members of this enumeration closely mirror the states of XEP-0085, with the addition of the internal
PENDING
state. The reason is that XEP-0085 is a Final Standard and is state-of-the-art for conversation states in XMPP.-
PENDING
¶ The conversation has been created, possibly automatically, and the application has not yet set the conversation state.
-
ACTIVE
¶ 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-0085
-
INACTIVE
¶ User has not interacted with the chat session interface for an intermediate period of time (e.g., 2 minutes).
—from XEP-0085
-
GONE
¶ 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-0085
-
COMPOSING
¶ 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-0085
-
PAUSED
¶ User was composing but has not interacted with the message input interface for a short period of time (e.g., 30 seconds).
—from XEP-0085
When any of the above states is entered, a notification is sent out to the participants of the conversation.
-
-
class
aioxmpp.im.
ConversationFeature
(value)[source]¶ Represent individual features of a Conversation of a Conversation Implementation.
See also
The
AbstractConversation.features
provides a set of features offered by a specific Conversation.-
INVITE_DIRECT_CONFIGURE
¶ Explicit support for configuring the conversation to allow the invitee to join when using
DIRECT
withinvite()
.
-
SEND_MESSAGE
¶ Allows use of
send_message()
.
-
SEND_MESSAGE_TRACKED
¶ Allows use of
send_message_tracked()
.
-
SET_NICK
¶ Allows use of
set_nick()
.
-
SET_NICK_OF_OTHERS
¶ Explicit support for changing the nickname of other members when calling
set_nick()
.
-
SET_TOPIC
¶ Allows use of
set_topic()
.
-
-
class
aioxmpp.im.
InviteMode
(value)[source]¶ Represent different possible modes for sending an invitation.
-
DIRECT
¶ The invitation is sent directly to the invitee, without going through a service specific to the conversation.
-
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).
-
Abstract base classes¶
Conversations¶
-
class
aioxmpp.im.conversation.
AbstractConversation
(service, parent=None, **kwargs)[source]¶ 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
None
and always an instance of a subclass ofAbstractConversationMember
. However, the member may not be part of themembers
of the conversation. For example, it may be theservice_member
object which is never part ofmembers
. 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.
- Parameters
msg (
aioxmpp.Message
) – Message which was received.member (
AbstractConversationMember
) – The member object of the sender.source (
MessageSource
) – How the message was acquiredtracker (
aioxmpp.tracking.MessageTracker
) – A message tracker which tracks an outbound message.
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
STREAM
and member is theAbstractConversationMember
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
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
CARBONS
and member is theAbstractConversationMember
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
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
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
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.
- Parameters
member (
AbstractConversationMember
) – The member object of the member whose state changed.new_state (
ConversationState
) – The new conversation state of the member.msg (
aioxmpp.Message
) – The stanza which conveyed the state change.
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.
- Parameters
member (
AbstractConversationMember
) – The member object of the affected member.resource (
str
orNone
) – The resource of the member which changed presence.presence (
aioxmpp.Presence
) – The presence stanza
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
None
; the affected resource can be extracted from thefrom_
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 notNone
), 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
on_leave()
is emitted instead.
-
signal
on_nick_changed
(member, old_nick, new_nick, **kwargs)¶ The nickname of a member has changed
- Parameters
member (
AbstractConversationMember
) – The member object of the member whose nick has changed.new_nick (
str
) – The new nickname of the member.
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
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.
- Parameters
member (
AbstractConversationMember
) – The member object who changed the topic.new_topic (
LanguageMap
) – The new topic of the conversation.
-
signal
on_uid_changed
(member, old_uid, **kwargs)¶ This rare signal notifies that the
uid
of a member has changed.- Parameters
member (
AbstractConversationMember
) – The member object for which the UID has changed.old_uid (
bytes
) – The old UID of the member.
The new uid is already available at the members
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
AbstractConversation
.One of
on_enter()
andon_failure()
is emitted exactly once for eachAbstractConversation
instance.See also
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
on_failure()
are the only signals which must not receive keyword arguments, so that they continue to work withAdHocSignal.AUTO_FUTURE
andfirst_signal()
.New in version 0.10.
-
signal
on_failure
(exc)¶ The conversation could not be entered.
- Parameters
exc (
Exception
) – The exception which caused the operation to fail.
Often, exc will be a
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
on_enter()
and not after the room has been entered. If the conversation is terminated due to a remote cause at a later point,on_exit()
is used.One of
on_enter()
andon_failure()
is emitted exactly once for eachAbstractConversation
instance.Note
This and
on_failure()
are the only signals which must not receive keyword arguments, so that they continue to work withAdHocSignal.AUTO_FUTURE
andfirst_signal()
.New in version 0.10.
-
signal
on_join
(member, **kwargs)¶ A new member has joined the conversation.
- Parameters
member (
AbstractConversationMember
) – The member object of the new member.
When this signal is called, the member is already included in the
members
.
-
signal
on_leave
(member, **kwargs)¶ A member has left the conversation.
- Parameters
member (
AbstractConversationMember
) – The member object of the previous member.
When this signal is called, the member has already been removed from the
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:
-
features
¶ A set of features supported by this Conversation.
The members of the set are usually drawn from the
ConversationFeature
enumeration
; Conversation Implementations are free to add custom elements from other enumerations to this set.Unless stated otherwise, the methods of
AbstractConversation
and its subclasses always may throw one of the following exceptions, unless support for those methods is explicitly stated with an appropriateConversationFeature
member in thefeatures
.NotImplementedError
if the Conversation Implementation does not support the method at all.RuntimeError
if the server does not support the method.aioxmpp.XMPPCancelError
withfeature-not-implemented
condition.
If support for the method is claimed in
features
, these exceptions must not be raised (for the given reason; of course, a method may still raise anaioxmpp.XMPPCancelError
due for other conditions such asitem-not-found
).
-
jid
¶ The address of the conversation.
-
members
¶ An iterable of members of this conversation.
-
me
¶ The member representing the local member.
-
service_member
¶ The member representing the service on which the conversation is hosted, if available.
This is never included in
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
None
.New in version 0.10.
Methods:
Note
See
features
for discovery of support for individual methods at a given conversation instance.-
async
ban
(member, reason=None, *, request_kick=True)[source]¶ Ban a member from re-joining the conversation.
- Parameters
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:
BAN_WITH_KICK
If request_kick is true, the member is kicked from the conversation.
See also
The corresponding feature for this method is
ConversationFeature.BAN
. Seefeatures
for details on the semantics of features.
-
async
invite
(address, text=None, *, mode=<InviteMode.DIRECT: 0>, allow_upgrade=False)[source]¶ Invite another entity to the conversation.
- Parameters
address (
aioxmpp.JID
) – The address of the entity to invite.text – A reason/accompanying text for the invitation.
mode (
InviteMode
) – The invitation mode to use.allow_upgrade (
bool
) – Whether to allow creating a new conversation to satisfy the invitation.
- Raises
NotImplementedError – if the requested mode is not supported
ValueError – if allow_upgrade is false, but a new conversation is required.
- Returns
The stanza token for the invitation and the possibly new conversation object
- Return type
tuple of
StanzaToken
andAbstractConversation
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,
ValueError
is raised.Additional features:
INVITE_DIRECT
Support for
DIRECT
mode.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
aioxmpp.errors.XMPPError
, in which case the error is re-raised and the invitation not sent.INVITE_MEDIATED
Support for
MEDIATED
mode.INVITE_UPGRADE
If allow_upgrade is
True
, an upgrade will be performed and a new conversation is returned. If allow_upgrade isFalse
, the invite will fail.
See also
The corresponding feature for this method is
ConversationFeature.INVITE
. Seefeatures
for details on the semantics of features.
-
async
kick
(member, reason=None)[source]¶ Kick a member from the conversation.
- Parameters
member – The member to kick.
reason (
str
) – A reason to show to the members of the conversation including the kicked member.
- Raises
aioxmpp.errors.XMPPError – if the server returned an error for the kick command.
See also
The corresponding feature is
ConversationFeature.KICK
. Seefeatures
for details.
-
async
leave
()[source]¶ Leave the conversation.
See also
The corresponding feature is
ConversationFeature.LEAVE
. Seefeatures
for details.
-
send_message
(body)[source]¶ Send a message to the conversation.
- Parameters
msg (
aioxmpp.Message
) – The message to send.- Returns
The stanza token obtained from sending.
- Return type
The default implementation simply calls
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
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.
See also
The corresponding feature is
ConversationFeature.SEND_MESSAGE
. Seefeatures
for details.
-
abstract
send_message_tracked
(msg, *, timeout=None)[source]¶ Send a message to the conversation with tracking.
- Parameters
msg (
aioxmpp.Message
) – The message to send.timeout (
numbers.RealNumber
,datetime.timedelta
orNone
) – Timeout for the tracking.
- Raises
NotImplementedError – if tracking is not implemented
- Returns
The stanza token obtained from sending and the
aioxmpp.tracking.MessageTracker
tracking the delivery.- Return type
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
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
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 toNone
, the tracking never expires.Warning
See also
The corresponding feature is
ConversationFeature.SEND_MESSAGE_TRACKED
. Seefeatures
for details.
-
async
set_nick
(new_nickname)[source]¶ Change our nickname.
- Parameters
new_nickname (
str
) – The new nickname for the member.- 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
on_nick_changed()
event.Implementations may provide a different method which provides more feedback.
See also
The corresponding feature for this method is
ConversationFeature.SET_NICK
. Seefeatures
for details on the semantics of features.
-
async
set_topic
(new_topic)[source]¶ Change the (possibly publicly) visible topic of the conversation.
- Parameters
new_topic (
str
) – The new topic for the conversation.
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
on_topic_chagned()
event.Implementations may provide a different method which provides more feedback.
See also
The corresponding feature for this method is
ConversationFeature.SET_TOPIC
. Seefeatures
for details on the semantics of features.
Interface solely for subclasses:
-
_client
¶ The client as passed to the constructor.
-
signal
-
class
aioxmpp.im.conversation.
AbstractConversationMember
(conversation_jid, is_self)[source]¶ Represent a member in a
AbstractConversation
.While all implementations will have their own additional attributes, the following attributes must exist on all subclasses:
-
direct_jid
¶ If available, this is the
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
None
.
-
is_self
¶ True if the member refers to ourselves in the conversation, false otherwise.
-
uid
¶ 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
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.
-
Conversation Service¶
-
class
aioxmpp.im.conversation.
AbstractConversationService
[source]¶ Abstract base class for Conversation Services.
Useful implementations:
aioxmpp.im.p2p.Service
(client, **kwargs)Manage one-to-one conversations.
aioxmpp.muc.MUCClient
(client, **kwargs)Conversation Implementation for Multi-User Chats (XEP-0045).
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
AbstractConversation
object immediately and start possibly needed background tasks to actually initiate the conversation. The caller should use theon_enter()
andon_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.
- Parameters
conversation (
AbstractConversation
) – The new conversation.
See also
ConversationService.on_conversation_added()
is a signal shared among all Conversation Implementations 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
on_conversation_new()
, but is only emitted for conversations which are created without local interaction.- Parameters
conversation (
AbstractConversation
) – The new conversation.
New in version 0.10.
-
signal