Internal “API”#

Slixmpp has a generic API registry that can be used by its plugins to allow access control, redefinition of behaviour, without having to inherit from the plugin or do more dark magic.

The idea is that each api call can be replaced, most of them use a form of in-memory storage that can be, for example, replaced with database or file-based storaged.

Each plugin is assigned an API proxy bound to itself, but only a few make use of it.

See also Flexible internal API usage.

Description of a generic API call#

def get_toto(jid, node, ifrom, args):
    return 'toto'

self.xmpp.plugin['xep_XXXX'].api.register(handler, 'get_toto')

Each API call will receive 4 parameters (which can be None if data is not relevant to the operation), which are jid (Optional[JID]), node (Optional[str]), ifrom (Optional[JID]), and args (Any).

  • jid, if relevant, represents the JID targeted by that operation

  • node, if relevant is an arbitrary string, but was thought for, e.g., a pubsub or disco node.

  • ifrom, if relevant, is the JID the event is coming from.

  • args is the event-specific data passed on by the plugin, often a dict of arguments (can be None as well).

Note

Since 1.8.0, API calls can be coroutines.

Handler hierarchy#

The self.api.register() signature is as follows:

def register(handler, op, jid=None, node=None, default=False):
    pass

As you can see, register() takes an additional ctype parameter, but the APIWrapper takes care of that for us (in most cases, it is the name of the XEP plugin, such as 'xep_0XXX').

When you register a handler, you register it for an op, for operation. For example, get_vcard.

handler and op are the only two required parameters (and in many cases, all you will ever need). You can, however, go further and register handlers for specific values of the jid and node parameters of the calls.

The priority of the execution of handlers is as follows:

  • Check if a handler for both values of node and jid has been defined

  • If not found, check if a handler for this value of jid has been defined

  • If not found, check if a handler for this value of node has been defined

  • If still not found, get the global handler (no parameter registered)

Raw documentation#

This documentation is provided for reference, but register() should be all you need.

class slixmpp.api.APIRegistry(xmpp)[source]#

API Registry.

This class is the global Slixmpp API registry, on which any handler will be registed.

purge(ctype)[source]#

Remove all information for a given API.

Return type

None

register(handler, ctype, op, jid=None, node=None, default=False)[source]#

Register an API callback, with JID+node specificity.

The API callback can later be executed based on the specificity of the provided JID+node combination.

See run() for more details.

Parameters

  • ctype (str) – The name of the API to use.

  • op (str) – The API operation to perform.

  • jid (Optional[JID]) – Optionally provide specific JID.

  • node (Optional[str]) – Optionally provide specific node.

register_default(handler, ctype, op)[source]#

Register a default, global handler for an operation.

Parameters

  • handler – The default, global handler for the operation.

  • ctype (str) – The name of the API to modify.

  • op (str) – The API operation to use.

restore_default(ctype, op, jid=None, node=None)[source]#

Reset an API callback to use a default handler.

Parameters

  • ctype (str) – The name of the API to use.

  • op (str) – The API operation to perform.

  • jid (Optional[JID]) – Optionally provide specific JID.

  • node (Optional[str]) – Optionally provide specific node.

run(ctype, op, jid=None, node=None, ifrom=None, args=None)[source]#

Execute an API callback, based on specificity.

The API callback that is executed is chosen based on the combination of the provided JID and node:

JID

node

Handler

Given

Given

Node + JID handler

Given

None

JID handler

None

Given

Node handler

None

None

Global handler

A node handler is responsible for servicing a single node at a single JID, while a JID handler may respond for any node at a given JID, and the global handler will answer to any JID+node combination.

Handlers should check that the JID ifrom is authorized to perform the desired action.

Changed in version 1.8.0: run() always returns a future, if the handler is a coroutine the future should be awaited on.

Parameters

  • ctype (str) – The name of the API to use.

  • op (str) – The API operation to perform.

  • jid (Optional[JID]) – Optionally provide specific JID.

  • node (Optional[str]) – Optionally provide specific node.

  • ifrom (Optional[JID]) – Optionally provide the requesting JID.

  • args (Optional[Any]) – Optional arguments to the handler.

Return type

Future

unregister(ctype, op, jid=None, node=None)[source]#

Remove an API callback.

The API callback chosen for removal is based on the specificity of the provided JID+node combination.

See run() for more details.

Parameters

  • ctype (str) – The name of the API to use.

  • op (str) – The API operation to perform.

  • jid (Optional[JID]) – Optionally provide specific JID.

  • node (Optional[str]) – Optionally provide specific node.

wrap(ctype)[source]#

Return a wrapper object that targets a specific API.

Return type

APIWrapper

class slixmpp.api.APIWrapper(api, name)[source]#

Slixmpp API wrapper.

This class provide a shortened binding to access self.api from plugins without having to specify the plugin name or the global APIRegistry.