Begin experiment with a centralized API callback registry.

The API registry generalizes the node handler system from the xep_0030
plugin so that other plugins can use it.

6 files changed, 260 insertions, 97 deletions

diff --git a/sleekxmpp/api.py b/sleekxmpp/api.py
new file mode 100644
index 00000000..9d8ec201
--- /dev/null
+++ b/sleekxmpp/api.py
@@ -0,0 +1,191 @@
+from sleekxmpp.xmlstream import JID
+
+
+class APIWrapper(object):
+
+    def __init__(self, api, name):
+        self.api = api
+        self.name = name
+
+    def __getattr__(self, attr):
+        """Curry API management commands with the API name."""
+        if attr == 'name':
+            return self.name
+        elif attr == 'settings':
+            return self.api.settings[self.name]
+        elif attr == 'register':
+            def curried_handler(handler, op, jid=None, node=None):
+                register = getattr(self.api, attr)
+                return register(handler, self.name, op, jid, node)
+            return curried_handler
+        elif attr == 'register_default':
+            def curried_handler(handler, op, jid=None, node=None):
+                return getattr(self.api, attr)(handler, self.name, op)
+            return curried_handler
+        elif attr in ('run', 'restore_default', 'unregister'):
+            def curried_handler(*args, **kwargs):
+                return getattr(self.api, attr)(self.name, *args, **kwargs)
+            return curried_handler
+        return None
+
+    def __getitem__(self, attr):
+        def curried_handler(jid=None, node=None, ifrom=None, args=None):
+            return self.api.run(self.name, attr, jid, node, ifrom, args)
+        return curried_handler
+
+
+class APIRegistry(object):
+
+    def __init__(self, xmpp):
+        self._handlers = {}
+        self._handler_defaults = {}
+        self.xmpp = xmpp
+        self.settings = {} 
+
+    def _setup(self, ctype, op):
+        """Initialize the API callback dictionaries.
+
+        :param string ctype: The name of the API to initialize.
+        :param string op: The API operation to initialize.
+        """
+        if ctype not in self.settings:
+            self.settings[ctype] = {}
+        if ctype not in self._handler_defaults:
+            self._handler_defaults[ctype] = {}
+        if ctype not in self._handlers:
+            self._handlers[ctype] = {}
+        if op not in self._handlers[ctype]:
+            self._handlers[ctype][op] = {'global': None,
+                                         'jid': {},
+                                         'node': {}}
+
+    def wrap(self, ctype):
+        """Return a wrapper object that targets a specific API."""
+        return APIWrapper(self, ctype)
+
+    def purge(self, ctype):
+        """Remove all information for a given API."""
+        del self.settings[ctype]
+        del self._handler_defaults[ctype]
+        del self._handlers[ctype]
+
+    def run(self, ctype, op, jid=None, node=None, ifrom=None, args=None):
+        """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 handler
+        Given | None  | JID 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.
+
+        :param string ctype: The name of the API to use.
+        :param string op: The API operation to perform.
+        :param JID jid: Optionally provide specific JID.
+        :param string node: Optionally provide specific node.
+        :param JID ifrom: Optionally provide the requesting JID.
+        :param tuple args: Optional positional arguments to the handler.
+        """
+        self._setup(ctype, op)
+
+        if jid in (None, ''):
+            jid = self.xmpp.boundjid
+        if jid and not isinstance(jid, JID):
+            jid = JID(jid)
+
+        if node is None:
+            node = ''
+
+        if self.xmpp.is_component:
+            if self.settings[ctype].get('component_bare', False):
+                jid = jid.bare
+            else:
+                jid = jid.full
+        else:
+            if self.settings[ctype].get('client_bare', True):
+                jid = jid.bare
+            else:
+                jid = jid.full
+
+        handler = self._handlers[ctype][op]['node'].get((jid, node), None)
+        if handler is None:
+            handler = self._handlers[ctype][op]['jid'].get(jid, None)
+        if handler is None:
+            handler = self._handlers[ctype][op].get('global', None)
+
+        if handler:
+            try:
+                return handler(jid, node, ifrom, args)
+            except TypeError:
+                # To preserve backward compatibility, drop the ifrom
+                # parameter for existing handlers that don't understand it.
+                return handler(jid, node, args)
+
+    def register(self, handler, ctype, op, jid=None, node=None, default=False):
+        """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 :meth:`~ApiRegistry.run` for more details.
+
+        :param string ctype: The name of the API to use.
+        :param string op: The API operation to perform.
+        :param JID jid: Optionally provide specific JID.
+        :param string node: Optionally provide specific node.
+        """
+        self._setup(ctype, op)
+        if jid is None and node is None:
+            if handler is None:
+                handler = self._handler_defaults[op]
+            self._handlers[ctype][op]['global'] = handler
+        elif jid is not None and node is None:
+            self._handlers[ctype][op]['jid'][jid] = handler
+        else:
+            self._handlers[ctype][op]['node'][(jid, node)] = handler
+
+    def register_default(self, handler, ctype, op):
+        """Register a default, global handler for an operation.
+
+        :param func handler: The default, global handler for the operation.
+        :param string ctype: The name of the API to modify.
+        :param string op: The API operation to use.
+        """
+        self._setup(ctype, op)
+        self._handler_defaults[ctype][op] = handler
+
+    def unregister(self, ctype, op, jid=None, node=None):
+        """Remove an API callback.
+
+        The API callback chosen for removal is based on the
+        specificity of the provided JID+node combination.
+
+        See :meth:`~ApiRegistry.run` for more details.
+
+        :param string ctype: The name of the API to use.
+        :param string op: The API operation to perform.
+        :param JID jid: Optionally provide specific JID.
+        :param string node: Optionally provide specific node.
+        """
+        self._setup(ctype, op)
+        self.register(None, ctype, op, jid, node)
+
+    def restore_default(self, ctype, op, jid=None, node=None):
+        """Reset an API callback to use a default handler.
+
+        :param string ctype: The name of the API to use.
+        :param string op: The API operation to perform.
+        :param JID jid: Optionally provide specific JID.
+        :param string node: Optionally provide specific node.
+        """
+        self.unregister(ctype, op, jid, node)
+        self.register(self._handler_defaults[ctype][op], ctype, op, jid, node)
diff --git a/sleekxmpp/basexmpp.py b/sleekxmpp/basexmpp.py
index dc1f6b94..5fcfbf6d 100644
--- a/sleekxmpp/basexmpp.py
+++ b/sleekxmpp/basexmpp.py
@@ -19,6 +19,7 @@ import logging
 
 import sleekxmpp
 from sleekxmpp import plugins, features, roster
