API Reference

class xmpp.networking.XMPPConnection(host, port=5222, debug=False, auto_reconnect=False, queue_class=<class Queue.Queue>, hwm_in=256, hwm_out=256, recv_chunk_size=65536)

Event-based TCP/TLS connection.

It buffers up received messages and also the messages to be sent.

Parameters:

• host – a string containing a domain or ip address. If a domain is given the name will be resolved before connecting.
• port – defaults to 5222. If you are using a component you might point to 5347 or something else.
• debug – bool defaults to False: whether to print the XML traffic on stderr
• queue_class – bool defaults to :py:class`Queue.Queue`
• hwm_in – int defaults to 256: how many incomming messages to buffer before blocking
• hwm_out – int defaults to 256: how many outcomming messages to buffer before blocking
• recv_chunk_size – int defaults to 65536: how many bytes to read at a time.

connect(timeout_in_seconds=3)

connects

Parameters:timeout_in_seconds –

disconnect()

disconencts the socket

published events:

• tcp_disconnect("intentional") - when succeeded

Parameters:timeout_in_seconds –

is_alive()

Returns:True if the connection is alive

loop_once(timeout=3)

entrypoint for any mainloop.

basically call this continuously to keep the connection up

perform_read(connection)

reads from the socket and populates the read queue :param connection: a socket that is ready to write

perform_write(connection)

consumes the write queue and writes to the given socket

Parameters:connection – a socket that is ready to write

receive(timeout=3)

retrieves a message from the queue, returns None if there are no messages.

Parameters:timeout – int in seconds

reconnect(timeout_in_seconds=3)

reconnects the socket

published events:

• tcp_restablished(host) - when succeeded
• tcp_failed(host) - when failed

Parameters:timeout_in_seconds –

resolve_dns()

resolves the given host

send(data, timeout=3)

adds bytes to the be sent in the next time the socket is ready

Parameters:

• data – the data to be sent
• timeout – int in seconds

send_whitespace_keepalive(timeout=3)

sends a whitespace keepalive to avoid connection timeouts and dead connections

published events:

• tcp_disconnect("intentional") - when succeeded

Parameters:timeout_in_seconds –

class xmpp.stream.XMLStream(connection, debug=False)

XML Stream behavior class.

Parameters:

• connection – a XMPPConnection instance
• debug – whether to print errors to the stderr

add_contact(contact_jid, from_jid=None, groups=None)

adds a contact to the roster of the bound_jid or the provided from_jid parameter.

Automatically sends a <presence type="subscribe"> with a subsequent <iq type="set">.

Parameters:

• contact_jid – the jid to add in the roster
• from_jid – custom from= field to designate the owner of the roster
• groups – a list of strings with group names to categorize this contact in the roster

bind_to_resource(name)

sends an <iq type="set"><resource>name</resource></iq> in order to bind the resource

Parameters:name – the name of the resource

bound_jid

a JID or None

Automatically captured from the XML traffic.

close(disconnect=True)

sends a final </stream:stream> to the server then immediately closes the bound TCP connection,disposes it and resets the minimum state kept by the stream, so it can be reutilized right away.

feed(data, attempt=1)

feeds the stream with incoming data from the XMPP server. This is the basic entrypoint for usage with the XML received from the XMPPConnection

Parameters:data – the XML string

id

returns the stream id provided by the server. <stream:stream id="SOMETHING">

Mainly used by the authenticate() when crafting the secret.

load_extensions()

reloads all the available extensions bound to this stream

open_client(domain)

Sends a <stream:stream xmlns=”jabber:client”> to the given domain

Parameters:domain – the FQDN of the XMPP server

parse()

attempts to parse whatever is in the buffer of the incremental XML parser and creates a new parser.

ready_to_read(_, connection)

event handler for the on.ready_to_read event of a XMPP Connection.

You should probably never have to call this by hand, use bind() instead

ready_to_write(_, connection)

even handler for the on.ready_to_write event of a XMPP Connection.

You should probably never have to call this by hand, use bind() instead

reset()

resets the minimal state of the XML Stream, that is: * attributes of the <stream> sent by the server during negotiation, used by id() * a bound JID sent by the server * a successful sasl result node to leverage has_gone_through_sasl()

send(node)

sends a XML serialized Node through the bound XMPP connection

Parameters:node – the Node

send_message(message, to, **params)

Parameters:

• message – the string with the message
• to – the jid to send the message to
• **params –

  keyword args for designating attributes of the message

send_presence(to=None, delay=None, priority=10, **params)

sends presence

Parameters:

• to – jid to receive presence.
• delay – if set, it must be a ISO compatible date string
• priority – the priority of this resource

send_sasl_auth(mechanism, message)

sends a SASL response to the server in order to proceed with authentication handshakes

Parameters:mechanism – the name of SASL mechanism (i.e. SCRAM-SHA-1, PLAIN, EXTERNAL)

send_sasl_response(mechanism, message)

sends a SASL response to the server in order to proceed with authentication handshakes

Parameters:mechanism – the name of SASL mechanism (i.e. SCRAM-SHA-1, PLAIN, EXTERNAL)

class xmpp.models.node.Node(element, closed=False)

Base class for all XML node definitions.

The xmpp library only supports XML tags that are explicitly defined as python classes that inherit from this one.

classmethod create(_stringcontent=None, **kw)

