From 95d40a3ca336a4e1b66c7ed287ec3f2ef92b201c Mon Sep 17 00:00:00 2001 From: mathieui Date: Thu, 10 Dec 2020 19:20:23 +0100 Subject: docs: update docstrings for sphinx conformity Remove most references to timeout/callback/ifrom/timeout_callbacks args --- slixmpp/clientxmpp.py | 2 +- slixmpp/plugins/xep_0030/disco.py | 349 +++++++++++++--------------- slixmpp/plugins/xep_0030/stanza/info.py | 69 +++--- slixmpp/plugins/xep_0030/stanza/items.py | 32 ++- slixmpp/plugins/xep_0045/stanza.py | 40 ++-- slixmpp/plugins/xep_0050/adhoc.py | 153 +++++------- slixmpp/plugins/xep_0050/stanza.py | 68 +++--- slixmpp/plugins/xep_0059/stanza.py | 69 +++--- slixmpp/plugins/xep_0060/pubsub.py | 153 ++++-------- slixmpp/plugins/xep_0066/oob.py | 36 +-- slixmpp/plugins/xep_0080/geoloc.py | 84 +++---- slixmpp/plugins/xep_0080/stanza.py | 36 ++- slixmpp/plugins/xep_0084/avatar.py | 8 - slixmpp/plugins/xep_0085/stanza.py | 13 +- slixmpp/plugins/xep_0086/legacy_error.py | 2 + slixmpp/plugins/xep_0086/stanza.py | 14 +- slixmpp/plugins/xep_0092/stanza.py | 27 ++- slixmpp/plugins/xep_0107/user_mood.py | 23 +- slixmpp/plugins/xep_0108/user_activity.py | 27 +-- slixmpp/plugins/xep_0118/user_tune.py | 31 +-- slixmpp/plugins/xep_0122/stanza.py | 17 +- slixmpp/plugins/xep_0128/extended_disco.py | 45 ++-- slixmpp/plugins/xep_0152/reachability.py | 38 ++- slixmpp/plugins/xep_0163.py | 54 +++-- slixmpp/plugins/xep_0172/stanza.py | 11 +- slixmpp/plugins/xep_0172/user_nick.py | 35 ++- slixmpp/plugins/xep_0196/user_gaming.py | 55 ++--- slixmpp/plugins/xep_0199/ping.py | 25 +- slixmpp/plugins/xep_0199/stanza.py | 8 +- slixmpp/plugins/xep_0202/stanza.py | 28 +-- slixmpp/plugins/xep_0202/time.py | 20 +- slixmpp/plugins/xep_0222.py | 53 ++--- slixmpp/plugins/xep_0223.py | 55 ++--- slixmpp/plugins/xep_0231/stanza.py | 4 +- slixmpp/plugins/xep_0249/invite.py | 28 +-- slixmpp/plugins/xep_0249/stanza.py | 6 + slixmpp/plugins/xep_0332/stanza/request.py | 52 +++-- slixmpp/plugins/xep_0332/stanza/response.py | 44 ++-- slixmpp/plugins/xep_0369/mix_core.py | 5 +- slixmpp/plugins/xep_0377/stanza.py | 15 +- slixmpp/plugins/xep_0421/stanza.py | 20 +- slixmpp/plugins/xep_0424/retraction.py | 5 +- slixmpp/xmlstream/tostring.py | 2 +- slixmpp/xmlstream/xmlstream.py | 3 +- 44 files changed, 799 insertions(+), 1065 deletions(-) (limited to 'slixmpp') diff --git a/slixmpp/clientxmpp.py b/slixmpp/clientxmpp.py index 1bbf5216..2b0e8536 100644 --- a/slixmpp/clientxmpp.py +++ b/slixmpp/clientxmpp.py @@ -208,7 +208,7 @@ class ClientXMPP(BaseXMPP): :param timeout: The length of time (in seconds) to wait for a response before continuing if blocking is used. Defaults to - :attr:`~slixmpp.xmlstream.xmlstream.XMLStream.response_timeout`. + :attr:`~slixmpp.xmlstream.xmlstream.XMLStream.response_timeout`. :param callback: Optional reference to a stream handler function. Will be executed when the roster is received. Implies ``block=False``. diff --git a/slixmpp/plugins/xep_0030/disco.py b/slixmpp/plugins/xep_0030/disco.py index b79a14ff..10603b81 100644 --- a/slixmpp/plugins/xep_0030/disco.py +++ b/slixmpp/plugins/xep_0030/disco.py @@ -9,6 +9,9 @@ import asyncio import logging + +from typing import Optional, Callable + from slixmpp import Iq from slixmpp import future_wrapper from slixmpp.plugins import BasePlugin @@ -41,6 +44,9 @@ class XEP_0030(BasePlugin): storage mechanism desired, such as SQLite or Redis. Node handler hierarchy: + + :: + JID | Node | Level --------------------- None | None | Global @@ -49,41 +55,29 @@ class XEP_0030(BasePlugin): Given | Given | A single node Stream Handlers: + + :: + 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 -- 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. Attributes: - stanza -- A reference to the module containing the - stanza classes provided by this plugin. - static -- Object containing the default set of - static node handlers. - default_handlers -- A dictionary mapping operations to the default - global handler (by default, the static handlers). - xmpp -- The main Slixmpp object. - - Methods: - set_node_handler -- Assign a handler to a JID/node combination. - del_node_handler -- Remove a handler from a JID/node combination. - get_info -- Retrieve disco#info data, locally or remote. - get_items -- Retrieve disco#items data, locally or remote. - set_identities -- - set_features -- - set_items -- - del_items -- - del_identity -- - del_feature -- - del_item -- - add_identity -- - add_feature -- - add_item -- + + :var static: Object containing the default set of + static node handlers. + :var default_handlers: A dictionary mapping operations to the default + global handler (by default, the static handlers). """ name = 'xep_0030' @@ -136,7 +130,9 @@ class XEP_0030(BasePlugin): 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): + def set_node_handler(self, htype: str, jid: Optional[JID] = None, + node: Optional[str] = None, + handler: Optional[Callable] = None): """ Add a node handler for the given hierarchy level and handler type. @@ -148,6 +144,9 @@ class XEP_0030(BasePlugin): global behavior. Node handler hierarchy: + + :: + JID | Node | Level --------------------- None | None | Global @@ -156,6 +155,9 @@ class XEP_0030(BasePlugin): Given | Given | A single node Handler types: + + :: + get_info get_items set_identities @@ -171,14 +173,13 @@ class XEP_0030(BasePlugin): add_feature add_item - Arguments: - htype -- The operation provided by the handler. - jid -- The JID the handler applies to. May be narrowed - further if a node is given. - node -- The particular node the handler is for. If no JID - is given, then the self.xmpp.boundjid.full is - assumed. - handler -- The handler function to use. + :param htype: The operation provided by the handler. + :param jid: The JID the handler applies to. May be narrowed + further if a node is given. + :param node: The particular node the handler is for. If no JID + is given, then the self.xmpp.boundjid.full is + assumed. + :param handler: The handler function to use. """ self.api.register(handler, htype, jid, node) @@ -191,6 +192,9 @@ class XEP_0030(BasePlugin): other handlers exist to process existing nodes. Node handler hierarchy: + + :: + JID | Node | Level --------------------- None | None | Global @@ -198,10 +202,9 @@ class XEP_0030(BasePlugin): None | Given | Node on self.xmpp.boundjid Given | Given | A single node - Arguments: - 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. + :param htype: The type of handler to remove. + :param jid: The JID from which to remove the handler. + :param node: The node from which to remove the handler. """ self.api.unregister(htype, jid, node) @@ -215,13 +218,12 @@ class XEP_0030(BasePlugin): The default is to use the built-in static handlers, but that may be changed by modifying self.default_handlers. - Arguments: - jid -- The JID owning the node to modify. - node -- The node to change to using static handlers. - handlers -- Optional list of handlers to change to the - default version. If provided, only these - handlers will be changed. Otherwise, all - handlers will use the default version. + :param jid: The JID owning the node to modify. + :param node: The node to change to using static handlers. + :param handlers: Optional list of handlers to change to the + default version. If provided, only these + handlers will be changed. Otherwise, all + handlers will use the default version. """ if handlers is None: handlers = self._disco_ops @@ -234,27 +236,25 @@ class XEP_0030(BasePlugin): Check if a JID supports a given feature. Return values: - True -- The feature is supported - False -- The feature is not listed as supported - None -- Nothing could be found due to a timeout - - Arguments: - jid -- Request info from this JID. - node -- The particular node to query. - feature -- The name of the feature to check. - local -- If true, then the query is for a JID/node - combination handled by this Slixmpp instance and - no stanzas need to be sent. - Otherwise, a disco stanza must be sent to the - remove JID to retrieve the info. - cached -- If true, then look for the disco info data from - the local cache system. If no results are found, - send the query as usual. The self.use_cache - setting must be set to true for this option to - be useful. If set to false, then the cache will - be skipped, even if a result has already been - cached. Defaults to false. - ifrom -- Specifiy the sender's JID. + :param True: The feature is supported + :param False: The feature is not listed as supported + :param None: Nothing could be found due to a timeout + + :param jid: Request info from this JID. + :param node: The particular node to query. + :param feature: The name of the feature to check. + :param local: If true, then the query is for a JID/node + combination handled by this Slixmpp instance and + no stanzas need to be sent. + Otherwise, a disco stanza must be sent to the + remove JID to retrieve the info. + :param cached: If true, then look for the disco info data from + the local cache system. If no results are found, + send the query as usual. The self.use_cache + setting must be set to true for this option to + be useful. If set to false, then the cache will + be skipped, even if a result has already been + cached. Defaults to false. """ data = {'feature': feature, 'local': local, @@ -267,29 +267,27 @@ class XEP_0030(BasePlugin): Check if a JID provides a given identity. Return values: - True -- The identity is provided - False -- The identity is not listed - None -- Nothing could be found due to a timeout - - Arguments: - jid -- Request info from this JID. - node -- The particular node to query. - category -- The category of the identity to check. - itype -- The type of the identity to check. - lang -- The language of the identity to check. - local -- If true, then the query is for a JID/node + :param True: The identity is provided + :param False: The identity is not listed + :param None: Nothing could be found due to a timeout + + :param jid: Request info from this JID. + :param node: The particular node to query. + :param category: The category of the identity to check. + :param itype: The type of the identity to check. + :param lang: The language of the identity to check. + :param local: If true, then the query is for a JID/node combination handled by this Slixmpp instance and no stanzas need to be sent. Otherwise, a disco stanza must be sent to the remove JID to retrieve the info. - cached -- If true, then look for the disco info data from + :param cached: If true, then look for the disco info data from the local cache system. If no results are found, send the query as usual. The self.use_cache setting must be set to true for this option to be useful. If set to false, then the cache will be skipped, even if a result has already been cached. Defaults to false. - ifrom -- Specifiy the sender's JID. """ data = {'category': category, 'itype': itype, @@ -343,29 +341,20 @@ class XEP_0030(BasePlugin): If requesting items from a local JID/node, then only a DiscoInfo stanza will be returned. Otherwise, an Iq stanza will be returned. - Arguments: - jid -- Request info from this JID. - node -- The particular node to query. - local -- If true, then the query is for a JID/node - combination handled by this Slixmpp instance and - no stanzas need to be sent. - Otherwise, a disco stanza must be sent to the - remote JID to retrieve the info. - cached -- If true, then look for the disco info data from - the local cache system. If no results are found, - send the query as usual. The self.use_cache - setting must be set to true for this option to - be useful. If set to false, then the cache will - be skipped, even if a result has already been - cached. Defaults to false. - ifrom -- Specifiy the sender's JID. - timeout -- The time in seconds to wait for reply, before - calling timeout_callback - callback -- Optional callback to execute when a reply is - received instead of blocking and waiting for - the reply. - timeout_callback -- Optional callback to execute when no result - has been received in timeout seconds. + :param jid: Request info from this JID. + :param node: The particular node to query. + :param local: If true, then the query is for a JID/node + combination handled by this Slixmpp instance and + no stanzas need to be sent. + Otherwise, a disco stanza must be sent to the + remote JID to retrieve the info. + :param cached: If true, then look for the disco info data from + the local cache system. If no results are found, + send the query as usual. The self.use_cache + setting must be set to true for this option to + be useful. If set to false, then the cache will + be skipped, even if a result has already been + cached. Defaults to false. """ if local is None: if jid is not None and not isinstance(jid, JID): @@ -430,25 +419,16 @@ class XEP_0030(BasePlugin): If requesting items from a local JID/node, then only a DiscoItems stanza will be returned. Otherwise, an Iq stanza will be returned. - Arguments: - jid -- Request info from this JID. - node -- The particular node to query. - local -- If true, then the query is for a JID/node - combination handled by this Slixmpp instance and - no stanzas need to be sent. - Otherwise, a disco stanza must be sent to the - remove JID to retrieve the items. - ifrom -- Specifiy the sender's JID. - timeout -- The time in seconds to block while waiting for - a reply. If None, then wait indefinitely. - callback -- Optional callback to execute when a reply is - received instead of blocking and waiting for - the reply. - iterator -- If True, return a result set iterator using - the XEP-0059 plugin, if the plugin is loaded. - Otherwise the parameter is ignored. - timeout_callback -- Optional callback to execute when no result - has been received in timeout seconds. + :param jid: Request info from this JID. + :param node: The particular node to query. + :param local: If true, then the query is for a JID/node + combination handled by this Slixmpp instance and + no stanzas need to be sent. + Otherwise, a disco stanza must be sent to the + remove JID to retrieve the items. + :param iterator: If True, return a result set iterator using + the XEP-0059 plugin, if the plugin is loaded. + Otherwise the parameter is ignored. """ if local or local is None and jid is None: items = self.api['get_items'](jid, node, @@ -477,10 +457,9 @@ class XEP_0030(BasePlugin): The given items must be in a list or set where each item is a tuple of the form: (jid, node, name). - Arguments: - jid -- The JID to modify. - node -- Optional node to modify. - items -- A series of items in tuple format. + :param jid: The JID to modify. + :param node: Optional node to modify. + :param items: A series of items in tuple format. """ self.api['set_items'](jid, node, None, kwargs) @@ -489,8 +468,8 @@ class XEP_0030(BasePlugin): Remove all items from the given JID/node combination. Arguments: - jid -- The JID to modify. - node -- Optional node to modify. + :param jid: The JID to modify. + :param node: Optional node to modify. """ self.api['del_items'](jid, node, None, kwargs) @@ -501,12 +480,11 @@ class XEP_0030(BasePlugin): Each item is required to have a JID, but may also specify a node value to reference non-addressable entities. - Arguments: - jid -- The JID for the item. - name -- Optional name for the item. - node -- The node to modify. - subnode -- Optional node for the item. - ijid -- The JID to modify. + :param jid: The JID for the item. + :param name: Optional name for the item. + :param node: The node to modify. + :param subnode: Optional node for the item. + :param ijid: The JID to modify. """ if not jid: jid = self.xmpp.boundjid.full @@ -519,11 +497,10 @@ class XEP_0030(BasePlugin): """ Remove a single item from the given JID/node combination. - Arguments: - jid -- The JID to modify. - node -- The node to modify. - ijid -- The item's JID. - inode -- The item's node. + :param jid: The JID to modify. + :param node: The node to modify. + :param ijid: The item's JID. + :param inode: The item's node. """ self.api['del_item'](jid, node, None, kwargs) @@ -540,13 +517,12 @@ class XEP_0030(BasePlugin): category/type/xml:lang pairs are allowed so long as the names are different. A category and type is always required. - Arguments: - category -- The identity's category. - itype -- The identity's type. - name -- Optional name for the identity. - lang -- Optional two-letter language code. - node -- The node to modify. - jid -- The JID to modify. + :param category: The identity's category. + :param itype: The identity's type. + :param name: Optional name for the identity. + :param lang: Optional two-letter language code. + :param node: The node to modify. + :param jid: The JID to modify. """ kwargs = {'category': category, 'itype': itype, @@ -554,29 +530,28 @@ class XEP_0030(BasePlugin): 'lang': lang} self.api['add_identity'](jid, node, None, kwargs) - def add_feature(self, feature, node=None, jid=None): + def add_feature(self, feature: str, node: Optional[str] = None, + jid: Optional[JID] = None): """ Add a feature to a JID/node combination. - Arguments: - feature -- The namespace of the supported feature. - node -- The node to modify. - jid -- The JID to modify. + :param feature: The namespace of the supported feature. + :param node: The node to modify. + :param jid: The JID to modify. """ kwargs = {'feature': feature} self.api['add_feature'](jid, node, None, kwargs) - def del_identity(self, jid=None, node=None, **kwargs): + def del_identity(self, jid: Optional[JID] = None, node: Optional[str] = None, **kwargs): """ Remove an identity from the given JID/node combination. - Arguments: - jid -- The JID to modify. - node -- The node to modify. - category -- The identity's category. - itype -- The identity's type value. - name -- Optional, human readable name for the identity. - lang -- Optional, the identity's xml:lang value. + :param jid: The JID to modify. + :param node: The node to modify. + :param category: The identity's category. + :param itype: The identity's type value. + :param name: Optional, human readable name for the identity. + :param lang: Optional, the identity's xml:lang value. """ self.api['del_identity'](jid, node, None, kwargs) @@ -584,10 +559,9 @@ class XEP_0030(BasePlugin): """ Remove a feature from a given JID/node combination. - Arguments: - jid -- The JID to modify. - node -- The node to modify. - feature -- The feature's namespace. + :param jid: The JID to modify. + :param node: The node to modify. + :param feature: The feature's namespace. """ self.api['del_feature'](jid, node, None, kwargs) @@ -598,11 +572,10 @@ class XEP_0030(BasePlugin): The identities must be in a set where each identity is a tuple of the form: (category, type, lang, name) - Arguments: - jid -- The JID to modify. - node -- The node to modify. - identities -- A set of identities in tuple form. - lang -- Optional, xml:lang value. + :param jid: The JID to modify. + :param node: The node to modify. + :param identities: A set of identities in tuple form. + :param lang: Optional, xml:lang value. """ self.api['set_identities'](jid, node, None, kwargs) @@ -613,10 +586,9 @@ class XEP_0030(BasePlugin): If a language is specified, only identities using that language will be removed. - Arguments: - jid -- The JID to modify. - node -- The node to modify. - lang -- Optional. If given, only remove identities + :param jid: The JID to modify. + :param node: The node to modify. + :param lang: Optional. If given, only remove identities using this xml:lang value. """ self.api['del_identities'](jid, node, None, kwargs) @@ -626,10 +598,9 @@ class XEP_0030(BasePlugin): Add or replace the set of supported features for a JID/node combination. - Arguments: - jid -- The JID to modify. - node -- The node to modify. - features -- The new set of supported features. + :param jid: The JID to modify. + :param node: The node to modify. + :param features: The new set of supported features. """ self.api['set_features'](jid, node, None, kwargs) @@ -637,9 +608,8 @@ class XEP_0030(BasePlugin): """ Remove all features from a JID/node combination. - Arguments: - jid -- The JID to modify. - node -- The node to modify. + :param jid: The JID to modify. + :param node: The node to modify. """ self.api['del_features'](jid, node, None, kwargs) @@ -648,11 +618,10 @@ class XEP_0030(BasePlugin): Execute the most specific node handler for the given JID/node combination. - Arguments: - htype -- The handler type to execute. - jid -- The JID requested. - node -- The node requested. - data -- Optional, custom data to pass to the handler. + :param htype: The handler type to execute. + :param jid: The JID requested. + :param node: The node requested. + :param data: Optional, custom data to pass to the handler. """ if not data: data = {} @@ -666,8 +635,7 @@ class XEP_0030(BasePlugin): and features. If it is an info result, fire the disco_info event. - Arguments: - iq -- The incoming disco#items stanza. + :param iq: The incoming disco#items stanza. """ if iq['type'] == 'get': log.debug("Received disco info query from " + \ @@ -709,8 +677,7 @@ class XEP_0030(BasePlugin): request, find and return the appropriate items. If it is an items result, fire the disco_items event. - Arguments: - iq -- The incoming disco#items stanza. + :param iq: The incoming disco#items stanza. """ if iq['type'] == 'get': log.debug("Received disco items query from " + \ @@ -739,8 +706,7 @@ class XEP_0030(BasePlugin): bot client identity. A the standard disco#info feature will also be added if no features are provided. - Arguments: - info -- The disco#info quest (not the full Iq stanza) to modify. + :param info: The disco#info quest (not the full Iq stanza) to modify. """ result = info if isinstance(info, Iq): @@ -766,11 +732,10 @@ class XEP_0030(BasePlugin): Ensure that results are wrapped in an Iq stanza if self.wrap_results has been set to True. - Arguments: - ito -- The JID to use as the 'to' value - ifrom -- The JID to use as the 'from' value - payload -- The disco data to wrap - force -- Force wrapping, regardless of self.wrap_results + :param ito: The JID to use as the 'to' value + :param ifrom: The JID to use as the 'from' value + :param payload: The disco data to wrap + :param force: Force wrapping, regardless of self.wrap_results """ if (force or self.wrap_results) and not isinstance(payload, Iq): iq = self.xmpp.Iq() diff --git a/slixmpp/plugins/xep_0030/stanza/info.py b/slixmpp/plugins/xep_0030/stanza/info.py index b23af0cc..5bb77c03 100644 --- a/slixmpp/plugins/xep_0030/stanza/info.py +++ b/slixmpp/plugins/xep_0030/stanza/info.py @@ -34,6 +34,9 @@ class DiscoInfo(ElementBase): be like section headings. Example disco#info stanzas: + + :: + @@ -48,6 +51,8 @@ class DiscoInfo(ElementBase): Stanza Interface: + :: + node -- The name of the node to either query or return info from. identities -- A set of 4-tuples, where each tuple contains @@ -55,17 +60,6 @@ class DiscoInfo(ElementBase): of an identity. features -- A set of namespaces for features. - Methods: - add_identity -- Add a new, single identity. - del_identity -- Remove a single identity. - get_identities -- Return all identities in tuple form. - set_identities -- Use multiple identities, each given in tuple form. - del_identities -- Remove all identities. - add_feature -- Add a single feature. - del_feature -- Remove a single feature. - get_features -- Return a list of all features. - set_features -- Use a given list of features. - del_features -- Remove all features. """ name = 'query' @@ -86,8 +80,7 @@ class DiscoInfo(ElementBase): Caches identity and feature information. - Arguments: - xml -- Use an existing XML object for the stanza's values. + :param xml: Use an existing XML object for the stanza's values. """ ElementBase.setup(self, xml) @@ -104,11 +97,10 @@ class DiscoInfo(ElementBase): category/type/xml:lang pairs are allowed so long as the names are different. In any case, a category and type are required. - Arguments: - category -- The general category to which the agent belongs. - itype -- A more specific designation with the category. - name -- Optional human readable name for this identity. - lang -- Optional standard xml:lang value. + :param category: The general category to which the agent belongs. + :param itype: A more specific designation with the category. + :param name: Optional human readable name for this identity. + :param lang: Optional standard xml:lang value. """ identity = (category, itype, lang) if identity not in self._identities: @@ -128,11 +120,10 @@ class DiscoInfo(ElementBase): """ Remove a given identity. - Arguments: - category -- The general category to which the agent belonged. - itype -- A more specific designation with the category. - name -- Optional human readable name for this identity. - lang -- Optional, standard xml:lang value. + :param category: The general category to which the agent belonged. + :param itype: A more specific designation with the category. + :param name: Optional human readable name for this identity. + :param lang: Optional, standard xml:lang value. """ identity = (category, itype, lang) if identity in self._identities: @@ -149,15 +140,15 @@ class DiscoInfo(ElementBase): def get_identities(self, lang=None, dedupe=True): """ Return a set of all identities in tuple form as so: + (category, type, lang, name) If a language was specified, only return identities using that language. - Arguments: - lang -- Optional, standard xml:lang value. - dedupe -- If True, de-duplicate identities, otherwise - return a list of all identities. + :param lang: Optional, standard xml:lang value. + :param dedupe: If True, de-duplicate identities, otherwise + return a list of all identities. """ if dedupe: identities = set() @@ -180,17 +171,19 @@ class DiscoInfo(ElementBase): """ Add or replace all identities. The identities must be a in set where each identity is a tuple of the form: + (category, type, lang, name) If a language is specifified, any identities using that language will be removed to be replaced with the given identities. - NOTE: An identity's language will not be changed regardless of - the value of lang. + .. note:: + + An identity's language will not be changed regardless of + the value of lang. - Arguments: - identities -- A set of identities in tuple form. - lang -- Optional, standard xml:lang value. + :param identities: A set of identities in tuple form. + :param lang: Optional, standard xml:lang value. """ self.del_identities(lang) for identity in identities: @@ -202,8 +195,7 @@ class DiscoInfo(ElementBase): Remove all identities. If a language was specified, only remove identities using that language. - Arguments: - lang -- Optional, standard xml:lang value. + :param lang: Optional, standard xml:lang value. """ for id_xml in self.xml.findall('{%s}identity' % self.namespace): if lang is None: @@ -219,8 +211,7 @@ class DiscoInfo(ElementBase): """ Add a single, new feature. - Arguments: - feature -- The namespace of the supported feature. + :param feature: The namespace of the supported feature. """ if feature not in self._features: self._features.add(feature) @@ -234,8 +225,7 @@ class DiscoInfo(ElementBase): """ Remove a single feature. - Arguments: - feature -- The namespace of the removed feature. + :param feature: The namespace of the removed feature. """ if feature in self._features: self._features.remove(feature) @@ -262,8 +252,7 @@ class DiscoInfo(ElementBase): """ Add or replace the set of supported features. - Arguments: - features -- The new set of supported features. + :param features: The new set of supported features. """ self.del_features() for feature in features: diff --git a/slixmpp/plugins/xep_0030/stanza/items.py b/slixmpp/plugins/xep_0030/stanza/items.py index b0fd0bf1..5eaf6c4b 100644 --- a/slixmpp/plugins/xep_0030/stanza/items.py +++ b/slixmpp/plugins/xep_0030/stanza/items.py @@ -13,6 +13,9 @@ class DiscoItems(ElementBase): """ Example disco#items stanzas: + + :: + @@ -29,17 +32,13 @@ class DiscoItems(ElementBase): Stanza Interface: + :: + node -- The name of the node to either query or return info from. items -- A list of 3-tuples, where each tuple contains the JID, node, and name of an item. - Methods: - add_item -- Add a single new item. - del_item -- Remove a single item. - get_items -- Return all items. - set_items -- Set or replace all items. - del_items -- Remove all items. """ name = 'query' @@ -58,8 +57,7 @@ class DiscoItems(ElementBase): Caches item information. - Arguments: - xml -- Use an existing XML object for the stanza's values. + :param xml: Use an existing XML object for the stanza's values. """ ElementBase.setup(self, xml) self._items = {item[0:2] for item in self['items']} @@ -70,11 +68,10 @@ class DiscoItems(ElementBase): JID, but may also specify a node value to reference non-addressable entitities. - Arguments: - jid -- The JID for the item. - node -- Optional additional information to reference - non-addressable items. - name -- Optional human readable name for the item. + :param jid: The JID for the item. + :param node: Optional additional information to reference + non-addressable items. + :param name: Optional human readable name for the item. """ if (jid, node) not in self._items: self._items.add((jid, node)) @@ -90,9 +87,8 @@ class DiscoItems(ElementBase): """ Remove a single item. - Arguments: - jid -- JID of the item to remove. - node -- Optional extra identifying information. + :param jid: JID of the item to remove. + :param node: Optional extra identifying information. """ if (jid, node) in self._items: for item_xml in self.xml.findall('{%s}item' % self.namespace): @@ -115,10 +111,10 @@ class DiscoItems(ElementBase): """ Set or replace all items. The given items must be in a list or set where each item is a tuple of the form: + (jid, node, name) - Arguments: - items -- A series of items in tuple format. + :param items: A series of items in tuple format. """ self.del_items() for item in items: diff --git a/slixmpp/plugins/xep_0045/stanza.py b/slixmpp/plugins/xep_0045/stanza.py index 71223f0d..64224949 100644 --- a/slixmpp/plugins/xep_0045/stanza.py +++ b/slixmpp/plugins/xep_0045/stanza.py @@ -135,15 +135,17 @@ class MUCPresence(MUCBase): ''' A MUC Presence - - - - - - + :: + + + + + + + ''' @@ -151,15 +153,17 @@ class MUCMessage(MUCBase): ''' A MUC Message - - Foo - - - - + :: + + + Foo + + + + ''' class MUCJoin(ElementBase): diff --git a/slixmpp/plugins/xep_0050/adhoc.py b/slixmpp/plugins/xep_0050/adhoc.py index 67a4ecb5..e116e4f0 100644 --- a/slixmpp/plugins/xep_0050/adhoc.py +++ b/slixmpp/plugins/xep_0050/adhoc.py @@ -50,26 +50,6 @@ class XEP_0050(BasePlugin): session IDs to dictionaries containing data relevant to a command's session. - Methods: - plugin_init -- Overrides BasePlugin.plugin_init - post_init -- Overrides BasePlugin.post_init - new_session -- Return a new session ID. - prep_handlers -- Placeholder. May call with a list of handlers - to prepare them for use with the session storage - backend, if needed. - set_backend -- Replace the default session storage with some - external storage mechanism, such as a database. - The provided backend wrapper must be able to - act using the same syntax as a dictionary. - add_command -- Add a command for use by external entitites. - get_commands -- Retrieve a list of commands provided by a - remote agent. - send_command -- Send a command request to a remote agent. - start_command -- Command user API: initiate a command session - continue_command -- Command user API: proceed to the next step - cancel_command -- Command user API: cancel a command - complete_command -- Command user API: finish a command - terminate_command -- Command user API: delete a command's session """ name = 'xep_0050' @@ -116,8 +96,7 @@ class XEP_0050(BasePlugin): The replacement backend must be able to interact through the same syntax and interfaces as a normal dictionary. - Arguments: - db -- The new session storage mechanism. + :param db: The new session storage mechanism. """ self.sessions = db @@ -127,9 +106,8 @@ class XEP_0050(BasePlugin): Intended to be replaced by the backend service as needed. - Arguments: - handlers -- A list of function pointers - **kwargs -- Any additional parameters required by the backend. + :param handlers: A list of function pointers + :param kwargs: Any additional parameters required by the backend. """ pass @@ -148,13 +126,12 @@ class XEP_0050(BasePlugin): payload items of the command. All handlers will receive the command's session data. - Arguments: - jid -- The JID that will expose the command. - node -- The node associated with the command. - name -- A human readable name for the command. - handler -- A function that will generate the response to the - initial command request, as well as enforcing any - access control policies. + :param jid: The JID that will expose the command. + :param node: The node associated with the command. + :param name: A human readable name for the command. + :param handler: A function that will generate the response to the + initial command request, as well as enforcing any + access control policies. """ if jid is None: jid = self.xmpp.boundjid @@ -212,8 +189,7 @@ class XEP_0050(BasePlugin): """ Process an initial request to execute a command. - Arguments: - iq -- The command execution request. + :param iq: The command execution request. """ sessionid = self.new_session() node = iq['command']['node'] @@ -258,8 +234,7 @@ class XEP_0050(BasePlugin): Process a request for the next step in the workflow for a command with multiple steps. - Arguments: - iq -- The command continuation request. + :param iq: The command continuation request. """ sessionid = iq['command']['sessionid'] session = self.sessions.get(sessionid) @@ -285,8 +260,7 @@ class XEP_0050(BasePlugin): Process a request for the prev step in the workflow for a command with multiple steps. - Arguments: - iq -- The command continuation request. + :param iq: The command continuation request. """ sessionid = iq['command']['sessionid'] session = self.sessions.get(sessionid) @@ -312,9 +286,8 @@ class XEP_0050(BasePlugin): Generate a command reply stanza based on the provided session data. - Arguments: - iq -- The command request stanza. - session -- A dictionary of relevant session data. + :param iq: The command request stanza. + :param session: A dictionary of relevant session data. """ sessionid = session['id'] @@ -368,8 +341,7 @@ class XEP_0050(BasePlugin): """ Process a request to cancel a command's execution. - Arguments: - iq -- The command cancellation request. + :param iq: The command cancellation request. """ node = iq['command']['node'] sessionid = iq['command']['sessionid'] @@ -399,7 +371,7 @@ class XEP_0050(BasePlugin): All data related to the command session will be removed. Arguments: - iq -- The command completion request. + :param iq: The command completion request. """ node = iq['command']['node'] sessionid = iq['command']['sessionid'] @@ -451,22 +423,15 @@ class XEP_0050(BasePlugin): """ Return a list of commands provided by a given JID. - Arguments: - jid -- The JID to query for commands. - local -- If true, then the query is for a JID/node - combination handled by this Slixmpp instance and - no stanzas need to be sent. - Otherwise, a disco stanza must be sent to the - remove JID to retrieve the items. - ifrom -- Specifiy the sender's JID. - timeout -- The time in seconds to block while waiting for - a reply. If None, then wait indefinitely. - callback -- Optional callback to execute when a reply is - received instead of blocking and waiting for - the reply. - iterator -- If True, return a result set iterator using - the XEP-0059 plugin, if the plugin is loaded. - Otherwise the parameter is ignored. + :param jid: The JID to query for commands. + :param local: If true, then the query is for a JID/node + combination handled by this Slixmpp instance and + no stanzas need to be sent. + Otherwise, a disco stanza must be sent to the + remove JID to retrieve the items. + :param iterator: If True, return a result set iterator using + the XEP-0059 plugin, if the plugin is loaded. + Otherwise the parameter is ignored. """ return self.xmpp['xep_0030'].get_items(jid=jid, node=Command.namespace, @@ -478,26 +443,18 @@ class XEP_0050(BasePlugin): Create and send a command stanza, without using the provided workflow management APIs. - Arguments: - jid -- The JID to send the command request or result. - node -- The node for the command. - ifrom -- Specify the sender's JID. - action -- May be one of: execute, cancel, complete, + :param jid: The JID to send the command request or result. + :param node: The node for the command. + :param ifrom: Specify the sender's JID. + :param action: May be one of: execute, cancel, complete, or cancel. - payload -- Either a list of payload items, or a single - payload item such as a data form. - sessionid -- The current session's ID value. - flow -- If True, process the Iq result using the - command workflow methods contained in the - session instead of returning the response - stanza itself. Defaults to False. - timeout -- The length of time (in seconds) to wait for a - response before exiting the send call - if blocking is used. Defaults to - slixmpp.xmlstream.RESPONSE_TIMEOUT - callback -- Optional reference to a stream handler - function. Will be executed when a reply - stanza is received if flow=False. + :param payload: Either a list of payload items, or a single + payload item such as a data form. + :param sessionid: The current session's ID value. + :param flow: If True, process the Iq result using the + command workflow methods contained in the + session instead of returning the response + stanza itself. Defaults to False. """ iq = self.xmpp.Iq() iq['type'] = 'set' @@ -522,15 +479,14 @@ class XEP_0050(BasePlugin): Initiate executing a command provided by a remote agent. The provided session dictionary should contain: - next -- A handler for processing the command result. - error -- A handler for processing any error stanzas - generated by the request. - Arguments: - jid -- The JID to send the command request. - node -- The node for the desired command. - session -- A dictionary of relevant session data. - ifrom -- Optionally specify the sender's JID. + :param next: A handler for processing the command result. + :param error: A handler for processing any error stanzas + generated by the request. + + :param jid: The JID to send the command request. + :param node: The node for the desired command. + :param session: A dictionary of relevant session data. """ session['jid'] = jid session['node'] = node @@ -560,9 +516,8 @@ class XEP_0050(BasePlugin): """ Execute the next action of the command. - Arguments: - session -- All stored data relevant to the current - command session. + :param session: All stored data relevant to the current + command session. """ sessionid = 'client:' + session['id'] self.sessions[sessionid] = session @@ -579,9 +534,8 @@ class XEP_0050(BasePlugin): """ Cancel the execution of a command. - Arguments: - session -- All stored data relevant to the current - command session. + :param session: All stored data relevant to the current + command session. """ sessionid = 'client:' + session['id'] self.sessions[sessionid] = session @@ -598,9 +552,8 @@ class XEP_0050(BasePlugin): """ Finish the execution of a command workflow. - Arguments: - session -- All stored data relevant to the current - command session. + :param session: All stored data relevant to the current + command session. """ sessionid = 'client:' + session['id'] self.sessions[sessionid] = session @@ -618,9 +571,8 @@ class XEP_0050(BasePlugin): Delete a command's session after a command has completed or an error has occurred. - Arguments: - session -- All stored data relevant to the current - command session. + :param session: All stored data relevant to the current + command session. """ sessionid = 'client:' + session['id'] try: @@ -635,8 +587,7 @@ class XEP_0050(BasePlugin): Will execute the 'next' handler stored in the session data, or the 'error' handler depending on the Iq's type. - Arguments: - iq -- The command response. + :param iq: The command response. """ sessionid = 'client:' + iq['command']['sessionid'] pending = False diff --git a/slixmpp/plugins/xep_0050/stanza.py b/slixmpp/plugins/xep_0050/stanza.py index ef3eac9f..9e900d48 100644 --- a/slixmpp/plugins/xep_0050/stanza.py +++ b/slixmpp/plugins/xep_0050/stanza.py @@ -22,30 +22,35 @@ class Command(ElementBase): Also see Example command stanzas: - - - - - - - - - - Information! - - - - - + + :: + + + + + + + + + + + Information! + + + + + Stanza Interface: + :: + action -- The action to perform. actions -- The set of allowable next actions. node -- The node associated with the command. @@ -53,20 +58,6 @@ class Command(ElementBase): sessionid -- A unique identifier for a command session. status -- May be one of: canceled, completed, or executing. - Attributes: - actions -- A set of allowed action values. - statuses -- A set of allowed status values. - next_actions -- A set of allowed next action names. - - Methods: - get_action -- Return the requested action. - get_actions -- Return the allowable next actions. - set_actions -- Set the allowable next actions. - del_actions -- Remove the current set of next actions. - get_notes -- Return a list of informative note data. - set_notes -- Set informative notes. - del_notes -- Remove any note data. - add_note -- Add a single note. """ name = 'command' @@ -93,9 +84,8 @@ class Command(ElementBase): """ Assign the set of allowable next actions. - Arguments: - values -- A list containing any combination of: - 'prev', 'next', and 'complete' + :param values: A list containing any combination of: + 'prev', 'next', and 'complete' """ self.del_actions() if values: diff --git a/slixmpp/plugins/xep_0059/stanza.py b/slixmpp/plugins/xep_0059/stanza.py index b74ac1e8..e1942ee4 100644 --- a/slixmpp/plugins/xep_0059/stanza.py +++ b/slixmpp/plugins/xep_0059/stanza.py @@ -18,26 +18,30 @@ class Set(ElementBase): per response or starting at certain positions. Example set stanzas: - - - - 2 - - - - - - - - - - conference.example.com - pubsub.example.com - - - + :: + + + + + 2 + + + + + + + + + + conference.example.com + pubsub.example.com + + + Stanza Interface: + :: + first_index -- The index attribute of after -- The id defining from which item to start before -- The id defining from which item to @@ -48,17 +52,6 @@ class Set(ElementBase): index -- Used to set an index to start from count -- The number of remote items available - Methods: - set_first_index -- Sets the index attribute for and - creates the element if it doesn't exist - get_first_index -- Returns the value of the index - attribute for - del_first_index -- Removes the index attribute for - but keeps the element - set_before -- Sets the value of , if the value is True - then the element will be created without a value - get_before -- Returns the value of , if it is - empty it will return True """ namespace = 'http://jabber.org/protocol/rsm' @@ -70,6 +63,10 @@ class Set(ElementBase): 'count', 'index', 'last', 'max'} def set_first_index(self, val): + """ + Sets the index attribute for and + creates the element if it doesn't exist + """ fi = self.xml.find("{%s}first" % (self.namespace)) if fi is not None: if val: @@ -82,16 +79,26 @@ class Set(ElementBase): self.xml.append(fi) def get_first_index(self): + """ + Returns the value of the index attribute for + """ fi = self.xml.find("{%s}first" % (self.namespace)) if fi is not None: return fi.attrib.get('index', '') def del_first_index(self): + """ + Removes the index attribute for but keeps the element + """ fi = self.xml.find("{%s}first" % (self.namespace)) if fi is not None: del fi.attrib['index'] def set_before(self, val): + """ + Sets the value of , if the value is True + then the element will be created without a value + """ b = self.xml.find("{%s}before" % (self.namespace)) if b is None and val is True: self._set_sub_text('{%s}before' % self.namespace, '', True) @@ -99,6 +106,10 @@ class Set(ElementBase): self._set_sub_text('{%s}before' % self.namespace, val) def get_before(self): + """ + Returns the value of , if it is + empty it will return True + """ b = self.xml.find("{%s}before" % (self.namespace)) if b is not None and not b.text: return True diff --git a/slixmpp/plugins/xep_0060/pubsub.py b/slixmpp/plugins/xep_0060/pubsub.py index adfd908c..cd069eed 100644 --- a/slixmpp/plugins/xep_0060/pubsub.py +++ b/slixmpp/plugins/xep_0060/pubsub.py @@ -144,9 +144,8 @@ class XEP_0060(BasePlugin): when the respective notifications are received from the node 'http://jabber.org/protocol/tune', among other events. - Arguments: - node -- The node name to map to an event. - event_name -- The name of the event to raise when a + :param node: The node name to map to an event. + :param event_name: The name of the event to raise when a notification from the given node is received. """ self.node_event_map[node] = event_name @@ -163,22 +162,15 @@ class XEP_0060(BasePlugin): the server's default configuration. To get the default configuration use get_node_config(). - Arguments: - jid -- The JID of the pubsub service. - node -- Optional name of the node to create. If no name is - provided, the server MAY generate a node ID for you. - The server can also assign a different name than the - one you provide; check the result stanza to see if - the server assigned a name. - config -- Optional XEP-0004 data form of configuration settings. - ntype -- The type of node to create. Servers typically default - to using 'leaf' if no type is provided. - ifrom -- Specify the sender's JID. - timeout -- The length of time (in seconds) to wait for a response - before exiting the send call if blocking is used. - Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT - callback -- Optional reference to a stream handler function. Will - be executed when a reply stanza is received. + :param jid: The JID of the pubsub service. + :param node: Optional name of the node to create. If no name is + provided, the server MAY generate a node ID for you. + The server can also assign a different name than the + one you provide; check the result stanza to see if + the server assigned a name. + :param config: Optional XEP-0004 data form of configuration settings. + :param ntype: The type of node to create. Servers typically default + to using 'leaf' if no type is provided. """ iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='set') iq['pubsub']['create']['node'] = node @@ -207,24 +199,16 @@ class XEP_0060(BasePlugin): Subscribe to updates from a pubsub node. The rules for determining the JID that is subscribing to the node are: - 1. If subscribee is given, use that as provided. - 2. If ifrom was given, use the bare or full version based on bare. - 3. Otherwise, use self.xmpp.boundjid based on bare. - - Arguments: - jid -- The pubsub service JID. - node -- The node to subscribe to. - bare -- Indicates if the subscribee is a bare or full JID. - Defaults to True for a bare JID. - subscribee -- The JID that is subscribing to the node. - options -- - ifrom -- Specify the sender's JID. - timeout -- The length of time (in seconds) to wait for a - response before exiting the send call if blocking - is used. - Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT - callback -- Optional reference to a stream handler function. Will - be executed when a reply stanza is received. + 1. If subscribee is given, use that as provided. + 2. If ifrom was given, use the bare or full version based on bare. + 3. Otherwise, use self.xmpp.boundjid based on bare. + + :param jid: The pubsub service JID. + :param node: The node to subscribe to. + :param bare: Indicates if the subscribee is a bare or full JID. + Defaults to True for a bare JID. + :param subscribee: The JID that is subscribing to the node. + :param options: """ iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='set') iq['pubsub']['subscribe']['node'] = node @@ -254,25 +238,17 @@ class XEP_0060(BasePlugin): The rules for determining the JID that is unsubscribing from the node are: - 1. If subscribee is given, use that as provided. - 2. If ifrom was given, use the bare or full version based on bare. - 3. Otherwise, use self.xmpp.boundjid based on bare. - - Arguments: - jid -- The pubsub service JID. - node -- The node to unsubscribe from. - subid -- The specific subscription, if multiple subscriptions - exist for this JID/node combination. - bare -- Indicates if the subscribee is a bare or full JID. - Defaults to True for a bare JID. - subscribee -- The JID that is unsubscribing from the node. - ifrom -- Specify the sender's JID. - timeout -- The length of time (in seconds) to wait for a - response before exiting the send call if blocking - is used. - Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT - callback -- Optional reference to a stream handler function. Will - be executed when a reply stanza is received. + 1. If subscribee is given, use that as provided. + 2. If ifrom was given, use the bare or full version based on bare. + 3. Otherwise, use self.xmpp.boundjid based on bare. + + :param jid: The pubsub service JID. + :param node: The node to unsubscribe from. + :param subid: The specific subscription, if multiple subscriptions + exist for this JID/node combination. + :param bare: Indicates if the subscribee is a bare or full JID. + Defaults to True for a bare JID. + :param subscribee: The JID that is unsubscribing from the node. """ iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='set') iq['pubsub']['unsubscribe']['node'] = node @@ -332,17 +308,10 @@ class XEP_0060(BasePlugin): Retrieve the configuration for a node, or the pubsub service's default configuration for new nodes. - Arguments: - jid -- The JID of the pubsub service. - node -- The node to retrieve the configuration for. If None, - the default configuration for new nodes will be - requested. Defaults to None. - ifrom -- Specify the sender's JID. - timeout -- The length of time (in seconds) to wait for a response - before exiting the send call if blocking is used. - Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT - callback -- Optional reference to a stream handler function. Will - be executed when a reply stanza is received. + :param jid: The JID of the pubsub service. + :param node: The node to retrieve the configuration for. If None, + the default configuration for new nodes will be + requested. Defaults to None. """ iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='get') if node is None: @@ -357,15 +326,8 @@ class XEP_0060(BasePlugin): """ Retrieve the subscriptions associated with a given node. - Arguments: - jid -- The JID of the pubsub service. - node -- The node to retrieve subscriptions from. - ifrom -- Specify the sender's JID. - timeout -- The length of time (in seconds) to wait for a response - before exiting the send call if blocking is used. - Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT - callback -- Optional reference to a stream handler function. Will - be executed when a reply stanza is received. + :param jid: The JID of the pubsub service. + :param node: The node to retrieve subscriptions from. """ iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='get') iq['pubsub_owner']['subscriptions']['node'] = node @@ -376,15 +338,8 @@ class XEP_0060(BasePlugin): """ Retrieve the affiliations associated with a given node. - Arguments: - jid -- The JID of the pubsub service. - node -- The node to retrieve affiliations from. - ifrom -- Specify the sender's JID. - timeout -- The length of time (in seconds) to wait for a response - before exiting the send call if blocking is used. - Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT - callback -- Optional reference to a stream handler function. Will - be executed when a reply stanza is received. + :param jid: The JID of the pubsub service. + :param node: The node to retrieve affiliations from. """ iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='get') iq['pubsub_owner']['affiliations']['node'] = node @@ -395,15 +350,8 @@ class XEP_0060(BasePlugin): """ Delete a a pubsub node. - Arguments: - jid -- The JID of the pubsub service. - node -- The node to delete. - ifrom -- Specify the sender's JID. - timeout -- The length of time (in seconds) to wait for a response - before exiting the send call if blocking is used. - Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT - callback -- Optional reference to a stream handler function. Will - be executed when a reply stanza is received. + :param jid: The JID of the pubsub service. + :param node: The node to delete. """ iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='set') iq['pubsub_owner']['delete']['node'] = node @@ -433,18 +381,11 @@ class XEP_0060(BasePlugin): the options as preconditions that the node's settings must match. - Arguments: - jid -- The JID of the pubsub service. - node -- The node to publish the item to. - id -- Optionally specify the ID of the item. - payload -- The item content to publish. - options -- A form of publish options. - ifrom -- Specify the sender's JID. - timeout -- The length of time (in seconds) to wait for a response - before exiting the send call if blocking is used. - Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT - callback -- Optional reference to a stream handler function. Will - be executed when a reply stanza is received. + :param jid: The JID of the pubsub service. + :param node: The node to publish the item to. + :param id: Optionally specify the ID of the item. + :param payload: The item content to publish. + :param options: A form of publish options. """ iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='set') iq['pubsub']['publish']['node'] = node diff --git a/slixmpp/plugins/xep_0066/oob.py b/slixmpp/plugins/xep_0066/oob.py index 233263a2..7f32e39c 100644 --- a/slixmpp/plugins/xep_0066/oob.py +++ b/slixmpp/plugins/xep_0066/oob.py @@ -36,10 +36,6 @@ class XEP_0066(BasePlugin): Events: oob_transfer -- Raised when a request to download a resource has been received. - - Methods: - send_oob -- Send a request to another entity to download a file - or other addressable resource. """ name = 'xep_0066' @@ -76,11 +72,10 @@ class XEP_0066(BasePlugin): Register a handler to process download requests, either for all JIDs or a single JID. - Arguments: - jid -- If None, then set the handler as a global default. - handler -- If None, then remove the existing handler for the - given JID, or reset the global handler if the JID - is None. + :param jid: If None, then set the handler as a global default. + :param handler: If None, then remove the existing handler for the + given JID, or reset the global handler if the JID + is None. """ if jid is None: if handler is not None: @@ -98,17 +93,9 @@ class XEP_0066(BasePlugin): Initiate a basic file transfer by sending the URL of a file or other resource. - Arguments: - url -- The URL of the resource to transfer. - desc -- An optional human readable description of the item - that is to be transferred. - ifrom -- Specifiy the sender's JID. - block -- If true, block and wait for the stanzas' reply. - timeout -- The time in seconds to block while waiting for - a reply. If None, then wait indefinitely. - callback -- Optional callback to execute when a reply is - received instead of blocking and waiting for - the reply. + :param url: The URL of the resource to transfer. + :param desc: An optional human readable description of the item + that is to be transferred. """ iq = self.xmpp.Iq() iq['type'] = 'set' @@ -122,8 +109,7 @@ class XEP_0066(BasePlugin): """ Execute the appropriate handler for a transfer request. - Arguments: - iq -- The Iq stanza containing the OOB transfer request. + :param iq: The Iq stanza containing the OOB transfer request. """ if iq['to'] in self.url_handlers['jid']: return self.url_handlers['jid'][iq['to']](iq) @@ -140,8 +126,7 @@ class XEP_0066(BasePlugin): Register a new handler using self.register_url_handler to screen requests and download files. - Arguments: - iq -- The Iq stanza containing the OOB transfer request. + :param iq: The Iq stanza containing the OOB transfer request. """ raise XMPPError('service-unavailable') @@ -149,8 +134,7 @@ class XEP_0066(BasePlugin): """ Handle receiving an out-of-band transfer request. - Arguments: - iq -- An Iq stanza containing an OOB transfer request. + :param iq: An Iq stanza containing an OOB transfer request. """ log.debug('Received out-of-band data request for %s from %s:' % ( iq['oob_transfer']['url'], iq['from'])) diff --git a/slixmpp/plugins/xep_0080/geoloc.py b/slixmpp/plugins/xep_0080/geoloc.py index 459d8a91..e229bf5e 100644 --- a/slixmpp/plugins/xep_0080/geoloc.py +++ b/slixmpp/plugins/xep_0080/geoloc.py @@ -39,48 +39,40 @@ class XEP_0080(BasePlugin): """ Publish the user's current location. - Arguments: - accuracy -- Horizontal GPS error in meters. - alt -- Altitude in meters above or below sea level. - area -- A named area such as a campus or neighborhood. - bearing -- GPS bearing (direction in which the entity is - heading to reach its next waypoint), measured in - decimal degrees relative to true north. - building -- A specific building on a street or in an area. - country -- The nation where the user is located. - countrycode -- The ISO 3166 two-letter country code. - datum -- GPS datum. - description -- A natural-language name for or description of - the location. - error -- Horizontal GPS error in arc minutes. Obsoleted by - the accuracy parameter. - floor -- A particular floor in a building. - lat -- Latitude in decimal degrees North. - locality -- A locality within the administrative region, such - as a town or city. - lon -- Longitude in decimal degrees East. - postalcode -- A code used for postal delivery. - region -- An administrative region of the nation, such - as a state or province. - room -- A particular room in a building. - speed -- The speed at which the entity is moving, - in meters per second. - street -- A thoroughfare within the locality, or a crossing - of two thoroughfares. - text -- A catch-all element that captures any other - information about the location. - timestamp -- UTC timestamp specifying the moment when the - reading was taken. - uri -- A URI or URL pointing to information about - the location. - - options -- Optional form of publish options. - ifrom -- Specify the sender's JID. - timeout -- The length of time (in seconds) to wait for a response - before exiting the send call if blocking is used. - Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT - callback -- Optional reference to a stream handler function. Will - be executed when a reply stanza is received. + :param accuracy: Horizontal GPS error in meters. + :param alt: Altitude in meters above or below sea level. + :param area: A named area such as a campus or neighborhood. + :param bearing: GPS bearing (direction in which the entity is + heading to reach its next waypoint), measured in + decimal degrees relative to true north. + :param building: A specific building on a street or in an area. + :param country: The nation where the user is located. + :param countrycode: The ISO 3166 two-letter country code. + :param datum: GPS datum. + :param description: A natural-language name for or description of + the location. + :param error: Horizontal GPS error in arc minutes. Obsoleted by + the accuracy parameter. + :param floor: A particular floor in a building. + :param lat: Latitude in decimal degrees North. + :param locality: A locality within the administrative region, such + as a town or city. + :param lon: Longitude in decimal degrees East. + :param postalcode: A code used for postal delivery. + :param region: An administrative region of the nation, such + as a state or province. + :param room: A particular room in a building. + :param speed: The speed at which the entity is moving, + in meters per second. + :param street: A thoroughfare within the locality, or a crossing + of two thoroughfares. + :param text: A catch-all element that captures any other + information about the location. + :param timestamp: UTC timestamp specifying the moment when the + reading was taken. + :param uri: A URI or URL pointing to information about + the location. + :param options: Optional form of publish options. """ options = kwargs.get('options', None) ifrom = kwargs.get('ifrom', None) @@ -104,14 +96,6 @@ class XEP_0080(BasePlugin): def stop(self, ifrom=None, callback=None, timeout=None, timeout_callback=None): """ Clear existing user location information to stop notifications. - - Arguments: - ifrom -- Specify the sender's JID. - timeout -- The length of time (in seconds) to wait for a response - before exiting the send call if blocking is used. - Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT - callback -- Optional reference to a stream handler function. Will - be executed when a reply stanza is received. """ geoloc = Geoloc() return self.xmpp['xep_0163'].publish(geoloc, diff --git a/slixmpp/plugins/xep_0080/stanza.py b/slixmpp/plugins/xep_0080/stanza.py index adad6321..c63803bd 100644 --- a/slixmpp/plugins/xep_0080/stanza.py +++ b/slixmpp/plugins/xep_0080/stanza.py @@ -17,6 +17,9 @@ class Geoloc(ElementBase): geographical or physical location of an entity. (XEP-0080: User Location) Example stanzas: + + :: + @@ -28,6 +31,8 @@ class Geoloc(ElementBase): Stanza Interface: + :: + accuracy -- Horizontal GPS error in meters. alt -- Altitude in meters above or below sea level. area -- A named area such as a campus or neighborhood. @@ -61,6 +66,7 @@ class Geoloc(ElementBase): reading was taken. uri -- A URI or URL pointing to information about the location. + """ namespace = 'http://jabber.org/protocol/geoloc' @@ -83,8 +89,7 @@ class Geoloc(ElementBase): """ Set the value of the element. - Arguments: - accuracy -- Horizontal GPS error in meters + :param accuracy: Horizontal GPS error in meters """ self._set_sub_text('accuracy', text=str(accuracy)) return self @@ -106,8 +111,7 @@ class Geoloc(ElementBase): """ Set the value of the element. - Arguments: - alt -- Altitude in meters above or below sea level + :param alt: Altitude in meters above or below sea level """ self._set_sub_text('alt', text=str(alt)) return self @@ -129,8 +133,7 @@ class Geoloc(ElementBase): """ Set the value of the element. - Arguments: - bearing -- GPS bearing (direction in which the entity is heading + :param bearing: GPS bearing (direction in which the entity is heading to reach its next waypoint), measured in decimal degrees relative to true north """ @@ -154,9 +157,8 @@ class Geoloc(ElementBase): """ Set the value of the element. - Arguments: - error -- Horizontal GPS error in arc minutes; this - element is deprecated in favor of + :param error: Horizontal GPS error in arc minutes; this + element is deprecated in favor of """ self._set_sub_text('error', text=str(error)) return self @@ -178,8 +180,7 @@ class Geoloc(ElementBase): """ Set the value of the element. - Arguments: - lat -- Latitude in decimal degrees North + :param lat: Latitude in decimal degrees North """ self._set_sub_text('lat', text=str(lat)) return self @@ -201,8 +202,7 @@ class Geoloc(ElementBase): """ Set the value of the element. - Arguments: - lon -- Longitude in decimal degrees East + :param lon: Longitude in decimal degrees East """ self._set_sub_text('lon', text=str(lon)) return self @@ -224,9 +224,8 @@ class Geoloc(ElementBase): """ Set the value of the element. - Arguments: - speed -- The speed at which the entity is moving, - in meters per second + :param speed: The speed at which the entity is moving, + in meters per second """ self._set_sub_text('speed', text=str(speed)) return self @@ -248,9 +247,8 @@ class Geoloc(ElementBase): """ Set the value of the element. - Arguments: - timestamp -- UTC timestamp specifying the moment when - the reading was taken + :param timestamp: UTC timestamp specifying the moment when + the reading was taken """ self._set_sub_text('timestamp', text=str(xep_0082.datetime(timestamp))) return self diff --git a/slixmpp/plugins/xep_0084/avatar.py b/slixmpp/plugins/xep_0084/avatar.py index 6ab4d24b..e434d39c 100644 --- a/slixmpp/plugins/xep_0084/avatar.py +++ b/slixmpp/plugins/xep_0084/avatar.py @@ -92,14 +92,6 @@ class XEP_0084(BasePlugin): def stop(self, ifrom=None, callback=None, timeout=None, timeout_callback=None): """ Clear existing avatar metadata information to stop notifications. - - Arguments: - ifrom -- Specify the sender's JID. - timeout -- The length of time (in seconds) to wait for a response - before exiting the send call if blocking is used. - Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT - callback -- Optional reference to a stream handler function. Will - be executed when a reply stanza is received. """ metadata = MetaData() return self.xmpp['xep_0163'].publish(metadata, diff --git a/slixmpp/plugins/xep_0085/stanza.py b/slixmpp/plugins/xep_0085/stanza.py index d0987308..d0937c06 100644 --- a/slixmpp/plugins/xep_0085/stanza.py +++ b/slixmpp/plugins/xep_0085/stanza.py @@ -14,6 +14,9 @@ class ChatState(ElementBase): """ Example chat state stanzas: + + :: + @@ -22,16 +25,6 @@ class ChatState(ElementBase): - Stanza Interfaces: - chat_state - - Attributes: - states - - Methods: - get_chat_state - set_chat_state - del_chat_state """ name = '' diff --git a/slixmpp/plugins/xep_0086/legacy_error.py b/slixmpp/plugins/xep_0086/legacy_error.py index 0a6e0e87..e2ad41db 100644 --- a/slixmpp/plugins/xep_0086/legacy_error.py +++ b/slixmpp/plugins/xep_0086/legacy_error.py @@ -26,6 +26,8 @@ class XEP_0086(BasePlugin): Also see . Configuration Values: + :: + override -- Indicates if applying legacy error codes should be done automatically. Defaults to True. If False, then inserting legacy error codes can diff --git a/slixmpp/plugins/xep_0086/stanza.py b/slixmpp/plugins/xep_0086/stanza.py index a28abafa..6043308b 100644 --- a/slixmpp/plugins/xep_0086/stanza.py +++ b/slixmpp/plugins/xep_0086/stanza.py @@ -22,6 +22,8 @@ class LegacyError(ElementBase): Also see . Example legacy error stanzas: + :: + @@ -32,13 +34,8 @@ class LegacyError(ElementBase): xmlns="urn:ietf:params:xml:ns:xmpp-stanzas" /> - Attributes: - error_map -- A map of error conditions to error types and - code values. - Methods: - setup -- Overrides ElementBase.setup - set_condition -- Remap the type and code interfaces when a - condition is set. + :var error_map: A map of error conditions to error types and + code values. """ name = 'legacy' @@ -79,8 +76,7 @@ class LegacyError(ElementBase): Set the error type and code based on the given error condition value. - Arguments: - value -- The new error condition. + :param value: The new error condition. """ self.parent().set_condition(value) diff --git a/slixmpp/plugins/xep_0092/stanza.py b/slixmpp/plugins/xep_0092/stanza.py index e76a041e..f7dc9e69 100644 --- a/slixmpp/plugins/xep_0092/stanza.py +++ b/slixmpp/plugins/xep_0092/stanza.py @@ -17,19 +17,24 @@ class Version(ElementBase): that the agent is running on. Example version stanzas: - - - - - - - Slixmpp - 1.0 - Linux - - + :: + + + + + + + + Slixmpp + 1.0 + Linux + + Stanza Interface: + + :: + name -- The human readable name of the software. version -- The specific version of the software. os -- The name of the operating system running the program. diff --git a/slixmpp/plugins/xep_0107/user_mood.py b/slixmpp/plugins/xep_0107/user_mood.py index c745671f..83155f92 100644 --- a/slixmpp/plugins/xep_0107/user_mood.py +++ b/slixmpp/plugins/xep_0107/user_mood.py @@ -45,17 +45,10 @@ class XEP_0107(BasePlugin): """ Publish the user's current mood. - Arguments: - value -- The name of the mood to publish. - text -- Optional natural-language description or reason - for the mood. - options -- Optional form of publish options. - ifrom -- Specify the sender's JID. - timeout -- The length of time (in seconds) to wait for a response - before exiting the send call if blocking is used. - Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT - callback -- Optional reference to a stream handler function. Will - be executed when a reply stanza is received. + :param value: The name of the mood to publish. + :param text: Optional natural-language description or reason + for the mood. + :param options: Optional form of publish options. """ mood = UserMood() mood['value'] = value @@ -69,14 +62,6 @@ class XEP_0107(BasePlugin): timeout_callback=None): """ Clear existing user mood information to stop notifications. - - Arguments: - ifrom -- Specify the sender's JID. - timeout -- The length of time (in seconds) to wait for a response - before exiting the send call if blocking is used. - Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT - callback -- Optional reference to a stream handler function. Will - be executed when a reply stanza is received. """ mood = UserMood() self.xmpp['xep_0163'].publish(mood, node=UserMood.namespace, diff --git a/slixmpp/plugins/xep_0108/user_activity.py b/slixmpp/plugins/xep_0108/user_activity.py index d66ed9c4..089269bd 100644 --- a/slixmpp/plugins/xep_0108/user_activity.py +++ b/slixmpp/plugins/xep_0108/user_activity.py @@ -39,19 +39,12 @@ class XEP_0108(BasePlugin): """ Publish the user's current activity. - Arguments: - general -- The required general category of the activity. - specific -- Optional specific activity being done as part - of the general category. - text -- Optional natural-language description or reason - for the activity. - options -- Optional form of publish options. - ifrom -- Specify the sender's JID. - timeout -- The length of time (in seconds) to wait for a response - before exiting the send call if blocking is used. - Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT - callback -- Optional reference to a stream handler function. Will - be executed when a reply stanza is received. + :param general: The required general category of the activity. + :param specific: Optional specific activity being done as part + of the general category. + :param text: Optional natural-language description or reason + for the activity. + :param options: Optional form of publish options. """ activity = UserActivity() activity['value'] = (general, specific) @@ -66,14 +59,6 @@ class XEP_0108(BasePlugin): timeout_callback=None): """ Clear existing user activity information to stop notifications. - - Arguments: - ifrom -- Specify the sender's JID. - timeout -- The length of time (in seconds) to wait for a response - before exiting the send call if blocking is used. - Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT - callback -- Optional reference to a stream handler function. Will - be executed when a reply stanza is received. """ activity = UserActivity() self.xmpp['xep_0163'].publish(activity, node=UserActivity.namespace, diff --git a/slixmpp/plugins/xep_0118/user_tune.py b/slixmpp/plugins/xep_0118/user_tune.py index 8b64eaf7..4145dce6 100644 --- a/slixmpp/plugins/xep_0118/user_tune.py +++ b/slixmpp/plugins/xep_0118/user_tune.py @@ -39,21 +39,14 @@ class XEP_0118(BasePlugin): """ Publish the user's current tune. - Arguments: - artist -- The artist or performer of the song. - length -- The length of the song in seconds. - rating -- The user's rating of the song (from 1 to 10) - source -- The album name, website, or other source of the song. - title -- The title of the song. - track -- The song's track number, or other unique identifier. - uri -- A URL to more information about the song. - options -- Optional form of publish options. - ifrom -- Specify the sender's JID. - timeout -- The length of time (in seconds) to wait for a response - before exiting the send call if blocking is used. - Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT - callback -- Optional reference to a stream handler function. Will - be executed when a reply stanza is received. + :param artist: The artist or performer of the song. + :param length: The length of the song in seconds. + :param rating: The user's rating of the song (from 1 to 10) + :param source: The album name, website, or other source of the song. + :param title: The title of the song. + :param track: The song's track number, or other unique identifier. + :param uri: A URL to more information about the song. + :param options: Optional form of publish options. """ tune = UserTune() tune['artist'] = artist @@ -74,14 +67,6 @@ class XEP_0118(BasePlugin): def stop(self, ifrom=None, callback=None, timeout=None, timeout_callback=None): """ Clear existing user tune information to stop notifications. - - Arguments: - ifrom -- Specify the sender's JID. - timeout -- The length of time (in seconds) to wait for a response - before exiting the send call if blocking is used. - Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT - callback -- Optional reference to a stream handler function. Will - be executed when a reply stanza is received. """ tune = UserTune() return self.xmpp['xep_0163'].publish(tune, diff --git a/slixmpp/plugins/xep_0122/stanza.py b/slixmpp/plugins/xep_0122/stanza.py index 9f1c423d..e038a558 100644 --- a/slixmpp/plugins/xep_0122/stanza.py +++ b/slixmpp/plugins/xep_0122/stanza.py @@ -7,15 +7,18 @@ class FormValidation(ElementBase): Example: - - - 2003-10-06T11:22:00-07:00 - + :: + + + + 2003-10-06T11:22:00-07:00 + Questions: - Should this look at the datatype value and convert the range values as appropriate? - Should this stanza provide a pass/fail for a value from the field, or convert field value to datatype? + + * Should this look at the datatype value and convert the range values as appropriate? + * Should this stanza provide a pass/fail for a value from the field, or convert field value to datatype? """ namespace = 'http://jabber.org/protocol/xdata-validate' diff --git a/slixmpp/plugins/xep_0128/extended_disco.py b/slixmpp/plugins/xep_0128/extended_disco.py index bf3971e3..ae4f149a 100644 --- a/slixmpp/plugins/xep_0128/extended_disco.py +++ b/slixmpp/plugins/xep_0128/extended_disco.py @@ -8,8 +8,10 @@ import logging +from typing import Optional + import slixmpp -from slixmpp import Iq +from slixmpp import Iq, JID from slixmpp.xmlstream import register_stanza_plugin from slixmpp.plugins import BasePlugin from slixmpp.plugins.xep_0004 import Form @@ -27,16 +29,9 @@ class XEP_0128(BasePlugin): Also see . - Attributes: - disco -- A reference to the XEP-0030 plugin. - static -- Object containing the default set of static - node handlers. - xmpp -- The main Slixmpp object. - - Methods: - set_extended_info -- Set extensions to a disco#info result. - add_extended_info -- Add an extension to a disco#info result. - del_extended_info -- Remove all extensions from a disco#info result. + :var disco: A reference to the XEP-0030 plugin. + :var static: Object containing the default set of static + node handlers. """ name = 'xep_0128' @@ -67,12 +62,11 @@ class XEP_0128(BasePlugin): Replaces any existing extended information. - Arguments: - jid -- The JID to modify. - node -- The node to modify. - data -- Either a form, or a list of forms to use - as extended information, replacing any - existing extensions. + :param jid: The JID to modify. + :param node: The node to modify. + :param data: Either a form, or a list of forms to use + as extended information, replacing any + existing extensions. """ self.api['set_extended_info'](jid, node, None, kwargs) @@ -80,20 +74,19 @@ class XEP_0128(BasePlugin): """ Add additional, extended identity information to a node. - Arguments: - jid -- The JID to modify. - node -- The node to modify. - data -- Either a form, or a list of forms to add - as extended information. + :param jid: The JID to modify. + :param node: The node to modify. + :param data: Either a form, or a list of forms to add + as extended information. """ self.api['add_extended_info'](jid, node, None, kwargs) - def del_extended_info(self, jid=None, node=None, **kwargs): + def del_extended_info(self, jid: Optional[JID] = None, + node: Optional[str] = None, **kwargs): """ Remove all extended identity information to a node. - Arguments: - jid -- The JID to modify. - node -- The node to modify. + :param jid: The JID to modify. + :param node: The node to modify. """ self.api['del_extended_info'](jid, node, None, kwargs) diff --git a/slixmpp/plugins/xep_0152/reachability.py b/slixmpp/plugins/xep_0152/reachability.py index 3ff5e118..0ca0ae68 100644 --- a/slixmpp/plugins/xep_0152/reachability.py +++ b/slixmpp/plugins/xep_0152/reachability.py @@ -8,8 +8,11 @@ import logging +from slixmpp import JID +from typing import Dict, List, Optional, Callable from slixmpp.plugins.base import BasePlugin from slixmpp.plugins.xep_0152 import stanza, Reachability +from slixmpp.plugins.xep_0004 import Form log = logging.getLogger(__name__) @@ -33,22 +36,18 @@ class XEP_0152(BasePlugin): def session_bind(self, jid): self.xmpp['xep_0163'].register_pep('reachability', Reachability) - def publish_reachability(self, addresses, options=None, ifrom=None, - callback=None, timeout=None, - timeout_callback=None): + def publish_reachability(self, addresses: List[Dict[str, str]], + options: Optional[Form] = None, + ifrom: Optional[JID] = None, + callback: Optional[Callable] = None, + timeout: Optional[int] = None, + timeout_callback: Optional[Callable] = None): """ Publish alternative addresses where the user can be reached. - Arguments: - addresses -- A list of dictionaries containing the URI and - optional description for each address. - options -- Optional form of publish options. - ifrom -- Specify the sender's JID. - timeout -- The length of time (in seconds) to wait for a response - before exiting the send call if blocking is used. - Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT - callback -- Optional reference to a stream handler function. Will - be executed when a reply stanza is received. + :param addresses: A list of dictionaries containing the URI and + optional description for each address. + :param options: Optional form of publish options. """ if not isinstance(addresses, (list, tuple)): addresses = [addresses] @@ -69,17 +68,12 @@ class XEP_0152(BasePlugin): timeout=timeout, timeout_callback=timeout_callback) - def stop(self, ifrom=None, callback=None, timeout=None, timeout_callback=None): + def stop(self, ifrom: Optional[JID] = None, + callback: Optional[Callable] = None, + timeout: Optional[int] = None, + timeout_callback: Optional[Callable] = None): """ Clear existing user activity information to stop notifications. - - Arguments: - ifrom -- Specify the sender's JID. - timeout -- The length of time (in seconds) to wait for a response - before exiting the send call if blocking is used. - Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT - callback -- Optional reference to a stream handler function. Will - be executed when a reply stanza is received. """ reach = Reachability() return self.xmpp['xep_0163'].publish(reach, diff --git a/slixmpp/plugins/xep_0163.py b/slixmpp/plugins/xep_0163.py index 4c302efa..0b146bcb 100644 --- a/slixmpp/plugins/xep_0163.py +++ b/slixmpp/plugins/xep_0163.py @@ -8,9 +8,11 @@ import logging -from slixmpp import asyncio -from slixmpp.xmlstream import register_stanza_plugin +from typing import Optional, Callable +from slixmpp import asyncio, JID +from slixmpp.xmlstream import register_stanza_plugin, ElementBase from slixmpp.plugins.base import BasePlugin, register_plugin +from slixmpp.plugins.xep_0004.stanza import Form log = logging.getLogger(__name__) @@ -45,16 +47,15 @@ class XEP_0163(BasePlugin): self.xmpp['xep_0030'].add_feature(stanza.namespace) self.xmpp['xep_0060'].map_node_event(stanza.namespace, name) - def add_interest(self, namespace, jid=None): + def add_interest(self, namespace: str, jid: Optional[JID] = None): """ Mark an interest in a PEP subscription by including a disco feature with the '+notify' extension. - Arguments: - namespace -- The base namespace to register as an interest, such - as 'http://jabber.org/protocol/tune'. This may also - be a list of such namespaces. - jid -- Optionally specify the JID. + :param namespace: The base namespace to register as an interest, such + as 'http://jabber.org/protocol/tune'. This may also + be a list of such namespaces. + :param jid: Optionally specify the JID. """ if not isinstance(namespace, set) and not isinstance(namespace, list): namespace = [namespace] @@ -67,16 +68,15 @@ class XEP_0163(BasePlugin): loop=self.xmpp.loop, ) - def remove_interest(self, namespace, jid=None): + def remove_interest(self, namespace: str, jid: Optional[JID] = None): """ Mark an interest in a PEP subscription by including a disco feature with the '+notify' extension. - Arguments: - namespace -- The base namespace to remove as an interest, such - as 'http://jabber.org/protocol/tune'. This may also - be a list of such namespaces. - jid -- Optionally specify the JID. + :param namespace: The base namespace to remove as an interest, such + as 'http://jabber.org/protocol/tune'. This may also + be a list of such namespaces. + :param jid: Optionally specify the JID. """ if not isinstance(namespace, (set, list)): namespace = [namespace] @@ -89,26 +89,24 @@ class XEP_0163(BasePlugin): loop=self.xmpp.loop, ) - def publish(self, stanza, node=None, id=None, options=None, ifrom=None, - timeout_callback=None, callback=None, timeout=None): + def publish(self, stanza: ElementBase, node: Optional[str] = None, + id: Optional[str] = None, + options: Optional[Form] = None, + ifrom: Optional[JID] = None, + timeout_callback: Optional[Callable] = None, + callback: Optional[Callable] = None, + timeout: Optional[int] = None): """ Publish a PEP update. This is just a (very) thin wrapper around the XEP-0060 publish() method to set the defaults expected by PEP. - Arguments: - stanza -- The PEP update stanza to publish. - node -- The node to publish the item to. If not specified, - the stanza's namespace will be used. - id -- Optionally specify the ID of the item. - options -- A form of publish options. - ifrom -- Specify the sender's JID. - timeout -- The length of time (in seconds) to wait for a response - before exiting the send call if blocking is used. - Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT - callback -- Optional reference to a stream handler function. Will - be executed when a reply stanza is received. + :param stanza: The PEP update stanza to publish. + :param node: The node to publish the item to. If not specified, + the stanza's namespace will be used. + :param id: Optionally specify the ID of the item. + :param options: A form of publish options. """ if node is None: node = stanza.namespace diff --git a/slixmpp/plugins/xep_0172/stanza.py b/slixmpp/plugins/xep_0172/stanza.py index c85137ab..addba94a 100644 --- a/slixmpp/plugins/xep_0172/stanza.py +++ b/slixmpp/plugins/xep_0172/stanza.py @@ -24,6 +24,9 @@ class UserNick(ElementBase): the same as the nickname used in a MUC. Example stanzas: + + :: + The User ... @@ -34,13 +37,11 @@ class UserNick(ElementBase): Stanza Interface: + + :: + nick -- A global, friendly or informal name chosen by a user. - Methods: - setup -- Overrides ElementBase.setup. - get_nick -- Return the nickname in the element. - set_nick -- Add a element with the given nickname. - del_nick -- Remove the element. """ namespace = 'http://jabber.org/protocol/nick' diff --git a/slixmpp/plugins/xep_0172/user_nick.py b/slixmpp/plugins/xep_0172/user_nick.py index 0bba8611..ef96c51a 100644 --- a/slixmpp/plugins/xep_0172/user_nick.py +++ b/slixmpp/plugins/xep_0172/user_nick.py @@ -8,6 +8,8 @@ import logging +from typing import Optional, Callable +from slixmpp import JID from slixmpp.stanza.message import Message from slixmpp.stanza.presence import Presence from slixmpp.xmlstream import register_stanza_plugin @@ -15,6 +17,7 @@ from slixmpp.xmlstream.handler import Callback from slixmpp.xmlstream.matcher import MatchXPath from slixmpp.plugins.base import BasePlugin from slixmpp.plugins.xep_0172 import stanza, UserNick +from slixmpp.plugins.xep_0004.stanza import Form log = logging.getLogger(__name__) @@ -42,20 +45,17 @@ class XEP_0172(BasePlugin): def session_bind(self, jid): self.xmpp['xep_0163'].register_pep('user_nick', UserNick) - def publish_nick(self, nick=None, options=None, ifrom=None, timeout_callback=None, - callback=None, timeout=None): + def publish_nick(self, nick: Optional[str] = None, + options: Optional[Form] = None, + ifrom: Optional[JID] = None, + timeout_callback: Optional[Callable] = None, + callback: Optional[Callable] = None, + timeout: Optional[int] = None): """ Publish the user's current nick. - Arguments: - nick -- The user nickname to publish. - options -- Optional form of publish options. - ifrom -- Specify the sender's JID. - timeout -- The length of time (in seconds) to wait for a response - before exiting the send call if blocking is used. - Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT - callback -- Optional reference to a stream handler function. Will - be executed when a reply stanza is received. + :param nick: The user nickname to publish. + :param options: Optional form of publish options. """ nickname = UserNick() nickname['nick'] = nick @@ -64,17 +64,12 @@ class XEP_0172(BasePlugin): callback=callback, timeout=timeout, timeout_callback=timeout_callback) - def stop(self, ifrom=None, timeout_callback=None, callback=None, timeout=None): + def stop(self, ifrom: Optional[JID] = None, + timeout_callback: Optional[Callable] = None, + callback: Optional[Callable] = None, + timeout: Optional[int] = None): """ Clear existing user nick information to stop notifications. - - Arguments: - ifrom -- Specify the sender's JID. - timeout -- The length of time (in seconds) to wait for a response - before exiting the send call if blocking is used. - Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT - callback -- Optional reference to a stream handler function. Will - be executed when a reply stanza is received. """ nick = UserNick() return self.xmpp['xep_0163'].publish(nick, node=UserNick.namespace, diff --git a/slixmpp/plugins/xep_0196/user_gaming.py b/slixmpp/plugins/xep_0196/user_gaming.py index 5a573ea9..623410a1 100644 --- a/slixmpp/plugins/xep_0196/user_gaming.py +++ b/slixmpp/plugins/xep_0196/user_gaming.py @@ -8,8 +8,11 @@ import logging +from slixmpp import JID +from typing import Optional, Callable from slixmpp.plugins.base import BasePlugin from slixmpp.plugins.xep_0196 import stanza, UserGaming +from slixmpp.plugins.xep_0004.stanza import Form log = logging.getLogger(__name__) @@ -33,30 +36,30 @@ class XEP_0196(BasePlugin): def session_bind(self, jid): self.xmpp['xep_0163'].register_pep('user_gaming', UserGaming) - def publish_gaming(self, name=None, level=None, server_name=None, - uri=None, character_name=None, - character_profile=None, server_address=None, - options=None, ifrom=None, callback=None, - timeout=None, timeout_callback=None): + def publish_gaming(self, name: Optional[str] = None, + level: Optional[str] = None, + server_name: Optional[str] = None, + uri: Optional[str] = None, + character_name: Optional[str] = None, + character_profile: Optional[str] = None, + server_address: Optional[str] = None, + options: Optional[Form] = None, + ifrom: Optional[JID] = None, + callback: Optional[Callable] = None, + timeout: Optional[int] = None, + timeout_callback: Optional[Callable]=None): """ Publish the user's current gaming status. - Arguments: - name -- The name of the game. - level -- The user's level in the game. - uri -- A URI for the game or relevant gaming service - server_name -- The name of the server where the user is playing. - server_address -- The hostname or IP address of the server where the - user is playing. - character_name -- The name of the user's character in the game. - character_profile -- A URI for a profile of the user's character. - options -- Optional form of publish options. - ifrom -- Specify the sender's JID. - timeout -- The length of time (in seconds) to wait for a response - before exiting the send call if blocking is used. - Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT - callback -- Optional reference to a stream handler function. Will - be executed when a reply stanza is received. + :param name: The name of the game. + :param level: The user's level in the game. + :param uri: A URI for the game or relevant gaming service + :param server_name: The name of the server where the user is playing. + :param server_address: The hostname or IP address of the server where the + user is playing. + :param character_name: The name of the user's character in the game. + :param character_profile: A URI for a profile of the user's character. + :param options: Optional form of publish options. """ gaming = UserGaming() gaming['name'] = name @@ -73,17 +76,9 @@ class XEP_0196(BasePlugin): timeout_callback=timeout_callback) def stop(self, ifrom=None, callback=None, timeout=None, - timeout_callback=None): + timeout_callback=None): """ Clear existing user gaming information to stop notifications. - - Arguments: - ifrom -- Specify the sender's JID. - timeout -- The length of time (in seconds) to wait for a response - before exiting the send call if blocking is used. - Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT - callback -- Optional reference to a stream handler function. Will - be executed when a reply stanza is received. """ gaming = UserGaming() return self.xmpp['xep_0163'].publish(gaming, diff --git a/slixmpp/plugins/xep_0199/ping.py b/slixmpp/plugins/xep_0199/ping.py index adbf2203..d1a82026 100644 --- a/slixmpp/plugins/xep_0199/ping.py +++ b/slixmpp/plugins/xep_0199/ping.py @@ -9,6 +9,8 @@ import time import logging +from typing import Optional, Callable + from slixmpp.jid import JID from slixmpp.stanza import Iq from slixmpp import asyncio @@ -123,17 +125,13 @@ class XEP_0199(BasePlugin): log.debug("Pinged by %s", iq['from']) iq.reply().send() - def send_ping(self, jid, ifrom=None, timeout=None, callback=None, - timeout_callback=None): + def send_ping(self, jid: JID, ifrom: Optional[JID] = None, + timeout: Optional[int] = None, + callback: Optional[Callable] = None, + timeout_callback: Optional[Callable] = None): """Send a ping request. - Arguments: - jid -- The JID that will receive the ping. - ifrom -- Specifiy the sender JID. - timeout -- Time in seconds to wait for a response. - Defaults to self.timeout. - callback -- Optional handler to execute when a pong - is received. + :param jid: The JID that will receive the ping. """ if not timeout: timeout = self.timeout @@ -147,15 +145,12 @@ class XEP_0199(BasePlugin): return iq.send(timeout=timeout, callback=callback, timeout_callback=timeout_callback) - async def ping(self, jid=None, ifrom=None, timeout=None): + async def ping(self, jid: Optional[JID] =None, + ifrom: Optional[JID] = None, timeout: Optional[int] = None) -> float: """Send a ping request and calculate RTT. This is a coroutine. - Arguments: - jid -- The JID that will receive the ping. - ifrom -- Specifiy the sender JID. - timeout -- Time in seconds to wait for a response. - Defaults to self.timeout. + :param jid: The JID that will receive the ping. """ own_host = False if not jid: diff --git a/slixmpp/plugins/xep_0199/stanza.py b/slixmpp/plugins/xep_0199/stanza.py index 425e891b..6795cb15 100644 --- a/slixmpp/plugins/xep_0199/stanza.py +++ b/slixmpp/plugins/xep_0199/stanza.py @@ -19,15 +19,11 @@ class Ping(ElementBase): keepalive methods for detecting lost connections. Example ping stanza: + :: + - - Stanza Interface: - None - - Methods: - None """ name = 'ping' diff --git a/slixmpp/plugins/xep_0202/stanza.py b/slixmpp/plugins/xep_0202/stanza.py index 4c7a0229..e71ffe9c 100644 --- a/slixmpp/plugins/xep_0202/stanza.py +++ b/slixmpp/plugins/xep_0202/stanza.py @@ -23,6 +23,8 @@ class EntityTime(ElementBase): included. Example