+from sleekxmpp.api import APIRegistry
 from sleekxmpp.exceptions import IqError, IqTimeout
 
 from sleekxmpp.stanza import Message, Presence, Iq, StreamError
@@ -97,6 +98,22 @@ class BaseXMPP(XMLStream):
         #: ``'to'`` and ``'from'`` JIDs of stanzas.
         self.is_component = False
 
+        #: The API registry is a way to process callbacks based on
+        #: JID+node combinations. Each callback in the registry is
+        #: marked with:
+        #: 
+        #:   - An API name, e.g. xep_0030
+        #:   - The name of an action, e.g. get_info
+        #:   - The JID that will be affected
+        #:   - The node that will be affected
+        #:
+        #: API handlers with no JID or node will act as global handlers,
+        #: while those with a JID and no node will service all nodes
+        #: for a JID, and handlers with both a JID and node will be
+        #: used only for that specific combination. The handler that
+        #: provides the most specificity will be used.
+        self.api = APIRegistry(self)
+
         #: Flag indicating that the initial presence broadcast has
         #: been sent. Until this happens, some servers may not
         #: behave as expected when sending stanzas.
diff --git a/sleekxmpp/plugins/base.py b/sleekxmpp/plugins/base.py
index f08023ba..ccea5ce4 100644
--- a/sleekxmpp/plugins/base.py
+++ b/sleekxmpp/plugins/base.py
@@ -269,6 +269,7 @@ class BasePlugin(object):
 
     def __init__(self, xmpp, config=None):
         self.xmpp = xmpp
+        self.api = self.xmpp.api.wrap(self.name)
 
         #: A plugin's behaviour may be configurable, in which case those
         #: configuration settings will be provided as a dictionary.
