From 2f4bdfee1bb4efd6bc390a4c97d27d40d88b8d3a Mon Sep 17 00:00:00 2001 From: Lance Stout Date: Mon, 13 Dec 2010 15:58:59 -0500 Subject: [PATCH] Update some docs. --- sleekxmpp/plugins/xep_0030/disco.py | 84 +++++++++++++++++----- sleekxmpp/plugins/xep_0030/stanza/disco.py | 0 sleekxmpp/plugins/xep_0030/stanza/items.py | 4 +- sleekxmpp/plugins/xep_0030/static.py | 7 +- 4 files changed, 74 insertions(+), 21 deletions(-) delete mode 100644 sleekxmpp/plugins/xep_0030/stanza/disco.py diff --git a/sleekxmpp/plugins/xep_0030/disco.py b/sleekxmpp/plugins/xep_0030/disco.py index c323ba7..c272929 100644 --- a/sleekxmpp/plugins/xep_0030/disco.py +++ b/sleekxmpp/plugins/xep_0030/disco.py @@ -26,15 +26,23 @@ class xep_0030(base_plugin): """ XEP-0030: Service Discovery + Service discovery in XMPP allows entities to discover information about + other agents in the network, such as the feature sets supported by a + client, or signposts to other, related entities. + + Also see . + Stream Handlers: - Disco Info -- - Disco Items -- + Disco Info -- Any Iq stanze that includes a query with the + namespace http://jabber.org/protocol/disco#info. + Disco Items -- Any Iq stanze that includes a query with the + namespace http://jabber.org/protocol/disco#items. Events: - disco_info -- - disco_items -- - disco_info_query -- - disco_items_query -- + disco_info -- Received a disco#info Iq query result. + disco_items -- Received a disco#items Iq query result. + disco_info_query -- Received a disco#info Iq query request. + disco_items_query -- Received a disco#items Iq query request. Methods: set_node_handler -- @@ -79,14 +87,45 @@ class xep_0030(base_plugin): 'jid': {}, 'node': {}} - def set_node_handler(self, htype, jid=None, node=None, handler=None): """ + Add a node handler for the given hierarchy level and + handler type. + + Node handlers are ordered in a hierarchy where the + most specific handler is executed. Thus, a fallback, + global handler can be used for the majority of cases + with a few node specific handler that override the + global behavior. + + Node handler hierarchy: + JID | Node | Level + --------------------- + None | None | Global + Given | None | All nodes for the JID + None | Given | Node on self.xmpp.boundjid + Given | Given | A single node + + Handler types: + get_info + get_items + set_identities + set_features + set_items + del_info + del_items + del_identity + del_feature + del_item + add_identity + add_feature + add_item + Arguments: - htype - jid - node - handler + htype -- The operation provided by the handler. + jid -- + node -- + handler -- """ if htype not in self._disco_ops: return @@ -102,10 +141,24 @@ class xep_0030(base_plugin): def del_node_handler(self, htype, jid, node): """ + Remove a handler type for a JID and node combination. + + The next handler in the hierarchy will be used if one + exists. If removing the global handler, make sure that + other handlers exist to process existing nodes. + + Node handler hierarchy: + JID | Node | Level + --------------------- + None | None | Global + Given | None | All nodes for the JID + None | Given | Node on self.xmpp.boundjid + Given | Given | A single node + Arguments: - htype - jid - node + htype -- The type of handler to remove. + 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) @@ -218,7 +271,7 @@ class xep_0030(base_plugin): htype -- The handler type to execute. jid -- The JID requested. node -- The node requested. - dat -- Optional, custom data to pass to the handler. + data -- Optional, custom data to pass to the handler. """ if jid is None: jid = self.xmpp.boundjid.full @@ -311,4 +364,3 @@ class xep_0030(base_plugin): "Using default disco#info feature.") info.add_feature(info.namespace) return info - diff --git a/sleekxmpp/plugins/xep_0030/stanza/disco.py b/sleekxmpp/plugins/xep_0030/stanza/disco.py deleted file mode 100644 index e69de29..0000000 diff --git a/sleekxmpp/plugins/xep_0030/stanza/items.py b/sleekxmpp/plugins/xep_0030/stanza/items.py index 319e666..a1fb819 100644 --- a/sleekxmpp/plugins/xep_0030/stanza/items.py +++ b/sleekxmpp/plugins/xep_0030/stanza/items.py @@ -12,8 +12,6 @@ from sleekxmpp.xmlstream import ElementBase, ET class DiscoItems(ElementBase): """ - - Example disco#items stanzas: @@ -74,7 +72,7 @@ class DiscoItems(ElementBase): Arguments: jid -- The JID for the item. - node -- Optional additional information to reference + node -- Optional additional information to reference non-addressable items. name -- Optional human readable name for the item. """ diff --git a/sleekxmpp/plugins/xep_0030/static.py b/sleekxmpp/plugins/xep_0030/static.py index f369322..e2d0331 100644 --- a/sleekxmpp/plugins/xep_0030/static.py +++ b/sleekxmpp/plugins/xep_0030/static.py @@ -35,6 +35,11 @@ class StaticDisco(object): def __init__(self, xmpp): """ + Create a static disco interface. Sets of disco#info and + disco#items are maintained for every given JID and node + combination. These stanzas are used to store disco + information in memory without any additional processing. + Arguments: xmpp -- The main SleekXMPP object. """ @@ -101,7 +106,6 @@ class StaticDisco(object): data.get('name', None), data.get('lang', None)) - def add_feature(self, jid, node, data=None): self.add_node(jid, node) self.nodes[(jid, node)]['info'].add_feature(data.get('feature', '')) @@ -124,4 +128,3 @@ class StaticDisco(object): def del_item(self, jid, node, data=None): if (jid, node) in self.nodes: self.nodes[(jid, node)]['items'].del_item(**data) -