Package pyxmpp2
[hide private]

Package pyxmpp2

Project Information

PyXMPP2 is a Python implementation of the XMPP protocol (RFC 6120, RFC 6121) and some of XMPP Extensions

PyXMPP was first implemented by Jacek Konieczny in year 2003, using libxml2 as the XML framework, then it slowly evolved over years becoming kind of monster full of 'smart' and legacy code. Also libxml2 proved to be inadequate base for a Python library.

PyXMPP2 is a rewrite of the original PyXMPP aimed to replace libxml2 with the more standard ElementTree API and to clean up the API. In fact the API has completely changed, hopefully for better.

The PyXMPP2 project is hosted at GitHub:

The API documentation is available at:

The simple API

If you don't care about all the PyXMPP flexibility and features and just want to send a Jabber message, please look at the 'Simple API': pyxmpp2.simple

Basic components


The basic functionality of the XMPP protocol is to send XML data between entities using XML container elements called 'stanzas'. There are three types of stanzas:

They are represented by the following PyXMPP2 classes: message.Message, iq.Iq and presence.Presence.

The stanzas may carry arbitrary XML payload. It is bound to the stanzas using the stanzapayload.StanzaPayload interface. It can be a generic stanzapayload.XMLPayload implementation or any specialized interfaces.StanzaPayload subclass decoding the XML element as required.

XMPP Streams

The stanzas are sent over XML streams. In PyXMPP the stream functionality is implemented by the streambase.StreamBase class. The class does not implement actual I/O (see the next secition) or SASL/TLS (these are handled by streamsasl.StreamSASLHandler and streamtls.StreamTLSHandler), but provides the basic logic to handle stanzas and stream negotiation.


The actual I/O (sending XML data over socket) has been separated from the streambase.StreamBase for cleaner code and to allow alternate transport implementations (like BOSH). The interface is defined by the interfaces.XMPPTransport abstract class and the standard TCP transport (RFC 6120) is implemented via transport.TCPTransport.

Main event loop

The transport objects react on I/O events (like data received from a socket) and an XMPP application usually wants to react on various XMPP events, so a mechanism to dispatch these events is required. In PyXMPP2 the mainloop.interfaces.MainLoop interface is defined to dispatch the events to various components. There are also a few implementation of the interface provided:

The default implementation is available as mainloop.main_loop_factory.

Chains of responsibility

Both streambase.StreamBase and main loop implementations constructors expect a 'handlers' argument with a list of object to handle various events or elements. Main loop handlers should implement one or more of these interfaces:

Stream handlers should implement one or more of:

Component configuration

As many parameters may define an XMPP implementation behaviour, class constructors or other methods would require lots of arguments to handle them all. Instead, a special settings.XMPPSettings object is often used, which can hold any parameter useful by any part of the PyXMPP2. It is also used as a simple form of dependency injection.

The Client class

The pyxmpp2.client.Client joins a main loop, a client stream and some basic handlers (for stream encryption, authentication, resource binding and roster handling) together, so a client application has only to add its handlers to make it work.

See the pyxmpp2.client module for details. This should be the start point for most XMPP client applications.


PyXMPP2 does all it logging via the standard logging module. Most of the PyXMPP2 modules log via 'pyxmpp2.module-name' loggers. There are some special cases though:

Those two can be used to intercept the data for application-specific monitoring (e.g. an 'XML console' in a client GUI).

Most of the log messages generated by PyXMPP have level 'DEBUG', no higher level messages should appear during normal operation. Some 'WARNING' messages may be emitted when a remote party misbehaves and 'ERROR' messages in case of programming errors.

Module hierarchy

Base XMPP features (RFC 6120 and RFC 6121) and core PyXMPP2 framework features are implemented in direct submodules of pyxmpp2 package.

pyxmpp2.sasl package provides the SASL protocol and mechanisms implementation.

pyxmpp2.mainloop contains the main event loop and I/O framework.

pyxmpp2.ext contains XMPP Extensions implementations.

Submodules [hide private]