diff --git a/sleekxmpp/plugins/xep_0030/disco.py b/sleekxmpp/plugins/xep_0030/disco.py
index a5e8fd1c..76824e1c 100644
--- a/sleekxmpp/plugins/xep_0030/disco.py
+++ b/sleekxmpp/plugins/xep_0030/disco.py
@@ -118,16 +118,13 @@ class XEP_0030(BasePlugin):
                 'del_item', 'del_identities', 'del_features', 'cache_info',
                 'get_cached_info', 'supports', 'has_identity']
 
-        self.default_handlers = {}
-        self._handlers = {}
         for op in self._disco_ops:
-            self._add_disco_op(op, getattr(self.static, op))
+            self.api.register(getattr(self.static, op), op)
+            self.api.register_default(getattr(self.static, op), op)
 
     def _add_disco_op(self, op, default_handler):
-        self.default_handlers[op] = default_handler
-        self._handlers[op] = {'global': default_handler,
-                              'jid': {},
-                              'node': {}}
+        self.api.register(default_handler, op)
+        self.api.register_default(default_handler, op)
 
     def set_node_handler(self, htype, jid=None, node=None, handler=None):
         """
@@ -173,20 +170,7 @@ class XEP_0030(BasePlugin):
                        assumed.
             handler -- The handler function to use.
         """
-        if htype not in self._disco_ops:
-            return
-        if jid is None and node is None:
-            self._handlers[htype]['global'] = handler
-        elif node is None:
-            self._handlers[htype]['jid'][jid] = handler
-        elif jid is None:
-            if self.xmpp.is_component:
-                jid = self.xmpp.boundjid.full
-            else:
-                jid = self.xmpp.boundjid.bare
-            self._handlers[htype]['node'][(jid, node)] = handler
-        else:
-            self._handlers[htype]['node'][(jid, node)] = handler
+        self.api.register(handler, htype, jid, node)
 
     def del_node_handler(self, htype, jid, node):
         """
@@ -209,7 +193,7 @@ class XEP_0030(BasePlugin):
             jid   -- The JID from which to remove the handler.
             node  -- The node from which to remove the handler.
         """
-        self.set_node_handler(htype, jid, node, None)
+        self.api.unregister(htype, jid, node)
 
     def restore_defaults(self, jid=None, node=None, handlers=None):
         """
@@ -232,8 +216,7 @@ class XEP_0030(BasePlugin):
         if handlers is None:
             handlers = self._disco_ops
         for op in handlers:
-            self.del_node_handler(op, jid, node)
-            self.set_node_handler(op, jid, node, self.default_handlers[op])
+            self.api.restore_default(op, jid, node)
 
     def supports(self, jid=None, node=None, feature=None, local=False,
                        cached=True, ifrom=None):
@@ -266,7 +249,7 @@ class XEP_0030(BasePlugin):
         data = {'feature': feature,
                 'local': local,
                 'cached': cached}
-        return self._run_node_handler('supports', jid, node, ifrom, data)
+        return self.api['supports'](jid, node, ifrom, data)
 
     def has_identity(self, jid=None, node=None, category=None, itype=None,
                      lang=None, local=False, cached=True, ifrom=None):
@@ -303,7 +286,7 @@ class XEP_0030(BasePlugin):
                 'lang': lang,
                 'local': local,
                 'cached': cached}
-        return self._run_node_handler('has_identity', jid, node, ifrom, data)
+        return self.api['has_identity'](jid, node, ifrom, data)
 
     def get_info(self, jid=None, node=None, local=False,
                        cached=None, **kwargs):
@@ -355,16 +338,18 @@ class XEP_0030(BasePlugin):
         if local or jid in (None, ''):
             log.debug("Looking up local disco#info data " + \
                       "for %s, node %s.", jid, node)
-            info = self._run_node_handler('get_info',
-                    jid, node, kwargs.get('ifrom', None), kwargs)
+            info = self.api['get_info'](jid, node, 
+                    kwargs.get('ifrom', None), 
+                    kwargs)
             info = self._fix_default_info(info)
             return self._wrap(kwargs.get('ifrom', None), jid, info)
 
         if cached:
             log.debug("Looking up cached disco#info data " + \
                       "for %s, node %s.", jid, node)
-            info = self._run_node_handler('get_cached_info',
-                    jid, node, kwargs.get('ifrom', None), kwargs)
+            info = self.api['get_cached_info'](jid, node, 
+                    kwargs.get('ifrom', None), 
+                    kwargs)
             if info is not None:
                 return self._wrap(kwargs.get('ifrom', None), jid, info)
 
@@ -385,7 +370,7 @@ class XEP_0030(BasePlugin):
         """
         if isinstance(info, Iq):
             info = info['disco_info']
