dispatcher — Dispatch stanzas to callbacks

New in version 0.9: The whole module was added in 0.9.

Stanza Dispatchers for Messages and Presences

class aioxmpp.dispatcher.SimpleMessageDispatcher(client, *, logger_base=None, dependencies={}, service_order_index=0)

Dispatch messages to callbacks.

This Service dispatches Message stanzas to callbacks. Callbacks registrations are managed with the SimpleStanzaDispatcher.register_callback() and SimpleStanzaDispatcher.unregister_callback() methods of the base class. The type_ argument to these methods must be a aioxmpp.MessageType or None to make any sense.

Note

It is not recommended to mix the use of a SimpleMessageDispatcher with the modern Instant Messaging features provided by the aioxmpp.im module. Both will receive the messages and this may thus lead to duplicate messages.

class aioxmpp.dispatcher.SimplePresenceDispatcher(client, *, logger_base=None, dependencies={}, service_order_index=0)

Dispatch presences to callbacks.

This Service dispatches Presence stanzas to callbacks. Callbacks registrations are managed with the SimpleStanzaDispatcher.register_callback() and SimpleStanzaDispatcher.unregister_callback() methods of the base class. The type_ argument to these methods must be a aioxmpp.MessageType or None to make any sense.

Warning

It is not recommended to mix the use of a SimplePresenceDispatcher with aioxmpp.RosterClient and aioxmpp.PresenceClient. Both of these register callbacks at the SimplePresenceDispatcher. Registering callbacks for different slots will either make those callbacks not be called at all or will make the services miss stanzas.

Decorators for aioxmpp.service.Service Methods

@aioxmpp.dispatcher.message_handler(type_, from_)

Register the decorated function as message handler.

Parameters

• type (MessageType) – Message type to listen for

• from (aioxmpp.JID or None) – Sender JIDs to listen for

Raises

TypeError – if the decorated object is a coroutine function

See also

register_message_callback()

for more details on the type_ and from_ arguments

Changed in version 0.9: This is now based on aioxmpp.dispatcher.SimpleMessageDispatcher.

@aioxmpp.dispatcher.presence_handler(type_, from_)

Register the decorated function as presence stanza handler.

Parameters

• type (PresenceType) – Presence type to listen for

• from (aioxmpp.JID or None) – Sender JIDs to listen for

Raises

TypeError – if the decorated object is a coroutine function

See also

register_presence_callback()

for more details on the type_ and from_ arguments

Changed in version 0.9: This is now based on aioxmpp.dispatcher.SimplePresenceDispatcher.

Test Functions

aioxmpp.dispatcher.is_message_handler(type_, from_, cb)

Return true if cb has been decorated with message_handler() for the given type_ and from_.

aioxmpp.dispatcher.is_presence_handler(type_, from_, cb)

Return true if cb has been decorated with presence_handler() for the given type_ and from_.

Base Class for Stanza Dispatchers

class aioxmpp.dispatcher.SimpleStanzaDispatcher(**kwargs)

Dispatch stanzas based on their sender and type.

This is a service base class (not a service you should summon) which can be used to implement simple, pre-0.9 presence and message dispatching.

For users, the following methods are relevant:

register_callback(type_, from_, cb, *, wildcard_resource=True)

Register a callback function.

Parameters

• type – Stanza type to listen for, or None for a wildcard match.

• from (aioxmpp.JID or None) – Sender to listen for, or None for a full wildcard match.

• cb – Callback function to register

• wildcard_resource (bool) – Whether to wildcard the resourcepart of the JID.

Raises

ValueError – if another function is already registered for the callback slot.

cb will be called whenever a stanza with the matching type_ and from_ is processed. The following wildcarding rules apply:

1. If the from_ attribute of the stanza has a resourcepart, the following lookup order for callbacks is used:

   type_	from_	wildcard_resource
   type_	from_	any
   type_	bare from_	True
   None	from_	any
   None	bare from_	True
   type_	None	any
   None	None	any

2. If the from_ attribute of the stanza does not have a resourcepart, the following lookup order for callbacks is used:

   type_	from_	wildcard_resource
   type_	from_	False
   None	from_	False
   type_	None	any
   None	None	any

Only the first callback which matches is called. wildcard_resource is ignored if from_ is a full JID or None.

Note

When the server sends a stanza without from attribute, it is replaced with the bare local_jid, as per RFC 6120.

unregister_callback(type_, from_, *, wildcard_resource=True)

Unregister a callback function.

Parameters

• type – Stanza type to listen for, or None for a wildcard match.

• from (aioxmpp.JID or None) – Sender to listen for, or None for a full wildcard match.

• wildcard_resource (bool) – Whether to wildcard the resourcepart of the JID.

The callback must be disconnected with the same arguments as were used to connect it.

handler_context(type_, from_, cb, *, wildcard_resource=True)

Context manager which temporarily registers a callback.

The arguments are the same as for register_callback().

When the context is entered, the callback cb is registered. When the context is exited, no matter if an exception is raised or not, the callback is unregistered.

For deriving classes, the following methods are relevant:

_feed(stanza)

Dispatch the given stanza.

Parameters

stanza (StanzaBase) – Stanza to dispatch

Return type

bool

Returns

true if the stanza was dispatched, false otherwise.

Dispatch the stanza to up to one handler registered on the dispatcher. If no handler is found for the stanza, False is returned. Otherwise, True is returned.

Subclasses must also provide the following property:

local_jid

The bare JID of the client for which this dispatcher is used.

This is required to map missing @from attributes to this JID. The attribute must be provided by implementing subclasses.