creates a node instance

Parameters:

• _stringcontent – the content text of the tag, if any
• **kw –

  keyword arguments that will become tag attributes

class xmpp.models.core.ClientStream(element, closed=False)

<stream:stream xmlns='jabber:client' version="1.0" xmlns:stream='http://etherx.jabber.org/streams' />

class xmpp.models.core.IQ(element, closed=False)

<iq></iq>

class xmpp.models.core.IQRegister(element, closed=False)

<register xmlns="http://jabber.org/features/iq-register" />

class xmpp.models.core.Message(element, closed=False)

<message type="chat"></message>

exception xmpp.models.core.MissingJID

raised when trying to send a stanza but it is missing either the “to” or “from” fields

class xmpp.models.core.Presence(element, closed=False)

<presence></presence>

class xmpp.models.core.ProceedTLS(element, closed=False)

<proceed xmlns="urn:ietf:params:xml:ns:xmpp-tls" />

class xmpp.models.core.SASLMechanism(element, closed=False)

<mechanism></mechanism>

class xmpp.models.core.SASLMechanismSet(element, closed=False)

<mechanisms xmlns="urn:ietf:params:xml:ns:xmpp-sasl"></mechanisms>

class xmpp.models.core.StartTLS(element, closed=False)

<starttls xmlns="urn:ietf:params:xml:ns:xmpp-tls" />

class xmpp.models.core.StreamFeatures(element, closed=False)

<stream:features></stream:features>

SASL authentication implementaion for PyXMPP.

Normative reference:

• RFC 4422

xmpp.sasl.filter_mechanism_list(mechanisms, properties, allow_insecure=False, server_side=False)

Filter a mechanisms list only to include those mechanisms that cans succeed with the provided properties and are secure enough.

Parameters:

• mechanisms: list of the mechanisms names
• properties: available authentication properties
• allow_insecure: allow insecure mechanisms

Types:

• mechanisms: sequence of unicode
• properties: mapping
• allow_insecure: bool

Returntype:

list of unicode

xmpp.sasl.server_authenticator_factory(mechanism, password_database)

Create a server authenticator object for given SASL mechanism and password databaser.

Parameters:

• mechanism: name of the SASL mechanism (“PLAIN”, “DIGEST-MD5” or “GSSAPI”).
• password_database: name of the password database object to be used for authentication credentials verification.

Types:

• mechanism: str
• password_database: PasswordDatabase

Raises:

KeyError – if no server authenticator is available for this mechanism

Returns:

new authenticator.

Returntype:

sasl.core.ServerAuthenticator

xmpp.sasl.client_authenticator_factory(mechanism)

Create a client authenticator object for given SASL mechanism.

Parameters:

• mechanism: name of the SASL mechanism (“PLAIN”, “DIGEST-MD5” or “GSSAPI”).

Types:

• mechanism: unicode

Raises:

KeyError – if no client authenticator is available for this mechanism

Returns:

new authenticator.

Returntype:

sasl.core.ClientAuthenticator

class xmpp.sasl.Success(properties=None, data=None)

The success SASL message (sent by the server on authentication success).

class xmpp.sasl.Failure(reason)

The failure SASL message.

Ivariables:

• reason: the failure reason.

Types:

• reason: unicode.

class xmpp.sasl.Challenge(data)

The challenge SASL message (server’s challenge for the client).

class xmpp.sasl.Response(data)

The response SASL message (clients’s reply the server’s challenge).

class xmpp.sasl.Reply(data=None)

Base class for SASL authentication reply objects.

Ivariables:

• data: optional reply data.

Types:

• data: bytes

encode()

Base64-encode the data contained in the reply when appropriate.

Returns:encoded data. Returntype:unicode

class xmpp.sasl.PasswordDatabase

Password database interface.

PasswordDatabase object is responsible for providing or verification of user authentication credentials on a server.

All the methods of the PasswordDatabase may be overridden in derived classes for specific authentication and authorization policy.

check_password(username, password, properties)

Check the password validity.

Used by plain-text authentication mechanisms.

Default implementation: retrieve a “plain” password for the username and realm using self.get_password and compare it with the password provided.

May be overridden e.g. to check the password against some external authentication mechanism (PAM, LDAP, etc.).

Parameters:

• username: the username for which the password verification is requested.
• password: the password to verify.
• properties: mapping with authentication properties (those provided to the authenticator’s start() method plus some already obtained via the mechanism).

Types:

• username: unicode
• password: unicode
• properties: mapping

Returns:

True if the password is valid.

Returntype:

bool

get_password(username, acceptable_formats, properties)

Get the password for user authentication.

By default returns (None, None) providing no password. Should be overridden in derived classes unless only check_password functionality is available.

Parameters:

• username: the username for which the password is requested.
• acceptable_formats: a sequence of acceptable formats of the password data. Could be “plain” (plain text password), “md5:user:realm:password” (MD5 hex digest of user:realm:password) or any other mechanism-specific encoding. This allows non-plain-text storage of passwords. But only “plain” format will work with all password authentication mechanisms.
• properties: mapping with authentication properties (those provided to the authenticator’s start() method plus some already obtained via the mechanism).

Types:

• username: unicode
• acceptable_formats: sequence of unicode
• properties: mapping

Returns:

the password and its encoding (format).

Returntype:

unicode,`unicode` tuple.