-        self._run_node_handler('set_info', jid, node, None, info)
+        self.api['set_info'](jid, node, None, info)
 
     def get_items(self, jid=None, node=None, local=False, **kwargs):
         """
@@ -419,8 +404,9 @@ class XEP_0030(BasePlugin):
                         Otherwise the parameter is ignored.
         """
         if local or jid is None:
-            items = self._run_node_handler('get_items',
-                    jid, node, kwargs.get('ifrom', None), kwargs)
+            items = self.api['get_items'](jid, node, 
+                    kwargs.get('ifrom', None), 
+                    kwargs)
             return self._wrap(kwargs.get('ifrom', None), jid, items)
 
         iq = self.xmpp.Iq()
@@ -448,7 +434,7 @@ class XEP_0030(BasePlugin):
             node  -- Optional node to modify.
             items -- A series of items in tuple format.
         """
-        self._run_node_handler('set_items', jid, node, None, kwargs)
+        self.api['set_items'](jid, node, None, kwargs)
 
     def del_items(self, jid=None, node=None, **kwargs):
         """
@@ -458,7 +444,7 @@ class XEP_0030(BasePlugin):
             jid  -- The JID to modify.
             node -- Optional node to modify.
         """
-        self._run_node_handler('del_items', jid, node, None, kwargs)
+        self.api['del_items'](jid, node, None, kwargs)
 
     def add_item(self, jid='', name='', node=None, subnode='', ijid=None):
         """
@@ -479,7 +465,7 @@ class XEP_0030(BasePlugin):
         kwargs = {'ijid': jid,
                   'name': name,
                   'inode': subnode}
-        self._run_node_handler('add_item', ijid, node, None, kwargs)
+        self.api['add_item'](ijid, node, None, kwargs)
 
     def del_item(self, jid=None, node=None, **kwargs):
         """
@@ -491,7 +477,7 @@ class XEP_0030(BasePlugin):
             ijid  -- The item's JID.
             inode -- The item's node.
         """
-        self._run_node_handler('del_item', jid, node, None, kwargs)
+        self.api['del_item'](jid, node, None, kwargs)
 
     def add_identity(self, category='', itype='', name='',
                      node=None, jid=None, lang=None):
@@ -518,7 +504,7 @@ class XEP_0030(BasePlugin):
                   'itype': itype,
                   'name': name,
                   'lang': lang}
-        self._run_node_handler('add_identity', jid, node, None, kwargs)
+        self.api['add_identity'](jid, node, None, kwargs)
 
     def add_feature(self, feature, node=None, jid=None):
         """
@@ -530,7 +516,7 @@ class XEP_0030(BasePlugin):
             jid     -- The JID to modify.
         """
         kwargs = {'feature': feature}
-        self._run_node_handler('add_feature', jid, node, None, kwargs)
+        self.api['add_feature'](jid, node, None, kwargs)
 
     def del_identity(self, jid=None, node=None, **kwargs):
         """
@@ -544,7 +530,7 @@ class XEP_0030(BasePlugin):
             name     -- Optional, human readable name for the identity.
             lang     -- Optional, the identity's xml:lang value.
         """
-        self._run_node_handler('del_identity', jid, node, None, kwargs)
+        self.api['del_identity'](jid, node, None, kwargs)
 
     def del_feature(self, jid=None, node=None, **kwargs):
         """
@@ -555,7 +541,7 @@ class XEP_0030(BasePlugin):
             node    -- The node to modify.
             feature -- The feature's namespace.
         """
