Welcome to aioxmpp’s documentation!

Welcome to the documentation of aioxmpp! In case you do not know, aioxmpp is a pure-python XMPP library written for use with asyncio.

If you are new to aioxmpp, you should check out the Quick start, or read on below for an overview of the Feature overview of aioxmpp. If you want to check the API reference to look something up, you should head to The aioxmpp package.

Contents:

• User guide
  • Installation
  • Quick start
  • Pitfalls to avoid
  • Frequently Asked Questions
  • An Introduction to XSO
• The aioxmpp package
  • On API stability and versioning
  • Version information
  • Overview of Services
  • Shorthands
  • Main classes
  • Protocol part and XEP implementations
  • Less common and helper classes
  • APIs mainly relevant for extension developers
  • Internal tools
  • Changelog
• Developer Guide
  • Testing
• Glossary

Feature overview

• Native XEP-0198 (Stream Management) support for robustness against transient network failures (such as switching between wireless and wired networks).

• Powerful declarative-style definition of XEP-based and custom protocols via aioxmpp.xso and aioxmpp.service. Most of the time, you will not get in contact with raw XML or character data, even when implementing a new protocol.

• Secure by default: TLS is required by default, as well as certificate validation. Certificate or public key pinning can be used, if needed.

• Support for RFC 6121 (Instant Messaging and Presence, aioxmpp.presence, aioxmpp.roster) roster and presence management, along with XEP-0045 (Multi-User Chats, aioxmpp.muc) for your human-to-human needs.

• Support for XEP-0060 (Publish-Subscribe, aioxmpp.pubsub) and XEP-0050 (Ad-Hoc Commands, aioxmpp.adhoc) for your machine-to-machine needs.

• Several other XEPs, such as XEP-0115 (Entity Capabilities, aioxmpp.entitycaps, including native support for reading and writing the capsdb) and XEP-0131 (Stanza Headers and Internet Metadata, aioxmpp.shim).

• APIs suitable for both one-shot scripts and long-running multi-account clients.

• Well-tested and modular codebase: aioxmpp is developed in test-driven style and many modules are automatedly tested against a Prosody 0.9, 0.10 and the most recent development version, as well as ejabberd, two popular XMPP servers.

  

Check out the Quick start to get started with aioxmpp now! ☺

Supported protocols

The referenced standards are ordered by their serial number. Not included are specifications which define procedures which were followed or which are described in the documentation. Those are also linked at the respective places throughout the docs.

From IETF RFCs

• RFC 4505 (SASL ANONYMOUS), see aioxmpp.make_security_layer() and aiosasl
• RFC 4616 (SASL PLAIN), see aioxmpp.make_security_layer() and aiosasl
• RFC 5802 (SASL SCRAM), see aioxmpp.make_security_layer() and aiosasl
• RFC 6120 (XMPP Core), including some of the legacy from RFC 3920
• RFC 6121 (XMPP Instant Messaging and Presence)
  • see aioxmpp.presence for managing inbound presence
  • see aioxmpp.roster for managing the roster and presence subscriptions
• RFC 6122 (XMPP Address Format)

From XMPP Extension Proposals (XEPs)

• XEP-0004 (Data Forms), see aioxmpp.forms
• XEP-0027 (Current Jabber OpenPGP Usage), schema-only, see aioxmpp.misc
• XEP-0030 (Service Discovery), see aioxmpp.disco
• XEP-0045 (Multi-User Chat), see aioxmpp.muc
• XEP-0048 (Bookmarks), see aioxmpp.bookmarks
• XEP-0049 (Private XML Storage), see aioxmpp.private_xml
• XEP-0047 (In-Band Bytestreams), see aioxmpp.ibb
• XEP-0050 (Ad-Hoc Commands), see aioxmpp.adhoc (no support for offering commands to other entities)
• XEP-0059 (Result Set Management), see aioxmpp.rsm
• XEP-0060 (Publish-Subscribe), see aioxmpp.pubsub
• XEP-0066 (Out-of-Band Data), schema-only, see aioxmpp.misc
• XEP-0068 (Field Standardisation for Data Forms), see aioxmpp.forms
• XEP-0077 (In-Band Registration), see aioxmpp.ibr
• XEP-0082 (XMPP Date and Time Profiles), via aioxmpp.xso.DateTime and others
• XEP-0084 (User Avatar), see aioxmpp.avatar
• XEP-0092 (Software Version), see aioxmpp.version
• XEP-0106 (JID Escaping), see aioxmpp.jid_unescape(), aioxmpp.jid_escape()
• XEP-0115 (Entity Capabilities), see aioxmpp.entitycaps, including read/write support for the capsdb
• XEP-0163 (Personal Eventing Protocol), see aioxmpp.pep
• XEP-0184 (Message Delivery Receipts), see aioxmpp.mdr
• XEP-0191 (Blocking Command), see aioxmpp.blocking
• XEP-0198 (Stream Management), always enabled if supported by the server
• XEP-0199 (XMPP Ping), used for aliveness-checks if Stream Management is not avaliable and aioxmpp.ping
• XEP-0203 (Delayed Delivery), see aioxmpp.misc
• XEP-0249 (Direct MUC Invitations), see aioxmpp.muc
• XEP-0297 (Stanza Forwarding), see aioxmpp.misc
• XEP-0280 (Message Carbons), see aioxmpp.carbons
• XEP-0300 (Use of Cryptographic Hash Functions in XMPP), see aioxmpp.hashes
• XEP-0308 (Last Message Correction), schema-only, see aioxmpp.misc
• XEP-0333 (Chat Markers), schema-only, see aioxmpp.misc
• XEP-0335 (JSON Containers), see aioxmpp.misc
• XEP-0363 (HTTP Upload), see aioxmpp.httpupload
• XEP-0368 (SRV records for XMPP over TLS)
• XEP-0379 (Pre-Authenticared Roster Subscription), schema-only, see aioxmpp.misc
• XEP-0390 (Entity Capabilities 2.0), see aioxmpp.entitycaps

Dependencies

• Python ≥ 3.4 (or Python = 3.3 with tulip and enum34)
• DNSPython
• lxml
• sortedcollections
• tzlocal (for i18n support)
• pyOpenSSL
• pyasn1 and pyasn1_modules
• aiosasl (≥ 0.3 for ANONYMOUS support)
• multidict
• aioopenssl

Contributing

The contribution guidelines are outlined in the README in the source code repository. The repository is hosted at GitHub.

Security Issues

If you believe that a bug you found in aioxmpp has security implications, you are welcome to notify me privately. To do so, send a mail to Jonas Schäfer, encrypted using the GPG public key:

0xE5EDE5AC679E300F
Fingerprint AA5A 78FF 508D 8CF4 F355  F682 E5ED E5AC 679E 300F

If you prefer to disclose security issues immediately, you can do so at any of the places listed in the contribution guidelines (see above).

Indices and tables

• Index
• Module Index
• Search Page