This module contains functions to connect to an XMPP server, as well as maintaining the stream. In addition, a client class which completely manages a stream based on a presence setting is provided.
The AbstractClient is a base class for implementing XMPP client classes. These classes deal with managing the StanzaStream and the underlying XMLStream instances. The abstract client provides functionality for connecting the xmlstream as well as signals which indicate changes in the stream state.
The jid must be a JID for which to connect. The security_layer is best created using the security_layer() function and must provide authentication for the given jid.
The negotiation_timeout argument controls the negotiation_timeout attribute.
If loop is given, it must be a asyncio.BaseEventLoop instance. If it is not given, the current event loop is used.
As a glue between the stanza stream and the XML stream, it also knows about stream management and performs stream management negotiation. It is specialized on client operations, which implies that it will try to keep the stream alive as long as wished by the client.
In general, there are no fatal errors (aside from stream negotiation problems) which stop a AbstractClient from working. It makes use of stream management as far as possible and abstracts away the gritty low level details. In general, it is sufficient to observe the on_stream_established and on_stream_destroyed events, which notify a user about when a stream becomes available and when it becomes unavailable.
If authentication fails (or another stream negotiation error occurs), the client fails and on_failure is fired. running becomes false and the client needs to be re-started manually by calling start().
Changed in version 0.4: Since 0.4, support for legacy XMPP sessions has been implemented. Mainly for compatiblity with ejabberd.
Controlling the client:
Start the client. If it is already running, RuntimeError is raised.
While the client is running, it will try to keep an XMPP connection open to the server associated with local_jid.
Stop the client. This sends a signal to the clients main task which makes it terminate.
It may take some cycles through the event loop to stop the client task. To check whether the task has actually stopped, query running.
The timeout applied to the connection process and the individual steps of negotiating the stream. See the negotiation_timeout argument to connect_secured_xmlstream().
Connection information:
true if the stream is currently established (as defined in on_stream_established) and false otherwise.
The JID the client currently has. While the client is disconnected, only the bare JID part is authentic, as the resource is ultimately determined by the server.
Writing this attribute is not allowed, as changing the JID introduces a lot of issues with respect to reusability of the stream. Instanciate a new AbstractClient if you need to change the bare part of the JID.
Note
Changing the resource between reconnects may be allowed later.
The StanzaStream instance used by the node.
An instance of StreamFeatures. This is the most-recently received stream features information (the one received right before resource binding).
While no stream has been established yet, this is None. During transparent re-negotiation, that information may be obsolete. However, when before_stream_established fires, the information is up-to-date.
Exponential backoff on interruptions:
When an underlying XML stream fails due to connectivity issues (generic OSError raised), exponential backoff takes place before attempting to reconnect.
The initial time to wait before reconnecting is described by backoff_start.
Each subsequent time a connection fails, the previous backoff time is multiplied with backoff_factor.
The backoff time is capped to backoff_cap, to avoid having unrealistically high values.
Signals:
This signal is fired when the client fails and stops.
This coroutine signal is executed right before on_stream_established() fires.
Fires when the client stops gracefully. This is the counterpart to on_failure().
When the stream is established and resource binding took place, this event is fired. It means that the stream can now be used for XMPP interactions.
This is called whenever a stream is destroyed. The conditions for this are the same as for StanzaStream.on_stream_destroyed.
This event can be used to know when to discard all state about the XMPP connection, such as roster information.
Services:
Summon a Service for the client.
If the class_ has already been summoned for the client, it’s instance is returned.
Otherwise, all requirements for the class are first summoned (if they are not there already). Afterwards, the class itself is summoned and the instance is returned.
A presence managed XMPP client. The arguments are passed to the AbstractClient constructor.
While the start/stop interfaces of AbstractClient are still available, it is recommended to control the presence managed client solely using the presence property.
The initial presence is set to unavailable, thus, the client will not connect immediately.
Control or query the current presence state (see PresenceState) of the client. Note that when reading, the property only returns the “set” value, not the actual value known to the server (and others). This may differ if the connection is still being established.
See also
Setting the presence state using presence clears the status of the presence. To set the status and state at once, use set_presence().
Upon setting this attribute, the PresenceManagedClient will do whatever neccessary to achieve the given presence. If the presence is an available presence, the client will attempt to connect to the server. If the presence is unavailable and the client is currently connected, it will disconnect.
Instead of setting the presence to unavailable, stop() can also be called. The presence attribute is not affected by calls to start() or stop().
Set the presence state and status on the client. This has the same effects as writing state to presence, but the status of the presence is also set at the same time.
status must be either a string or an iterable containing stanza.Status objects. The stanza.Status instances are saved and added to the presence stanza when it is time to send it.
The status is the text shown alongside the state (indicating availability such as away, do not disturb and free to chat).
Signals:
The event is fired after on_stream_established and after the current presence has been sent to the server as initial presence.
Connect to an XMPP server which serves the domain of the given jid and apply the given security_layer (see security_layer()).
loop must be either a valid asyncio.BaseEventLoop or None, in which case the current event loop is used.
The negotiation_timeout is passed to the security layer and used for connect timeouts.
override_peer is passed to connect_to_xmpp_server().
Return a triple consisting of the transport, the XMLStream and the current StreamFeatures node. The transport returned in the triple is the one returned by the security layer and is None if no starttls has been negotiated. To gain access to the transport used if the transport returned is None, use the transport of the XML stream.
If the connection fails OSError is raised. That OSError may in fact be a MultiOSError, which gives more information on the different errors which occured.
If the domain does not support XMPP at all (by indicating that fact in the SRV records), ValueError is raised.
If SASL or TLS negotiation fails, the corresponding exception type from aioxmpp.errors is raised. Most notably, authentication failures caused by invalid credentials or a user abort are raised as AuthenticationFailure.
Connect to an XMPP server which serves the domain of the given jid.
override_peer may be a tuple of host name (or IP address) and port. If given, this will be the first peer the stream tries to connect to. Only if that connection fails the usual XMPP server lookup routine takes place.
loop must be either a valid asyncio.BaseEventLoop or None, in which case the current event loop is used.
Return a triple consisting of the transport, the XMLStream instance and a asyncio.Future on the first StreamFeatures node.
If the connection fails OSError is raised. That OSError may in fact be a MultiOSError, which gives more information on the different errors which occured.
If the domain does not support XMPP at all (by indicating that fact in the SRV records), ValueError is raised.