-        self._run_node_handler('del_feature', jid, node, None, kwargs)
+        self.api['del_feature'](jid, node, None, kwargs)
 
     def set_identities(self, jid=None, node=None, **kwargs):
         """
@@ -570,7 +556,7 @@ class XEP_0030(BasePlugin):
             identities -- A set of identities in tuple form.
             lang       -- Optional, xml:lang value.
         """
-        self._run_node_handler('set_identities', jid, node, None, kwargs)
+        self.api['set_identities'](jid, node, None, kwargs)
 
     def del_identities(self, jid=None, node=None, **kwargs):
         """
@@ -585,7 +571,7 @@ class XEP_0030(BasePlugin):
             lang -- Optional. If given, only remove identities
                     using this xml:lang value.
         """
-        self._run_node_handler('del_identities', jid, node, None, kwargs)
+        self.api['del_identities'](jid, node, None, kwargs)
 
     def set_features(self, jid=None, node=None, **kwargs):
         """
@@ -597,7 +583,7 @@ class XEP_0030(BasePlugin):
             node     -- The node to modify.
             features -- The new set of supported features.
         """
-        self._run_node_handler('set_features', jid, node, None, kwargs)
+        self.api['set_features'](jid, node, None, kwargs)
 
     def del_features(self, jid=None, node=None, **kwargs):
         """
@@ -607,7 +593,7 @@ class XEP_0030(BasePlugin):
             jid  -- The JID to modify.
             node -- The node to modify.
         """
-        self._run_node_handler('del_features', jid, node, None, kwargs)
+        self.api['del_features'](jid, node, None, kwargs)
 
     def _run_node_handler(self, htype, jid, node=None, ifrom=None, data={}):
         """
@@ -620,39 +606,7 @@ class XEP_0030(BasePlugin):
             node  -- The node requested.
             data  -- Optional, custom data to pass to the handler.
         """
