From 95d40a3ca336a4e1b66c7ed287ec3f2ef92b201c Mon Sep 17 00:00:00 2001
From: mathieui <mathieui@mathieui.net>
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(-)
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:
+
+ ::
+
<iq type="get">
<query xmlns="http://jabber.org/protocol/disco#info" />
</iq>
@@ -48,6 +51,8 @@ class DiscoInfo(ElementBase):
</iq>
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:
+
+ ::
+
<iq type="get">
<query xmlns="http://jabber.org/protocol/disco#items" />
</iq>
@@ -29,17 +32,13 @@ class DiscoItems(ElementBase):
</iq>
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
- <presence from='foo@muc/user1' type='unavailable'>
- <x xmlns='http://jabber.org/protocol/muc#user'>
- <item affiliation='none'
- role='none'
- nick='newnick2'
- jid='some@jid'/>
- <status code='303'/>
- </x>
- </presence>
+ ::
+
+ <presence from='foo@muc/user1' type='unavailable'>
+ <x xmlns='http://jabber.org/protocol/muc#user'>
+ <item affiliation='none'
+ role='none'
+ nick='newnick2'
+ jid='some@jid'/>
+ <status code='303'/>
+ </x>
+ </presence>
'''
@@ -151,15 +153,17 @@ class MUCMessage(MUCBase):
'''
A MUC Message
- <message from='foo@muc/user1' type='groupchat' id='someid'>
- <body>Foo</body>
- <x xmlns='http://jabber.org/protocol/muc#user'>
- <item affiliation='none'
- role='none'
- nick='newnick2'
- jid='some@jid'/>
- </x>
- </message>
+ ::
+
+ <message from='foo@muc/user1' type='groupchat' id='someid'>
+ <body>Foo</body>
+ <x xmlns='http://jabber.org/protocol/muc#user'>
+ <item affiliation='none'
+ role='none'
+ nick='newnick2'
+ jid='some@jid'/>
+ </x>
+ </message>
'''
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 <http://xmpp.org/extensions/xep-0050.html>
Example command stanzas:
- <iq type="set">
- <command xmlns="http://jabber.org/protocol/commands"
- node="run_foo"
- action="execute" />
- </iq>
-
- <iq type="result">
- <command xmlns="http://jabber.org/protocol/commands"
- node="run_foo"
- sessionid="12345"
- status="executing">
- <actions>
- <complete />
- </actions>
- <note type="info">Information!</note>
- <x xmlns="jabber:x:data">
- <field var="greeting"
- type="text-single"
- label="Greeting" />
- </x>
- </command>
- </iq>
+
+ ::
+
+ <iq type="set">
+ <command xmlns="http://jabber.org/protocol/commands"
+ node="run_foo"
+ action="execute" />
+ </iq>
+
+ <iq type="result">
+ <command xmlns="http://jabber.org/protocol/commands"
+ node="run_foo"
+ sessionid="12345"
+ status="executing">
+ <actions>
+ <complete />
+ </actions>
+ <note type="info">Information!</note>
+ <x xmlns="jabber:x:data">
+ <field var="greeting"
+ type="text-single"
+ label="Greeting" />
+ </x>
+ </command>
+ </iq>
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:
- <iq type="get">
- <query xmlns="http://jabber.org/protocol/disco#items">
- <set xmlns="http://jabber.org/protocol/rsm">
- <max>2</max>
- </set>
- </query>
- </iq>
-
- <iq type="result">
- <query xmlns="http://jabber.org/protocol/disco#items">
- <item jid="conference.example.com" />
- <item jid="pubsub.example.com" />
- <set xmlns="http://jabber.org/protocol/rsm">
- <first>conference.example.com</first>
- <last>pubsub.example.com</last>
- </set>
- </query>
- </iq>
+ ::
+
+ <iq type="get">
+ <query xmlns="http://jabber.org/protocol/disco#items">
+ <set xmlns="http://jabber.org/protocol/rsm">
+ <max>2</max>
+ </set>
+ </query>
+ </iq>
+
+ <iq type="result">
+ <query xmlns="http://jabber.org/protocol/disco#items">
+ <item jid="conference.example.com" />
+ <item jid="pubsub.example.com" />
+ <set xmlns="http://jabber.org/protocol/rsm">
+ <first>conference.example.com</first>
+ <last>pubsub.example.com</last>
+ </set>
+ </query>
+ </iq>
Stanza Interface:
+ ::
+
first_index -- The index attribute of <first>
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 <first> and
- creates the element if it doesn't exist
- get_first_index -- Returns the value of the index
- attribute for <first>
- del_first_index -- Removes the index attribute for <first>
- but keeps the element
- set_before -- Sets the value of <before>, if the value is True
- then the element will be created without a value
- get_before -- Returns the value of <before>, 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 <first> 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 <first>
+ """
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 <first> 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 <before>, 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 <before>, 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 <geoloc> stanzas:
+
+ ::
+
<geoloc xmlns='http://jabber.org/protocol/geoloc'/>
<geoloc xmlns='http://jabber.org/protocol/geoloc' xml:lang='en'>
@@ -28,6 +31,8 @@ class Geoloc(ElementBase):
</geoloc>
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 <accuracy> 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 <alt> 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 <bearing> 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 <error> element.
- Arguments:
- error -- Horizontal GPS error in arc minutes; this
- element is deprecated in favor of <accuracy/>
+ :param error: Horizontal GPS error in arc minutes; this
+ element is deprecated in favor of <accuracy/>
"""
self._set_sub_text('error', text=str(error))
return self
@@ -178,8 +180,7 @@ class Geoloc(ElementBase):
"""
Set the value of the <lat> 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 <lon> 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 <speed> 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 <timestamp> 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:
+
+ ::
+
<message>
<active xmlns="http://jabber.org/protocol/chatstates" />
</message>
@@ -22,16 +25,6 @@ class ChatState(ElementBase):
<paused xmlns="http://jabber.org/protocol/chatstates" />
</message>
- 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 <http://xmpp.org/extensions/xep-0086.html>.
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 <http://xmpp.org/extensions/xep-0086.html>.
Example legacy error stanzas:
+ ::
+
<error xmlns="jabber:client" code="501" type="cancel">
<feature-not-implemented
xmlns="urn:ietf:params:xml:ns:xmpp-stanzas" />
@@ -32,13 +34,8 @@ class LegacyError(ElementBase):
xmlns="urn:ietf:params:xml:ns:xmpp-stanzas" />
</error>
- 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:
- <iq type="get">
- <query xmlns="jabber:iq:version" />
- </iq>
-
- <iq type="result">
- <query xmlns="jabber:iq:version">
- <name>Slixmpp</name>
- <version>1.0</version>
- <os>Linux</os>
- </query>
- </iq>
+ ::
+
+ <iq type="get">
+ <query xmlns="jabber:iq:version" />
+ </iq>
+
+ <iq type="result">
+ <query xmlns="jabber:iq:version">
+ <name>Slixmpp</name>
+ <version>1.0</version>
+ <os>Linux</os>
+ </query>
+ </iq>
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:
- <field var='evt.date' type='text-single' label='Event Date/Time'>
- <validate xmlns='http://jabber.org/protocol/xdata-validate'
- datatype='xs:dateTime'/>
- <value>2003-10-06T11:22:00-07:00</value>
- </field>
+ ::
+
+ <field var='evt.date' type='text-single' label='Event Date/Time'>
+ <validate xmlns='http://jabber.org/protocol/xdata-validate'
+ datatype='xs:dateTime'/>
+ <value>2003-10-06T11:22:00-07:00</value>
+ </field>
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 <http://www.xmpp.org/extensions/xep-0128.html>.
- 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:
+
+ ::
+
<message to="user@example.com">
<nick xmlns="http://jabber.org/nick/nick">The User</nick>
<body>...</body>
@@ -34,13 +37,11 @@ class UserNick(ElementBase):
</presence>
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 <nick> element.
- set_nick -- Add a <nick> element with the given nickname.
- del_nick -- Remove the <nick> 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:
+ ::
+
<iq type="get">
<ping xmlns="urn:xmpp:ping" />
</iq>
-
- 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 <time> stanzas:
+ ::
+
<iq type="result">
<time xmlns="urn:xmpp:time">
<utc>2011-07-03T11:37:12.234569</utc>
@@ -31,18 +33,11 @@ class EntityTime(ElementBase):
</iq>
Stanza Interface:
+ ::
+
time -- The local time for the entity (updates utc and tzo).
utc -- The UTC equivalent to local time.
tzo -- The local timezone offset from UTC.
-
- Methods:
- get_time -- Return local time datetime object.
- set_time -- Set UTC and TZO fields.
- del_time -- Remove both UTC and TZO fields.
- get_utc -- Return datetime object of UTC time.
- set_utc -- Set the UTC time.
- get_tzo -- Return tzinfo object.
- set_tzo -- Set the local timezone offset.
"""
name = 'time'
@@ -55,9 +50,8 @@ class EntityTime(ElementBase):
"""
Set both the UTC and TZO fields given a time object.
- Arguments:
- value -- A datetime object or properly formatted
- string equivalent.
+ :param value: A datetime object or properly formatted
+ string equivalent.
"""
date = value
if not isinstance(value, dt.datetime):
@@ -92,9 +86,8 @@ class EntityTime(ElementBase):
"""
Set the timezone offset from UTC.
- Arguments:
- value -- Either a tzinfo object or the number of
- seconds (positive or negative) to offset.
+ :param value: Either a tzinfo object or the number of
+ seconds (positive or negative) to offset.
"""
time = xep_0082.time(offset=value)
if xep_0082.parse(time).tzinfo == tzutc():
@@ -115,9 +108,8 @@ class EntityTime(ElementBase):
"""
Set the time in UTC.
- Arguments:
- value -- A datetime object or properly formatted
- string equivalent.
+ :param value: A datetime object or properly formatted
+ string equivalent.
"""
date = value
if not isinstance(value, dt.datetime):
diff --git a/slixmpp/plugins/xep_0202/time.py b/slixmpp/plugins/xep_0202/time.py
index 2b40dbb2..bec3a771 100644
--- a/slixmpp/plugins/xep_0202/time.py
+++ b/slixmpp/plugins/xep_0202/time.py
@@ -8,6 +8,9 @@
import logging
+from typing import Optional
+
+from slixmpp import JID
from slixmpp.stanza.iq import Iq
from slixmpp.xmlstream import register_stanza_plugin
from slixmpp.xmlstream.handler import Callback
@@ -61,7 +64,7 @@ class XEP_0202(BasePlugin):
def session_bind(self, jid):
self.xmpp['xep_0030'].add_feature('urn:xmpp:time')
- def _handle_time_request(self, iq):
+ def _handle_time_request(self, iq: Iq):
"""
Respond to a request for the local time.
@@ -69,26 +72,17 @@ class XEP_0202(BasePlugin):
during plugin configuration with a function that maps JIDs to
times.
- Arguments:
- iq -- The Iq time request stanza.
+ :param iq: The Iq time request stanza.
"""
iq = iq.reply()
iq['entity_time']['time'] = self.local_time(iq['to'])
iq.send()
- def get_entity_time(self, to, ifrom=None, **iqargs):
+ def get_entity_time(self, to: JID, ifrom: Optional[JID] = None, **iqargs):
"""
Request the time from another entity.
- Arguments:
- to -- JID of the entity to query.
- 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 to: JID of the entity to query.
"""
iq = self.xmpp.Iq()
iq['type'] = 'get'
diff --git a/slixmpp/plugins/xep_0222.py b/slixmpp/plugins/xep_0222.py
index abb10163..fdcf6c70 100644
--- a/slixmpp/plugins/xep_0222.py
+++ b/slixmpp/plugins/xep_0222.py
@@ -8,8 +8,11 @@
import logging
-from slixmpp.xmlstream import register_stanza_plugin
+from typing import Optional, Callable, List
+from slixmpp import 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__)
@@ -43,27 +46,23 @@ class XEP_0222(BasePlugin):
callback=callback,
timeout=timeout)
- def store(self, stanza, node=None, id=None, ifrom=None, options=None,
- callback=None, timeout=None):
+ def store(self, stanza: ElementBase, node: Optional[str] = None,
+ id: Optional[str] = None, ifrom: Optional[JID] = None,
+ options: Optional[Form] = None,
+ callback: Optional[Callable] = None,
+ timeout: Optional[int] = None):
"""
Store public data via PEP.
This is just a (very) thin wrapper around the XEP-0060 publish()
method to set the defaults expected by PEP.
- Arguments:
- stanza -- The private content to store.
- node -- The node to publish the content to. If not specified,
- the stanza's namespace will be used.
- id -- Optionally specify the ID of the item.
- options -- Publish options to use, which will be modified to
+ :param stanza: The private content to store.
+ :param node: The node to publish the content to. If not specified,
+ the stanza's namespace will be used.
+ :param id: Optionally specify the ID of the item.
+ :param options: Publish options to use, which will be modified to
fit the persistent storage option profile.
- 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.
"""
if not options:
options = self.xmpp['xep_0004'].stanza.Form()
@@ -85,25 +84,27 @@ class XEP_0222(BasePlugin):
callback=callback,
timeout=timeout)
- def retrieve(self, node, id=None, item_ids=None, ifrom=None,
- callback=None, timeout=None):
+ def retrieve(self, node: str, id: Optional[str] = None,
+ item_ids: Optional[List[str]] = None,
+ ifrom: Optional[JID] = None,
+ callback: Optional[Callable] = None,
+ timeout: Optional[int] = None):
"""
Retrieve public data via PEP.
This is just a (very) thin wrapper around the XEP-0060 publish()
method to set the defaults expected by PEP.
- Arguments:
- node -- The node to retrieve content from.
- id -- Optionally specify the ID of the item.
- item_ids -- Specify a group of IDs. If id is also specified, it
- will be included in item_ids.
- ifrom -- Specify the sender's JID.
- timeout -- The length of time (in seconds) to wait for a response
+ :param node: The node to retrieve content from.
+ :param id: Optionally specify the ID of the item.
+ :param item_ids: Specify a group of IDs. If id is also specified, it
+ will be included in item_ids.
+ :param ifrom: Specify the sender's JID.
+ :param 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 callback: Optional reference to a stream handler function. Will
+ be executed when a reply stanza is received.
"""
if item_ids is None:
item_ids = []
diff --git a/slixmpp/plugins/xep_0223.py b/slixmpp/plugins/xep_0223.py
index 18875eee..6cb8e1f3 100644
--- a/slixmpp/plugins/xep_0223.py
+++ b/slixmpp/plugins/xep_0223.py
@@ -8,8 +8,11 @@
import logging
-from slixmpp.xmlstream import register_stanza_plugin
+from typing import Optional, Callable, List
+from slixmpp import 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__)
@@ -44,27 +47,24 @@ class XEP_0223(BasePlugin):
callback=callback,
timeout=timeout)
- def store(self, stanza, node=None, id=None, ifrom=None, options=None,
- callback=None, timeout=None, timeout_callback=None):
+ def store(self, stanza: ElementBase, node: Optional[str] = None,
+ id: Optional[str] = None, ifrom: Optional[JID] = None,
+ options: Optional[Form] = None,
+ callback: Optional[Callable] = None,
+ timeout: Optional[int] = None,
+ timeout_callback: Optional[Callable] = None):
"""
Store private data via PEP.
This is just a (very) thin wrapper around the XEP-0060 publish()
method to set the defaults expected by PEP.
- Arguments:
- stanza -- The private content to store.
- node -- The node to publish the content to. If not specified,
- the stanza's namespace will be used.
- id -- Optionally specify the ID of the item.
- options -- Publish options to use, which will be modified to
+ :param stanza: The private content to store.
+ :param node: The node to publish the content to. If not specified,
+ the stanza's namespace will be used.
+ :param id: Optionally specify the ID of the item.
+ :param options: Publish options to use, which will be modified to
fit the persistent storage option profile.
- 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.
"""
if not options:
options = self.xmpp['xep_0004'].stanza.Form()
@@ -85,25 +85,28 @@ class XEP_0223(BasePlugin):
timeout=timeout,
timeout_callback=timeout_callback)
- def retrieve(self, node, id=None, item_ids=None, ifrom=None,
- callback=None, timeout=None, timeout_callback=None):
+ def retrieve(self, node: str, id: Optional[str] = None,
+ item_ids: Optional[List[str]] = None,
+ ifrom: Optional[JID] = None,
+ callback: Optional[Callable] = None,
+ timeout: Optional[int] = None,
+ timeout_callback: Optional[Callable] = None):
"""
Retrieve private data via PEP.
This is just a (very) thin wrapper around the XEP-0060 publish()
method to set the defaults expected by PEP.
- Arguments:
- node -- The node to retrieve content from.
- id -- Optionally specify the ID of the item.
- item_ids -- Specify a group of IDs. If id is also specified, it
- will be included in item_ids.
- ifrom -- Specify the sender's JID.
- timeout -- The length of time (in seconds) to wait for a response
+ :param node: The node to retrieve content from.
+ :param id: Optionally specify the ID of the item.
+ :param item_ids: Specify a group of IDs. If id is also specified, it
+ will be included in item_ids.
+ :param ifrom: Specify the sender's JID.
+ :param 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 callback: Optional reference to a stream handler function. Will
+ be executed when a reply stanza is received.
"""
if item_ids is None:
item_ids = []
diff --git a/slixmpp/plugins/xep_0231/stanza.py b/slixmpp/plugins/xep_0231/stanza.py
index 3de99aac..e7294c78 100644
--- a/slixmpp/plugins/xep_0231/stanza.py
+++ b/slixmpp/plugins/xep_0231/stanza.py
@@ -1,7 +1,7 @@
"""
Slixmpp: The Slick XMPP Library
- Copyright (C) 2012 Nathanael C. Fritz,
- Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
+ Copyright (C) 2012 Nathanael C. Fritz
+ Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
This file is part of Slixmpp.
See the file LICENSE for copying permission.
diff --git a/slixmpp/plugins/xep_0249/invite.py b/slixmpp/plugins/xep_0249/invite.py
index 9f08eae3..4be6921f 100644
--- a/slixmpp/plugins/xep_0249/invite.py
+++ b/slixmpp/plugins/xep_0249/invite.py
@@ -7,9 +7,10 @@
"""
import logging
+from typing import Optional
import slixmpp
-from slixmpp import Message
+from slixmpp import Message, JID
from slixmpp.plugins import BasePlugin
from slixmpp.xmlstream import register_stanza_plugin
from slixmpp.xmlstream.handler import Callback
@@ -46,7 +47,7 @@ class XEP_0249(BasePlugin):
def session_bind(self, jid):
self.xmpp['xep_0030'].add_feature(Invite.namespace)
- def _handle_invite(self, msg):
+ def _handle_invite(self, msg: Message):
"""
Raise an event for all invitations received.
"""
@@ -55,25 +56,26 @@ class XEP_0249(BasePlugin):
self.xmpp.event('groupchat_direct_invite', msg)
- def send_invitation(self, jid, roomjid, password=None,
- reason=None, ifrom=None):
+ def send_invitation(self, jid: JID, roomjid: JID,
+ password: Optional[str] = None,
+ reason: Optional[str] = None, *,
+ mfrom: Optional[JID] = None):
"""
Send a direct MUC invitation to an XMPP entity.
- Arguments:
- jid -- The JID of the entity that will receive
+ :param JID jid: The JID of the entity that will receive
the invitation
- roomjid -- the address of the groupchat room to be joined
- password -- a password needed for entry into a
- password-protected room (OPTIONAL).
- reason -- a human-readable purpose for the invitation
- (OPTIONAL).
+ :param JID roomjid: the address of the groupchat room to be joined
+ :param str password: a password needed for entry into a
+ password-protected room (OPTIONAL).
+ :param str reason: a human-readable purpose for the invitation
+ (OPTIONAL).
"""
msg = self.xmpp.Message()
msg['to'] = jid
- if ifrom is not None:
- msg['from'] = ifrom
+ if mfrom is not None:
+ msg['from'] = mfrom
msg['groupchat_invite']['jid'] = roomjid
if password is not None:
msg['groupchat_invite']['password'] = password
diff --git a/slixmpp/plugins/xep_0249/stanza.py b/slixmpp/plugins/xep_0249/stanza.py
index 5979f091..8633c67e 100644
--- a/slixmpp/plugins/xep_0249/stanza.py
+++ b/slixmpp/plugins/xep_0249/stanza.py
@@ -17,6 +17,9 @@ class Invite(ElementBase):
done through the server).
Example invite stanza:
+
+ ::
+
<message from='crone1@shakespeare.lit/desktop'
to='hecate@shakespeare.lit'>
<x xmlns='jabber:x:conference'
@@ -26,6 +29,9 @@ class Invite(ElementBase):
</message>
Stanza Interface:
+
+ ::
+
jid -- The JID of the groupchat room
password -- The password used to gain entry in the room
(optional)
diff --git a/slixmpp/plugins/xep_0332/stanza/request.py b/slixmpp/plugins/xep_0332/stanza/request.py
index 1d4aa5b1..670e27b1 100644
--- a/slixmpp/plugins/xep_0332/stanza/request.py
+++ b/slixmpp/plugins/xep_0332/stanza/request.py
@@ -19,32 +19,34 @@ class HTTPRequest(ElementBase):
element to the server. Each `iq` stanza sent is of type `set`.
Examples:
- <iq type='set' from='a@b.com/browser' to='x@y.com' id='1'>
- <req xmlns='urn:xmpp:http'
- method='GET'
- resource='/api/users'
- version='1.1'>
- <headers xmlns='http://jabber.org/protocol/shim'>
- <header name='Host'>b.com</header>
- </headers>
- </req>
- </iq>
+ ::
- <iq type='set' from='a@b.com/browser' to='x@y.com' id='2'>
- <req xmlns='urn:xmpp:http'
- method='PUT'
- resource='/api/users'
- version='1.1'>
- <headers xmlns='http://jabber.org/protocol/shim'>
- <header name='Host'>b.com</header>
- <header name='Content-Type'>text/html</header>
- <header name='Content-Length'>...</header>
- </headers>
- <data>
- <text>...</text>
- </data>
- </req>
- </iq>
+ <iq type='set' from='a@b.com/browser' to='x@y.com' id='1'>
+ <req xmlns='urn:xmpp:http'
+ method='GET'
+ resource='/api/users'
+ version='1.1'>
+ <headers xmlns='http://jabber.org/protocol/shim'>
+ <header name='Host'>b.com</header>
+ </headers>
+ </req>
+ </iq>
+
+ <iq type='set' from='a@b.com/browser' to='x@y.com' id='2'>
+ <req xmlns='urn:xmpp:http'
+ method='PUT'
+ resource='/api/users'
+ version='1.1'>
+ <headers xmlns='http://jabber.org/protocol/shim'>
+ <header name='Host'>b.com</header>
+ <header name='Content-Type'>text/html</header>
+ <header name='Content-Length'>...</header>
+ </headers>
+ <data>
+ <text>...</text>
+ </data>
+ </req>
+ </iq>
"""
name = 'request'
diff --git a/slixmpp/plugins/xep_0332/stanza/response.py b/slixmpp/plugins/xep_0332/stanza/response.py
index 8f58f0c2..a25aa780 100644
--- a/slixmpp/plugins/xep_0332/stanza/response.py
+++ b/slixmpp/plugins/xep_0332/stanza/response.py
@@ -21,27 +21,29 @@ class HTTPResponse(ElementBase):
in which the original requests were made.
Examples:
- <iq type='result'
- from='httpserver@clayster.com'
- to='httpclient@clayster.com/browser' id='2'>
- <resp xmlns='urn:xmpp:http'
- version='1.1'
- statusCode='200'
- statusMessage='OK'>
- <headers xmlns='http://jabber.org/protocol/shim'>
- <header name='Date'>Fri, 03 May 2013 16:39:54GMT-4</header>
- <header name='Server'>Clayster</header>
- <header name='Content-Type'>text/turtle</header>
- <header name='Content-Length'>...</header>
- <header name='Connection'>Close</header>
- </headers>
- <data>
- <text>
- ...
- </text>
- </data>
- </resp>
- </iq>
+ ::
+
+ <iq type='result'
+ from='httpserver@clayster.com'
+ to='httpclient@clayster.com/browser' id='2'>
+ <resp xmlns='urn:xmpp:http'
+ version='1.1'
+ statusCode='200'
+ statusMessage='OK'>
+ <headers xmlns='http://jabber.org/protocol/shim'>
+ <header name='Date'>Fri, 03 May 2013 16:39:54GMT-4</header>
+ <header name='Server'>Clayster</header>
+ <header name='Content-Type'>text/turtle</header>
+ <header name='Content-Length'>...</header>
+ <header name='Connection'>Close</header>
+ </headers>
+ <data>
+ <text>
+ ...
+ </text>
+ </data>
+ </resp>
+ </iq>
"""
name = 'response'
diff --git a/slixmpp/plugins/xep_0369/mix_core.py b/slixmpp/plugins/xep_0369/mix_core.py
index 598a97f4..19450c12 100644
--- a/slixmpp/plugins/xep_0369/mix_core.py
+++ b/slixmpp/plugins/xep_0369/mix_core.py
@@ -79,9 +79,10 @@ class XEP_0369(BasePlugin):
async def get_channel_info(self, channel: JID) -> InfoType:
""""
Get the contents of the channel info node.
- :param JID channel: The MIX channel
+
+ :param channel: The MIX channel
:returns: a dict containing the last modified time and form contents
- (Name, Description, Contact per the spec, YMMV)
+ (Name, Description, Contact per the spec, YMMV)
"""
info = await self.xmpp['xep_0060'].get_items(channel, 'urn:xmpp:mix:nodes:info')
for item in info['pubsub']['items']:
diff --git a/slixmpp/plugins/xep_0377/stanza.py b/slixmpp/plugins/xep_0377/stanza.py
index 1930c382..ccc04c1f 100644
--- a/slixmpp/plugins/xep_0377/stanza.py
+++ b/slixmpp/plugins/xep_0377/stanza.py
@@ -14,15 +14,18 @@ class Report(ElementBase):
A spam/abuse report.
Example sub stanza:
+ ::
- <report xmlns="urn:xmpp:reporting:0">
- <text xml:lang="en">
- Never came trouble to my house like this.
- </text>
- <spam/>
- </report>
+ <report xmlns="urn:xmpp:reporting:0">
+ <text xml:lang="en">
+ Never came trouble to my house like this.
+ </text>
+ <spam/>
+ </report>
Stanza Interface:
+ ::
+
abuse -- Flag the report as abuse
spam -- Flag the report as spam
text -- Add a reason to the report
diff --git a/slixmpp/plugins/xep_0421/stanza.py b/slixmpp/plugins/xep_0421/stanza.py
index ab1128d6..510bb50d 100644
--- a/slixmpp/plugins/xep_0421/stanza.py
+++ b/slixmpp/plugins/xep_0421/stanza.py
@@ -24,15 +24,17 @@ class OccupantId(ElementBase):
Without occupant-id, getting the following messages from MUC history would
prevent a client from asserting senders are the same entity:
- <message type='groupchat' from='foo@muc/nick1' id='message1'>
- <body>Some message</body>
- <occupant-id xmlns='urn:xmpp:occupant-id:0' id='unique-opaque-id1'/>
- </message>
- <message type='groupchat' from='foo@muc/nick2' id='message2'>
- <body>Some correction</body>
- <occupant-id xmlns='urn:xmpp:occupant-id:0' id='unique-opaque-id1'/>
- <replace xmlns='urn:xmpp:message-correct:0' id='message1'/>
- </message>
+ ::
+
+ <message type='groupchat' from='foo@muc/nick1' id='message1'>
+ <body>Some message</body>
+ <occupant-id xmlns='urn:xmpp:occupant-id:0' id='unique-opaque-id1'/>
+ </message>
+ <message type='groupchat' from='foo@muc/nick2' id='message2'>
+ <body>Some correction</body>
+ <occupant-id xmlns='urn:xmpp:occupant-id:0' id='unique-opaque-id1'/>
+ <replace xmlns='urn:xmpp:message-correct:0' id='message1'/>
+ </message>
'''
name = 'occupant-id'
diff --git a/slixmpp/plugins/xep_0424/retraction.py b/slixmpp/plugins/xep_0424/retraction.py
index 5425a61f..d3461d66 100644
--- a/slixmpp/plugins/xep_0424/retraction.py
+++ b/slixmpp/plugins/xep_0424/retraction.py
@@ -43,12 +43,13 @@ class XEP_0424(BasePlugin):
mfrom: Optional[JID] = None):
"""
Send a message retraction
+
:param JID mto: The JID to retract the message from
:param str id: Message ID to retract
:param str mtype: Message type
:param bool include_fallback: Whether to include a fallback body
- :param Optional[str] fallback_text: The contet of the fallback
- body. None will set the default value.
+ :param Optional[str] fallback_text: The content of the fallback
+ body. None will set the default value.
"""
if fallback_text is None:
fallback_text = DEFAULT_FALLBACK
diff --git a/slixmpp/xmlstream/tostring.py b/slixmpp/xmlstream/tostring.py
index d6cc85dd..f772ff63 100644
--- a/slixmpp/xmlstream/tostring.py
+++ b/slixmpp/xmlstream/tostring.py
@@ -1,7 +1,7 @@
# -*- coding: utf-8 -*-
"""
slixmpp.xmlstream.tostring
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~
This module converts XML objects into Unicode strings and
intelligently includes namespaces only when necessary to
diff --git a/slixmpp/xmlstream/xmlstream.py b/slixmpp/xmlstream/xmlstream.py
index 066d84df..14020e1c 100644
--- a/slixmpp/xmlstream/xmlstream.py
+++ b/slixmpp/xmlstream/xmlstream.py
@@ -261,7 +261,6 @@ class XMLStream(asyncio.BaseProtocol):
connection will be upgraded to SSL/TLS later, using
STARTTLS. Only use this value for old servers that
have specific port for SSL/TLS
- TODO fix the comment
:param force_starttls: If True, the connection will be aborted if
the server does not initiate a STARTTLS
negotiation. If None, the connection will be
@@ -278,7 +277,7 @@ class XMLStream(asyncio.BaseProtocol):
self.run_filters(),
loop=self.loop,
)
-
+
self.disconnect_reason = None
self.cancel_connection_attempt()
self.connect_loop_wait = 0
--
cgit v1.2.3