# `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.