-        if isinstance(jid, JID):
-            jid = jid.full
-
-        if jid in (None, ''):
-            if self.xmpp.is_component:
-                jid = self.xmpp.boundjid.full
-            else:
-                jid = self.xmpp.boundjid.bare
-        if node is None:
-            node = ''
-
-        try:
-            args = (jid, node, ifrom, data)
-            if self._handlers[htype]['node'].get((jid, node), False):
-                return self._handlers[htype]['node'][(jid, node)](*args)
-            elif self._handlers[htype]['jid'].get(jid, False):
-                return self._handlers[htype]['jid'][jid](*args)
-            elif self._handlers[htype]['global']:
-                return self._handlers[htype]['global'](*args)
-            else:
-                return None
-        except TypeError:
-            # To preserve backward compatibility, drop the ifrom parameter
-            # for existing handlers that don't understand it.
-            args = (jid, node, data)
-            if self._handlers[htype]['node'].get((jid, node), False):
-                return self._handlers[htype]['node'][(jid, node)](*args)
-            elif self._handlers[htype]['jid'].get(jid, False):
-                return self._handlers[htype]['jid'][jid](*args)
-            elif self._handlers[htype]['global']:
-                return self._handlers[htype]['global'](*args)
-            else:
-                return None
+        return self.api[htype](jid, node, ifrom, data)
 
     def _handle_disco_info(self, iq):
         """
@@ -671,11 +625,10 @@ class XEP_0030(BasePlugin):
                 jid = iq['to'].full
             else:
                 jid = iq['to'].bare
-            info = self._run_node_handler('get_info',
-                                          jid,
-                                          iq['disco_info']['node'],
-                                          iq['from'],
-                                          iq)
+            info = self.api['get_info'](jid,
+                                        iq['disco_info']['node'],
+                                        iq['from'],
+                                        iq)
             if isinstance(info, Iq):
                 info.send()
             else:
@@ -694,8 +647,7 @@ class XEP_0030(BasePlugin):
                     ito = iq['to'].full
                 else:
                     ito = None
-                self._run_node_handler('cache_info',
-                                       iq['from'].full,
+                self.api['cache_info'](iq['from'].full,
                                        iq['disco_info']['node'],
                                        ito,
                                        iq)
@@ -717,8 +669,7 @@ class XEP_0030(BasePlugin):
                 jid = iq['to'].full
             else:
                 jid = iq['to'].bare
-            items = self._run_node_handler('get_items',
-                                          jid,
+            items = self.api['get_items'](jid,
                                           iq['disco_items']['node'],
                                           iq['from'].full,
                                           iq)
diff --git a/sleekxmpp/plugins/xep_0115/caps.py b/sleekxmpp/plugins/xep_0115/caps.py
index 3aa0f70f..fee86f5b 100644
--- a/sleekxmpp/plugins/xep_0115/caps.py
+++ b/sleekxmpp/plugins/xep_0115/caps.py
@@ -78,7 +78,9 @@ class XEP_0115(BasePlugin):
         self.static = StaticCaps(self.xmpp, disco.static)
 
         for op in self._disco_ops:
-            disco._add_disco_op(op, getattr(self.static, op))
+            self.api.register(getattr(self.static, op), 'xep_0115', op)
+            self.api.register_default(getattr(self.static, op), 
+                    'xep_0115', op)
 
         self._run_node_handler = disco._run_node_handler
 
@@ -279,19 +281,19 @@ class XEP_0115(BasePlugin):
             jid = self.xmpp.boundjid.full
         if isinstance(jid, JID):
             jid = jid.full
-        return self._run_node_handler('get_verstring', jid)
+        return self.api['get_verstring'](jid)
 
     def assign_verstring(self, jid=None, verstring=None):
         if jid in (None, ''):
             jid = self.xmpp.boundjid.full
         if isinstance(jid, JID):
             jid = jid.full
-        return self._run_node_handler('assign_verstring', jid, 
-                                      data={'verstring': verstring})
+        return self.api['assign_verstring'](jid, args={
+            'verstring': verstring})
 
     def cache_caps(self, verstring=None, info=None):
         data = {'verstring': verstring, 'info': info}
-        return self._run_node_handler('cache_caps', None, None, data=data)
+        return self.api['cache_caps'](args=data)
 
     def get_caps(self, jid=None, verstring=None):
         if verstring is None:
@@ -302,4 +304,4 @@ class XEP_0115(BasePlugin):
         if isinstance(jid, JID):
             jid = jid.full
         data = {'verstring': verstring}
-        return self._run_node_handler('get_caps', jid, None, None, data)
+        return self.api['get_caps'](jid, args=data)
diff --git a/sleekxmpp/plugins/xep_0128/extended_disco.py b/sleekxmpp/plugins/xep_0128/extended_disco.py
index d49741de..93f8e8f0 100644
--- a/sleekxmpp/plugins/xep_0128/extended_disco.py
+++ b/sleekxmpp/plugins/xep_0128/extended_disco.py
@@ -61,7 +61,8 @@ class XEP_0128(BasePlugin):
         self.disco.del_extended_info = self.del_extended_info
 
         for op in self._disco_ops:
-            self.disco._add_disco_op(op, getattr(self.static, op))
+            self.api.register(getattr(self.static, op), op)
+            self.api.register_default(getattr(self.static, op), op)
 
     def set_extended_info(self, jid=None, node=None, **kwargs):
         """
@@ -76,7 +77,7 @@ class XEP_0128(BasePlugin):
                     as extended information, replacing any
                     existing extensions.
         """
-        self.disco._run_node_handler('set_extended_info', jid, node, None, kwargs)
+        self.api['set_extended_info'](jid, node, None, kwargs)
 
     def add_extended_info(self, jid=None, node=None, **kwargs):
         """
@@ -88,7 +89,7 @@ class XEP_0128(BasePlugin):
             data -- Either a form, or a list of forms to add
                     as extended information.
         """
-        self.disco._run_node_handler('add_extended_info', jid, node, None, kwargs)
+        self.api['add_extended_info'](jid, node, None, kwargs)
 
     def del_extended_info(self, jid=None, node=None, **kwargs):
         """
@@ -98,4 +99,4 @@ class XEP_0128(BasePlugin):
             jid  -- The JID to modify.
             node -- The node to modify.
         """
-        self.disco._run_node_handler('del_extended_info', jid, node, None, kwargs)
+        self.api['del_extended_info'](jid, node, None, kwargs)