jshiffer/slixmpp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update docstrings for sphinx conformity

Browse Source 
Remove most references to timeout/callback/ifrom/timeout_callbacks args
This commit is contained in:
mathieui 2020-12-10 19:20:23 +01:00
parent 010bf6dd70
commit 95d40a3ca3
44 changed files with 791 additions and 1057 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

279
slixmpp/plugins/xep_0030/disco.py
View File

@ -9,6 +9,9 @@
import asyncio import asyncio
import logging import logging
from typing import Optional, Callable
from slixmpp import Iq from slixmpp import Iq
from slixmpp import future_wrapper from slixmpp import future_wrapper
from slixmpp.plugins import BasePlugin from slixmpp.plugins import BasePlugin
@ -41,6 +44,9 @@ class XEP_0030(BasePlugin):
storage mechanism desired, such as SQLite or Redis. storage mechanism desired, such as SQLite or Redis.
Node handler hierarchy: Node handler hierarchy:
::
JID | Node | Level JID | Node | Level
--------------------- ---------------------
None | None | Global None | None | Global
@ -49,41 +55,29 @@ class XEP_0030(BasePlugin):
Given | Given | A single node Given | Given | A single node
Stream Handlers: Stream Handlers:
::
Disco Info -- Any Iq stanze that includes a query with the Disco Info -- Any Iq stanze that includes a query with the
namespace http://jabber.org/protocol/disco#info. namespace http://jabber.org/protocol/disco#info.
Disco Items -- Any Iq stanze that includes a query with the Disco Items -- Any Iq stanze that includes a query with the
namespace http://jabber.org/protocol/disco#items. namespace http://jabber.org/protocol/disco#items.
Events: Events:
::
disco_info -- Received a disco#info Iq query result. disco_info -- Received a disco#info Iq query result.
disco_items -- Received a disco#items Iq query result. disco_items -- Received a disco#items Iq query result.
disco_info_query -- Received a disco#info Iq query request. disco_info_query -- Received a disco#info Iq query request.
disco_items_query -- Received a disco#items Iq query request. disco_items_query -- Received a disco#items Iq query request.
Attributes: 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: :var static: Object containing the default set of
set_node_handler -- Assign a handler to a JID/node combination. static node handlers.
del_node_handler -- Remove a handler from a JID/node combination. :var default_handlers: A dictionary mapping operations to the default
get_info -- Retrieve disco#info data, locally or remote. global handler (by default, the static handlers).
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 --
""" """
name = 'xep_0030' name = 'xep_0030'
@ -136,7 +130,9 @@ class XEP_0030(BasePlugin):
self.api.register(default_handler, op) self.api.register(default_handler, op)
self.api.register_default(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 Add a node handler for the given hierarchy level and
handler type. handler type.
@ -148,6 +144,9 @@ class XEP_0030(BasePlugin):
global behavior. global behavior.
Node handler hierarchy: Node handler hierarchy:
::
JID | Node | Level JID | Node | Level
--------------------- ---------------------
None | None | Global None | None | Global
@ -156,6 +155,9 @@ class XEP_0030(BasePlugin):
Given | Given | A single node Given | Given | A single node
Handler types: Handler types:
::
get_info get_info
get_items get_items
set_identities set_identities
@ -171,14 +173,13 @@ class XEP_0030(BasePlugin):
add_feature add_feature
add_item add_item
Arguments: :param htype: The operation provided by the handler.
htype -- The operation provided by the handler. :param jid: The JID the handler applies to. May be narrowed
jid -- The JID the handler applies to. May be narrowed
further if a node is given. further if a node is given.
node -- The particular node the handler is for. If no JID :param node: The particular node the handler is for. If no JID
is given, then the self.xmpp.boundjid.full is is given, then the self.xmpp.boundjid.full is
assumed. assumed.
handler -- The handler function to use. :param handler: The handler function to use.
""" """
self.api.register(handler, htype, jid, node) self.api.register(handler, htype, jid, node)
@ -191,6 +192,9 @@ class XEP_0030(BasePlugin):
other handlers exist to process existing nodes. other handlers exist to process existing nodes.
Node handler hierarchy: Node handler hierarchy:
::
JID | Node | Level JID | Node | Level
--------------------- ---------------------
None | None | Global None | None | Global
@ -198,10 +202,9 @@ class XEP_0030(BasePlugin):
None | Given | Node on self.xmpp.boundjid None | Given | Node on self.xmpp.boundjid
Given | Given | A single node Given | Given | A single node
Arguments: :param htype: The type of handler to remove.
htype -- The type of handler to remove. :param jid: The JID from which to remove the handler.
jid -- The JID from which to remove the handler. :param node: The node from which to remove the handler.
node -- The node from which to remove the handler.
""" """
self.api.unregister(htype, jid, node) self.api.unregister(htype, jid, node)
@ -215,10 +218,9 @@ class XEP_0030(BasePlugin):
The default is to use the built-in static handlers, but that The default is to use the built-in static handlers, but that
may be changed by modifying self.default_handlers. may be changed by modifying self.default_handlers.
Arguments: :param jid: The JID owning the node to modify.
jid -- The JID owning the node to modify. :param node: The node to change to using static handlers.
node -- The node to change to using static handlers. :param handlers: Optional list of handlers to change to the
handlers -- Optional list of handlers to change to the
default version. If provided, only these default version. If provided, only these
handlers will be changed. Otherwise, all handlers will be changed. Otherwise, all
handlers will use the default version. handlers will use the default version.
@ -234,27 +236,25 @@ class XEP_0030(BasePlugin):
Check if a JID supports a given feature. Check if a JID supports a given feature.
Return values: Return values:
True -- The feature is supported :param True: The feature is supported
False -- The feature is not listed as supported :param False: The feature is not listed as supported
None -- Nothing could be found due to a timeout :param None: Nothing could be found due to a timeout
Arguments: :param jid: Request info from this JID.
jid -- Request info from this JID. :param node: The particular node to query.
node -- The particular node to query. :param feature: The name of the feature to check.
feature -- The name of the feature to check. :param local: If true, then the query is for a JID/node
local -- If true, then the query is for a JID/node
combination handled by this Slixmpp instance and combination handled by this Slixmpp instance and
no stanzas need to be sent. no stanzas need to be sent.
Otherwise, a disco stanza must be sent to the Otherwise, a disco stanza must be sent to the
remove JID to retrieve the info. 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, the local cache system. If no results are found,
send the query as usual. The self.use_cache send the query as usual. The self.use_cache
setting must be set to true for this option to setting must be set to true for this option to
be useful. If set to false, then the cache will be useful. If set to false, then the cache will
be skipped, even if a result has already been be skipped, even if a result has already been
cached. Defaults to false. cached. Defaults to false.
ifrom -- Specifiy the sender's JID.
""" """
data = {'feature': feature, data = {'feature': feature,
'local': local, 'local': local,
@ -267,29 +267,27 @@ class XEP_0030(BasePlugin):
Check if a JID provides a given identity. Check if a JID provides a given identity.
Return values: Return values:
True -- The identity is provided :param True: The identity is provided
False -- The identity is not listed :param False: The identity is not listed
None -- Nothing could be found due to a timeout :param None: Nothing could be found due to a timeout
Arguments: :param jid: Request info from this JID.
jid -- Request info from this JID. :param node: The particular node to query.
node -- The particular node to query. :param category: The category of the identity to check.
category -- The category of the identity to check. :param itype: The type of the identity to check.
itype -- The type of the identity to check. :param lang: The language of the identity to check.
lang -- The language of the identity to check. :param local: If true, then the query is for a JID/node
local -- If true, then the query is for a JID/node
combination handled by this Slixmpp instance and combination handled by this Slixmpp instance and
no stanzas need to be sent. no stanzas need to be sent.
Otherwise, a disco stanza must be sent to the Otherwise, a disco stanza must be sent to the
remove JID to retrieve the info. 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, the local cache system. If no results are found,
send the query as usual. The self.use_cache send the query as usual. The self.use_cache
setting must be set to true for this option to setting must be set to true for this option to
be useful. If set to false, then the cache will be useful. If set to false, then the cache will
be skipped, even if a result has already been be skipped, even if a result has already been
cached. Defaults to false. cached. Defaults to false.
ifrom -- Specifiy the sender's JID.
""" """
data = {'category': category, data = {'category': category,
'itype': itype, 'itype': itype,
@ -343,29 +341,20 @@ class XEP_0030(BasePlugin):
If requesting items from a local JID/node, then only a DiscoInfo If requesting items from a local JID/node, then only a DiscoInfo
stanza will be returned. Otherwise, an Iq stanza will be returned. stanza will be returned. Otherwise, an Iq stanza will be returned.
Arguments: :param jid: Request info from this JID.
jid -- Request info from this JID. :param node: The particular node to query.
node -- The particular node to query. :param local: If true, then the query is for a JID/node
local -- If true, then the query is for a JID/node
combination handled by this Slixmpp instance and combination handled by this Slixmpp instance and
no stanzas need to be sent. no stanzas need to be sent.
Otherwise, a disco stanza must be sent to the Otherwise, a disco stanza must be sent to the
remote JID to retrieve the info. remote 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, the local cache system. If no results are found,
send the query as usual. The self.use_cache send the query as usual. The self.use_cache
setting must be set to true for this option to setting must be set to true for this option to
be useful. If set to false, then the cache will be useful. If set to false, then the cache will
be skipped, even if a result has already been be skipped, even if a result has already been
cached. Defaults to false. 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.
""" """
if local is None: if local is None:
if jid is not None and not isinstance(jid, JID): 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 If requesting items from a local JID/node, then only a DiscoItems
stanza will be returned. Otherwise, an Iq stanza will be returned. stanza will be returned. Otherwise, an Iq stanza will be returned.
Arguments: :param jid: Request info from this JID.
jid -- Request info from this JID. :param node: The particular node to query.
node -- The particular node to query. :param local: If true, then the query is for a JID/node
local -- If true, then the query is for a JID/node
combination handled by this Slixmpp instance and combination handled by this Slixmpp instance and
no stanzas need to be sent. no stanzas need to be sent.
Otherwise, a disco stanza must be sent to the Otherwise, a disco stanza must be sent to the
remove JID to retrieve the items. remove JID to retrieve the items.
ifrom -- Specifiy the sender's JID. :param iterator: If True, return a result set iterator using
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. the XEP-0059 plugin, if the plugin is loaded.
Otherwise the parameter is ignored. Otherwise the parameter is ignored.
timeout_callback -- Optional callback to execute when no result
has been received in timeout seconds.
""" """
if local or local is None and jid is None: if local or local is None and jid is None:
items = self.api['get_items'](jid, node, 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 The given items must be in a list or set where each item is a
tuple of the form: (jid, node, name). tuple of the form: (jid, node, name).
Arguments: :param jid: The JID to modify.
jid -- The JID to modify. :param node: Optional node to modify.
node -- Optional node to modify. :param items: A series of items in tuple format.
items -- A series of items in tuple format.
""" """
self.api['set_items'](jid, node, None, kwargs) 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. Remove all items from the given JID/node combination.
Arguments: Arguments:
jid -- The JID to modify. :param jid: The JID to modify.
node -- Optional node to modify. :param node: Optional node to modify.
""" """
self.api['del_items'](jid, node, None, kwargs) 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 Each item is required to have a JID, but may also specify
a node value to reference non-addressable entities. a node value to reference non-addressable entities.
Arguments: :param jid: The JID for the item.
jid -- The JID for the item. :param name: Optional name for the item.
name -- Optional name for the item. :param node: The node to modify.
node -- The node to modify. :param subnode: Optional node for the item.
subnode -- Optional node for the item. :param ijid: The JID to modify.
ijid -- The JID to modify.
""" """
if not jid: if not jid:
jid = self.xmpp.boundjid.full jid = self.xmpp.boundjid.full
@ -519,11 +497,10 @@ class XEP_0030(BasePlugin):
""" """
Remove a single item from the given JID/node combination. Remove a single item from the given JID/node combination.
Arguments: :param jid: The JID to modify.
jid -- The JID to modify. :param node: The node to modify.
node -- The node to modify. :param ijid: The item's JID.
ijid -- The item's JID. :param inode: The item's node.
inode -- The item's node.
""" """
self.api['del_item'](jid, node, None, kwargs) 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 category/type/xml:lang pairs are allowed so long as the
names are different. A category and type is always required. names are different. A category and type is always required.
Arguments: :param category: The identity's category.
category -- The identity's category. :param itype: The identity's type.
itype -- The identity's type. :param name: Optional name for the identity.
name -- Optional name for the identity. :param lang: Optional two-letter language code.
lang -- Optional two-letter language code. :param node: The node to modify.
node -- The node to modify. :param jid: The JID to modify.
jid -- The JID to modify.
""" """
kwargs = {'category': category, kwargs = {'category': category,
'itype': itype, 'itype': itype,
@ -554,29 +530,28 @@ class XEP_0030(BasePlugin):
'lang': lang} 'lang': lang}
self.api['add_identity'](jid, node, None, kwargs) 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. Add a feature to a JID/node combination.
Arguments: :param feature: The namespace of the supported feature.
feature -- The namespace of the supported feature. :param node: The node to modify.
node -- The node to modify. :param jid: The JID to modify.
jid -- The JID to modify.
""" """
kwargs = {'feature': feature} kwargs = {'feature': feature}
self.api['add_feature'](jid, node, None, kwargs) 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. Remove an identity from the given JID/node combination.
Arguments: :param jid: The JID to modify.
jid -- The JID to modify. :param node: The node to modify.
node -- The node to modify. :param category: The identity's category.
category -- The identity's category. :param itype: The identity's type value.
itype -- The identity's type value. :param name: Optional, human readable name for the identity.
name -- Optional, human readable name for the identity. :param lang: Optional, the identity's xml:lang value.
lang -- Optional, the identity's xml:lang value.
""" """
self.api['del_identity'](jid, node, None, kwargs) 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. Remove a feature from a given JID/node combination.
Arguments: :param jid: The JID to modify.
jid -- The JID to modify. :param node: The node to modify.
node -- The node to modify. :param feature: The feature's namespace.
feature -- The feature's namespace.
""" """
self.api['del_feature'](jid, node, None, kwargs) 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 The identities must be in a set where each identity is a tuple
of the form: (category, type, lang, name) of the form: (category, type, lang, name)
Arguments: :param jid: The JID to modify.
jid -- The JID to modify. :param node: The node to modify.
node -- The node to modify. :param identities: A set of identities in tuple form.
identities -- A set of identities in tuple form. :param lang: Optional, xml:lang value.
lang -- Optional, xml:lang value.
""" """
self.api['set_identities'](jid, node, None, kwargs) 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 If a language is specified, only identities using that
language will be removed. language will be removed.
Arguments: :param jid: The JID to modify.
jid -- The JID to modify. :param node: The node to modify.
node -- The node to modify. :param lang: Optional. If given, only remove identities
lang -- Optional. If given, only remove identities
using this xml:lang value. using this xml:lang value.
""" """
self.api['del_identities'](jid, node, None, kwargs) self.api['del_identities'](jid, node, None, kwargs)
@ -626,10 +598,9 @@ class XEP_0030(BasePlugin):
Add or replace the set of supported features Add or replace the set of supported features
for a JID/node combination. for a JID/node combination.
Arguments: :param jid: The JID to modify.
jid -- The JID to modify. :param node: The node to modify.
node -- The node to modify. :param features: The new set of supported features.
features -- The new set of supported features.
""" """
self.api['set_features'](jid, node, None, kwargs) self.api['set_features'](jid, node, None, kwargs)
@ -637,9 +608,8 @@ class XEP_0030(BasePlugin):
""" """
Remove all features from a JID/node combination. Remove all features from a JID/node combination.
Arguments: :param jid: The JID to modify.
jid -- The JID to modify. :param node: The node to modify.
node -- The node to modify.
""" """
self.api['del_features'](jid, node, None, kwargs) 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 Execute the most specific node handler for the given
JID/node combination. JID/node combination.
Arguments: :param htype: The handler type to execute.
htype -- The handler type to execute. :param jid: The JID requested.
jid -- The JID requested. :param node: The node requested.
node -- The node requested. :param data: Optional, custom data to pass to the handler.
data -- Optional, custom data to pass to the handler.
""" """
if not data: if not data:
data = {} data = {}
@ -666,8 +635,7 @@ class XEP_0030(BasePlugin):
and features. If it is an info result, fire the and features. If it is an info result, fire the
disco_info event. disco_info event.
Arguments: :param iq: The incoming disco#items stanza.
iq -- The incoming disco#items stanza.
""" """
if iq['type'] == 'get': if iq['type'] == 'get':
log.debug("Received disco info query from " + \ log.debug("Received disco info query from " + \
@ -709,8 +677,7 @@ class XEP_0030(BasePlugin):
request, find and return the appropriate items. If it request, find and return the appropriate items. If it
is an items result, fire the disco_items event. is an items result, fire the disco_items event.
Arguments: :param iq: The incoming disco#items stanza.
iq -- The incoming disco#items stanza.
""" """
if iq['type'] == 'get': if iq['type'] == 'get':
log.debug("Received disco items query from " + \ 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 bot client identity. A the standard disco#info feature will also be
added if no features are provided. added if no features are provided.
Arguments: :param info: The disco#info quest (not the full Iq stanza) to modify.
info -- The disco#info quest (not the full Iq stanza) to modify.
""" """
result = info result = info
if isinstance(info, Iq): if isinstance(info, Iq):
@ -766,11 +732,10 @@ class XEP_0030(BasePlugin):
Ensure that results are wrapped in an Iq stanza Ensure that results are wrapped in an Iq stanza
if self.wrap_results has been set to True. if self.wrap_results has been set to True.
Arguments: :param ito: The JID to use as the 'to' value
ito -- The JID to use as the 'to' value :param ifrom: The JID to use as the 'from' value
ifrom -- The JID to use as the 'from' value :param payload: The disco data to wrap
payload -- The disco data to wrap :param force: Force wrapping, regardless of self.wrap_results
force -- Force wrapping, regardless of self.wrap_results
""" """
if (force or self.wrap_results) and not isinstance(payload, Iq): if (force or self.wrap_results) and not isinstance(payload, Iq):
iq = self.xmpp.Iq() iq = self.xmpp.Iq()

65
slixmpp/plugins/xep_0030/stanza/info.py
View File

@ -34,6 +34,9 @@ class DiscoInfo(ElementBase):
be like section headings. be like section headings.
Example disco#info stanzas: Example disco#info stanzas:
::
<iq type="get"> <iq type="get">
<query xmlns="http://jabber.org/protocol/disco#info" /> <query xmlns="http://jabber.org/protocol/disco#info" />
</iq> </iq>
@ -48,6 +51,8 @@ class DiscoInfo(ElementBase):
</iq> </iq>
Stanza Interface: Stanza Interface:
::
node -- The name of the node to either node -- The name of the node to either
query or return info from. query or return info from.
identities -- A set of 4-tuples, where each tuple contains identities -- A set of 4-tuples, where each tuple contains
@ -55,17 +60,6 @@ class DiscoInfo(ElementBase):
of an identity. of an identity.
features -- A set of namespaces for features. 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' name = 'query'
@ -86,8 +80,7 @@ class DiscoInfo(ElementBase):
Caches identity and feature information. Caches identity and feature information.
Arguments: :param xml: Use an existing XML object for the stanza's values.
xml -- Use an existing XML object for the stanza's values.
""" """
ElementBase.setup(self, xml) ElementBase.setup(self, xml)
@ -104,11 +97,10 @@ class DiscoInfo(ElementBase):
category/type/xml:lang pairs are allowed so long as the names category/type/xml:lang pairs are allowed so long as the names
are different. In any case, a category and type are required. are different. In any case, a category and type are required.
Arguments: :param category: The general category to which the agent belongs.
category -- The general category to which the agent belongs. :param itype: A more specific designation with the category.
itype -- A more specific designation with the category. :param name: Optional human readable name for this identity.
name -- Optional human readable name for this identity. :param lang: Optional standard xml:lang value.
lang -- Optional standard xml:lang value.
""" """
identity = (category, itype, lang) identity = (category, itype, lang)
if identity not in self._identities: if identity not in self._identities:
@ -128,11 +120,10 @@ class DiscoInfo(ElementBase):
""" """
Remove a given identity. Remove a given identity.
Arguments: :param category: The general category to which the agent belonged.
category -- The general category to which the agent belonged. :param itype: A more specific designation with the category.
itype -- A more specific designation with the category. :param name: Optional human readable name for this identity.
name -- Optional human readable name for this identity. :param lang: Optional, standard xml:lang value.
lang -- Optional, standard xml:lang value.
""" """
identity = (category, itype, lang) identity = (category, itype, lang)
if identity in self._identities: if identity in self._identities:
@ -149,14 +140,14 @@ class DiscoInfo(ElementBase):
def get_identities(self, lang=None, dedupe=True): def get_identities(self, lang=None, dedupe=True):
""" """
Return a set of all identities in tuple form as so: Return a set of all identities in tuple form as so:
(category, type, lang, name) (category, type, lang, name)
If a language was specified, only return identities using If a language was specified, only return identities using
that language. that language.
Arguments: :param lang: Optional, standard xml:lang value.
lang -- Optional, standard xml:lang value. :param dedupe: If True, de-duplicate identities, otherwise
dedupe -- If True, de-duplicate identities, otherwise
return a list of all identities. return a list of all identities.
""" """
if dedupe: if dedupe:
@ -180,17 +171,19 @@ class DiscoInfo(ElementBase):
""" """
Add or replace all identities. The identities must be a in set Add or replace all identities. The identities must be a in set
where each identity is a tuple of the form: where each identity is a tuple of the form:
(category, type, lang, name) (category, type, lang, name)
If a language is specifified, any identities using that language If a language is specifified, any identities using that language
will be removed to be replaced with the given identities. will be removed to be replaced with the given identities.
NOTE: An identity's language will not be changed regardless of .. note::
An identity's language will not be changed regardless of
the value of lang. the value of lang.
Arguments: :param identities: A set of identities in tuple form.
identities -- A set of identities in tuple form. :param lang: Optional, standard xml:lang value.
lang -- Optional, standard xml:lang value.
""" """
self.del_identities(lang) self.del_identities(lang)
for identity in identities: for identity in identities:
@ -202,8 +195,7 @@ class DiscoInfo(ElementBase):
Remove all identities. If a language was specified, only Remove all identities. If a language was specified, only
remove identities using that language. remove identities using that language.
Arguments: :param lang: Optional, standard xml:lang value.
lang -- Optional, standard xml:lang value.
""" """
for id_xml in self.xml.findall('{%s}identity' % self.namespace): for id_xml in self.xml.findall('{%s}identity' % self.namespace):
if lang is None: if lang is None:
@ -219,8 +211,7 @@ class DiscoInfo(ElementBase):
""" """
Add a single, new feature. Add a single, new feature.
Arguments: :param feature: The namespace of the supported feature.
feature -- The namespace of the supported feature.
""" """
if feature not in self._features: if feature not in self._features:
self._features.add(feature) self._features.add(feature)
@ -234,8 +225,7 @@ class DiscoInfo(ElementBase):
""" """
Remove a single feature. Remove a single feature.
Arguments: :param feature: The namespace of the removed feature.
feature -- The namespace of the removed feature.
""" """
if feature in self._features: if feature in self._features:
self._features.remove(feature) self._features.remove(feature)
@ -262,8 +252,7 @@ class DiscoInfo(ElementBase):
""" """
Add or replace the set of supported features. Add or replace the set of supported features.
Arguments: :param features: The new set of supported features.
features -- The new set of supported features.
""" """
self.del_features() self.del_features()
for feature in features: for feature in features:

30
slixmpp/plugins/xep_0030/stanza/items.py
View File

@ -13,6 +13,9 @@ class DiscoItems(ElementBase):
""" """
Example disco#items stanzas: Example disco#items stanzas:
::
<iq type="get"> <iq type="get">
<query xmlns="http://jabber.org/protocol/disco#items" /> <query xmlns="http://jabber.org/protocol/disco#items" />
</iq> </iq>
@ -29,17 +32,13 @@ class DiscoItems(ElementBase):
</iq> </iq>
Stanza Interface: Stanza Interface:
::
node -- The name of the node to either node -- The name of the node to either
query or return info from. query or return info from.
items -- A list of 3-tuples, where each tuple contains items -- A list of 3-tuples, where each tuple contains
the JID, node, and name of an item. 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' name = 'query'
@ -58,8 +57,7 @@ class DiscoItems(ElementBase):
Caches item information. Caches item information.
Arguments: :param xml: Use an existing XML object for the stanza's values.
xml -- Use an existing XML object for the stanza's values.
""" """
ElementBase.setup(self, xml) ElementBase.setup(self, xml)
self._items = {item[0:2] for item in self['items']} 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 JID, but may also specify a node value to reference
non-addressable entitities. non-addressable entitities.
Arguments: :param jid: The JID for the item.
jid -- The JID for the item. :param node: Optional additional information to reference
node -- Optional additional information to reference
non-addressable items. non-addressable items.
name -- Optional human readable name for the item. :param name: Optional human readable name for the item.
""" """
if (jid, node) not in self._items: if (jid, node) not in self._items:
self._items.add((jid, node)) self._items.add((jid, node))
@ -90,9 +87,8 @@ class DiscoItems(ElementBase):
""" """
Remove a single item. Remove a single item.
Arguments: :param jid: JID of the item to remove.
jid -- JID of the item to remove. :param node: Optional extra identifying information.
node -- Optional extra identifying information.
""" """
if (jid, node) in self._items: if (jid, node) in self._items:
for item_xml in self.xml.findall('{%s}item' % self.namespace): 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 Set or replace all items. The given items must be in a
list or set where each item is a tuple of the form: list or set where each item is a tuple of the form:
(jid, node, name) (jid, node, name)
Arguments: :param items: A series of items in tuple format.
items -- A series of items in tuple format.
""" """
self.del_items() self.del_items()
for item in items: for item in items:

4
slixmpp/plugins/xep_0045/stanza.py
View File

@ -135,6 +135,8 @@ class MUCPresence(MUCBase):
''' '''
A MUC Presence A MUC Presence
::
<presence from='foo@muc/user1' type='unavailable'> <presence from='foo@muc/user1' type='unavailable'>
<x xmlns='http://jabber.org/protocol/muc#user'> <x xmlns='http://jabber.org/protocol/muc#user'>
<item affiliation='none' <item affiliation='none'
@ -151,6 +153,8 @@ class MUCMessage(MUCBase):
''' '''
A MUC Message A MUC Message
::
<message from='foo@muc/user1' type='groupchat' id='someid'> <message from='foo@muc/user1' type='groupchat' id='someid'>
<body>Foo</body> <body>Foo</body>
<x xmlns='http://jabber.org/protocol/muc#user'> <x xmlns='http://jabber.org/protocol/muc#user'>

119
slixmpp/plugins/xep_0050/adhoc.py
View File

@ -50,26 +50,6 @@ class XEP_0050(BasePlugin):
session IDs to dictionaries containing data session IDs to dictionaries containing data
relevant to a command's session. 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' name = 'xep_0050'
@ -116,8 +96,7 @@ class XEP_0050(BasePlugin):
The replacement backend must be able to interact through The replacement backend must be able to interact through
the same syntax and interfaces as a normal dictionary. the same syntax and interfaces as a normal dictionary.
Arguments: :param db: The new session storage mechanism.
db -- The new session storage mechanism.
""" """
self.sessions = db self.sessions = db
@ -127,9 +106,8 @@ class XEP_0050(BasePlugin):
Intended to be replaced by the backend service as needed. Intended to be replaced by the backend service as needed.
Arguments: :param handlers: A list of function pointers
handlers -- A list of function pointers :param kwargs: Any additional parameters required by the backend.
**kwargs -- Any additional parameters required by the backend.
""" """
pass pass
@ -148,11 +126,10 @@ class XEP_0050(BasePlugin):
payload items of the command. All handlers will receive the command's payload items of the command. All handlers will receive the command's
session data. session data.
Arguments: :param jid: The JID that will expose the command.
jid -- The JID that will expose the command. :param node: The node associated with the command.
node -- The node associated with the command. :param name: A human readable name for the command.
name -- A human readable name for the command. :param handler: A function that will generate the response to the
handler -- A function that will generate the response to the
initial command request, as well as enforcing any initial command request, as well as enforcing any
access control policies. access control policies.
""" """
@ -212,8 +189,7 @@ class XEP_0050(BasePlugin):
""" """
Process an initial request to execute a command. Process an initial request to execute a command.
Arguments: :param iq: The command execution request.
iq -- The command execution request.
""" """
sessionid = self.new_session() sessionid = self.new_session()
node = iq['command']['node'] node = iq['command']['node']
@ -258,8 +234,7 @@ class XEP_0050(BasePlugin):
Process a request for the next step in the workflow Process a request for the next step in the workflow
for a command with multiple steps. for a command with multiple steps.
Arguments: :param iq: The command continuation request.
iq -- The command continuation request.
""" """
sessionid = iq['command']['sessionid'] sessionid = iq['command']['sessionid']
session = self.sessions.get(sessionid) session = self.sessions.get(sessionid)
@ -285,8 +260,7 @@ class XEP_0050(BasePlugin):
Process a request for the prev step in the workflow Process a request for the prev step in the workflow
for a command with multiple steps. for a command with multiple steps.
Arguments: :param iq: The command continuation request.
iq -- The command continuation request.
""" """
sessionid = iq['command']['sessionid'] sessionid = iq['command']['sessionid']
session = self.sessions.get(sessionid) session = self.sessions.get(sessionid)
@ -312,9 +286,8 @@ class XEP_0050(BasePlugin):
Generate a command reply stanza based on the Generate a command reply stanza based on the
provided session data. provided session data.
Arguments: :param iq: The command request stanza.
iq -- The command request stanza. :param session: A dictionary of relevant session data.
session -- A dictionary of relevant session data.
""" """
sessionid = session['id'] sessionid = session['id']
@ -368,8 +341,7 @@ class XEP_0050(BasePlugin):
""" """
Process a request to cancel a command's execution. Process a request to cancel a command's execution.
Arguments: :param iq: The command cancellation request.
iq -- The command cancellation request.
""" """
node = iq['command']['node'] node = iq['command']['node']
sessionid = iq['command']['sessionid'] sessionid = iq['command']['sessionid']
@ -399,7 +371,7 @@ class XEP_0050(BasePlugin):
All data related to the command session will be removed. All data related to the command session will be removed.
Arguments: Arguments:
iq -- The command completion request. :param iq: The command completion request.
""" """
node = iq['command']['node'] node = iq['command']['node']
sessionid = iq['command']['sessionid'] sessionid = iq['command']['sessionid']
@ -451,20 +423,13 @@ class XEP_0050(BasePlugin):
""" """
Return a list of commands provided by a given JID. Return a list of commands provided by a given JID.
Arguments: :param jid: The JID to query for commands.
jid -- The JID to query for commands. :param local: If true, then the query is for a JID/node
local -- If true, then the query is for a JID/node
combination handled by this Slixmpp instance and combination handled by this Slixmpp instance and
no stanzas need to be sent. no stanzas need to be sent.
Otherwise, a disco stanza must be sent to the Otherwise, a disco stanza must be sent to the
remove JID to retrieve the items. remove JID to retrieve the items.
ifrom -- Specifiy the sender's JID. :param iterator: If True, return a result set iterator using
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. the XEP-0059 plugin, if the plugin is loaded.
Otherwise the parameter is ignored. Otherwise the parameter is ignored.
""" """
@ -478,26 +443,18 @@ class XEP_0050(BasePlugin):
Create and send a command stanza, without using the provided Create and send a command stanza, without using the provided
workflow management APIs. workflow management APIs.
Arguments: :param jid: The JID to send the command request or result.
jid -- The JID to send the command request or result. :param node: The node for the command.
node -- The node for the command. :param ifrom: Specify the sender's JID.
ifrom -- Specify the sender's JID. :param action: May be one of: execute, cancel, complete,
action -- May be one of: execute, cancel, complete,
or cancel. or cancel.
payload -- Either a list of payload items, or a single :param payload: Either a list of payload items, or a single
payload item such as a data form. payload item such as a data form.
sessionid -- The current session's ID value. :param sessionid: The current session's ID value.
flow -- If True, process the Iq result using the :param flow: If True, process the Iq result using the
command workflow methods contained in the command workflow methods contained in the
session instead of returning the response session instead of returning the response
stanza itself. Defaults to False. 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.
""" """
iq = self.xmpp.Iq() iq = self.xmpp.Iq()
iq['type'] = 'set' iq['type'] = 'set'
@ -522,15 +479,14 @@ class XEP_0050(BasePlugin):
Initiate executing a command provided by a remote agent. Initiate executing a command provided by a remote agent.
The provided session dictionary should contain: The provided session dictionary should contain:
next -- A handler for processing the command result.
error -- A handler for processing any error stanzas :param next: A handler for processing the command result.
:param error: A handler for processing any error stanzas
generated by the request. generated by the request.
Arguments: :param jid: The JID to send the command request.
jid -- The JID to send the command request. :param node: The node for the desired command.
node -- The node for the desired command. :param session: A dictionary of relevant session data.
session -- A dictionary of relevant session data.
ifrom -- Optionally specify the sender's JID.
""" """
session['jid'] = jid session['jid'] = jid
session['node'] = node session['node'] = node
@ -560,8 +516,7 @@ class XEP_0050(BasePlugin):
""" """
Execute the next action of the command. Execute the next action of the command.
Arguments: :param session: All stored data relevant to the current
session -- All stored data relevant to the current
command session. command session.
""" """
sessionid = 'client:' + session['id'] sessionid = 'client:' + session['id']
@ -579,8 +534,7 @@ class XEP_0050(BasePlugin):
""" """
Cancel the execution of a command. Cancel the execution of a command.
Arguments: :param session: All stored data relevant to the current
session -- All stored data relevant to the current
command session. command session.
""" """
sessionid = 'client:' + session['id'] sessionid = 'client:' + session['id']
@ -598,8 +552,7 @@ class XEP_0050(BasePlugin):
""" """
Finish the execution of a command workflow. Finish the execution of a command workflow.
Arguments: :param session: All stored data relevant to the current
session -- All stored data relevant to the current
command session. command session.
""" """
sessionid = 'client:' + session['id'] sessionid = 'client:' + session['id']
@ -618,8 +571,7 @@ class XEP_0050(BasePlugin):
Delete a command's session after a command has completed Delete a command's session after a command has completed
or an error has occurred. or an error has occurred.
Arguments: :param session: All stored data relevant to the current
session -- All stored data relevant to the current
command session. command session.
""" """
sessionid = 'client:' + session['id'] sessionid = 'client:' + session['id']
@ -635,8 +587,7 @@ class XEP_0050(BasePlugin):
Will execute the 'next' handler stored in the session Will execute the 'next' handler stored in the session
data, or the 'error' handler depending on the Iq's type. data, or the 'error' handler depending on the Iq's type.
Arguments: :param iq: The command response.
iq -- The command response.
""" """
sessionid = 'client:' + iq['command']['sessionid'] sessionid = 'client:' + iq['command']['sessionid']
pending = False pending = False

22
slixmpp/plugins/xep_0050/stanza.py
View File

@ -22,6 +22,9 @@ class Command(ElementBase):
Also see <http://xmpp.org/extensions/xep-0050.html> Also see <http://xmpp.org/extensions/xep-0050.html>
Example command stanzas: Example command stanzas:
::
<iq type="set"> <iq type="set">
<command xmlns="http://jabber.org/protocol/commands" <command xmlns="http://jabber.org/protocol/commands"
node="run_foo" node="run_foo"
@ -46,6 +49,8 @@ class Command(ElementBase):
</iq> </iq>
Stanza Interface: Stanza Interface:
::
action -- The action to perform. action -- The action to perform.
actions -- The set of allowable next actions. actions -- The set of allowable next actions.
node -- The node associated with the command. node -- The node associated with the command.
@ -53,20 +58,6 @@ class Command(ElementBase):
sessionid -- A unique identifier for a command session. sessionid -- A unique identifier for a command session.
status -- May be one of: canceled, completed, or executing. 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' name = 'command'
@ -93,8 +84,7 @@ class Command(ElementBase):
""" """
Assign the set of allowable next actions. Assign the set of allowable next actions.
Arguments: :param values: A list containing any combination of:
values -- A list containing any combination of:
'prev', 'next', and 'complete' 'prev', 'next', and 'complete'
""" """
self.del_actions() self.del_actions()

33
slixmpp/plugins/xep_0059/stanza.py
View File

@ -18,6 +18,8 @@ class Set(ElementBase):
per response or starting at certain positions. per response or starting at certain positions.
Example set stanzas: Example set stanzas:
::
<iq type="get"> <iq type="get">
<query xmlns="http://jabber.org/protocol/disco#items"> <query xmlns="http://jabber.org/protocol/disco#items">
<set xmlns="http://jabber.org/protocol/rsm"> <set xmlns="http://jabber.org/protocol/rsm">
@ -38,6 +40,8 @@ class Set(ElementBase):
</iq> </iq>
Stanza Interface: Stanza Interface:
::
first_index -- The index attribute of <first> first_index -- The index attribute of <first>
after -- The id defining from which item to start after -- The id defining from which item to start
before -- The id defining from which item to before -- The id defining from which item to
@ -48,17 +52,6 @@ class Set(ElementBase):
index -- Used to set an index to start from index -- Used to set an index to start from
count -- The number of remote items available 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' namespace = 'http://jabber.org/protocol/rsm'
@ -70,6 +63,10 @@ class Set(ElementBase):
'count', 'index', 'last', 'max'} 'count', 'index', 'last', 'max'}
def set_first_index(self, val): 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)) fi = self.xml.find("{%s}first" % (self.namespace))
if fi is not None: if fi is not None:
if val: if val:
@ -82,16 +79,26 @@ class Set(ElementBase):
self.xml.append(fi) self.xml.append(fi)
def get_first_index(self): def get_first_index(self):
"""
Returns the value of the index attribute for <first>
"""
fi = self.xml.find("{%s}first" % (self.namespace)) fi = self.xml.find("{%s}first" % (self.namespace))
if fi is not None: if fi is not None:
return fi.attrib.get('index', '') return fi.attrib.get('index', '')
def del_first_index(self): def del_first_index(self):
"""
Removes the index attribute for <first> but keeps the element
"""
fi = self.xml.find("{%s}first" % (self.namespace)) fi = self.xml.find("{%s}first" % (self.namespace))
if fi is not None: if fi is not None:
del fi.attrib['index'] del fi.attrib['index']
def set_before(self, val): 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)) b = self.xml.find("{%s}before" % (self.namespace))
if b is None and val is True: if b is None and val is True:
self._set_sub_text('{%s}before' % self.namespace, '', 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) self._set_sub_text('{%s}before' % self.namespace, val)
def get_before(self): 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)) b = self.xml.find("{%s}before" % (self.namespace))
if b is not None and not b.text: if b is not None and not b.text:
return True return True

117
slixmpp/plugins/xep_0060/pubsub.py
View File

@ -144,9 +144,8 @@ class XEP_0060(BasePlugin):
when the respective notifications are received from the node when the respective notifications are received from the node
'http://jabber.org/protocol/tune', among other events. 'http://jabber.org/protocol/tune', among other events.
Arguments: :param node: The node name to map to an event.
node -- The node name to map to an event. :param event_name: The name of the event to raise when a
event_name -- The name of the event to raise when a
notification from the given node is received. notification from the given node is received.
""" """
self.node_event_map[node] = event_name 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 the server's default configuration. To get the default configuration
use get_node_config(). use get_node_config().
Arguments: :param jid: The JID of the pubsub service.
jid -- The JID of the pubsub service. :param node: Optional name of the node to create. If no name is
node -- Optional name of the node to create. If no name is
provided, the server MAY generate a node ID for you. provided, the server MAY generate a node ID for you.
The server can also assign a different name than the The server can also assign a different name than the
one you provide; check the result stanza to see if one you provide; check the result stanza to see if
the server assigned a name. the server assigned a name.
config -- Optional XEP-0004 data form of configuration settings. :param config: Optional XEP-0004 data form of configuration settings.
ntype -- The type of node to create. Servers typically default :param ntype: The type of node to create. Servers typically default
to using 'leaf' if no type is provided. 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.
""" """
iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='set') iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='set')
iq['pubsub']['create']['node'] = node iq['pubsub']['create']['node'] = node
@ -211,20 +203,12 @@ class XEP_0060(BasePlugin):
2. If ifrom was given, use the bare or full version based on bare. 2. If ifrom was given, use the bare or full version based on bare.
3. Otherwise, use self.xmpp.boundjid based on bare. 3. Otherwise, use self.xmpp.boundjid based on bare.
Arguments: :param jid: The pubsub service JID.
jid -- The pubsub service JID. :param node: The node to subscribe to.
node -- The node to subscribe to. :param bare: Indicates if the subscribee is a bare or full JID.
bare -- Indicates if the subscribee is a bare or full JID.
Defaults to True for a bare JID. Defaults to True for a bare JID.
subscribee -- The JID that is subscribing to the node. :param subscribee: The JID that is subscribing to the node.
options -- :param 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.
""" """
iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='set') iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='set')
iq['pubsub']['subscribe']['node'] = node iq['pubsub']['subscribe']['node'] = node
@ -258,21 +242,13 @@ class XEP_0060(BasePlugin):
2. If ifrom was given, use the bare or full version based on bare. 2. If ifrom was given, use the bare or full version based on bare.
3. Otherwise, use self.xmpp.boundjid based on bare. 3. Otherwise, use self.xmpp.boundjid based on bare.
Arguments: :param jid: The pubsub service JID.
jid -- The pubsub service JID. :param node: The node to unsubscribe from.
node -- The node to unsubscribe from. :param subid: The specific subscription, if multiple subscriptions
subid -- The specific subscription, if multiple subscriptions
exist for this JID/node combination. exist for this JID/node combination.
bare -- Indicates if the subscribee is a bare or full JID. :param bare: Indicates if the subscribee is a bare or full JID.
Defaults to True for a bare JID. Defaults to True for a bare JID.
subscribee -- The JID that is unsubscribing from the node. :param 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.
""" """
iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='set') iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='set')
iq['pubsub']['unsubscribe']['node'] = node iq['pubsub']['unsubscribe']['node'] = node
@ -332,17 +308,10 @@ class XEP_0060(BasePlugin):
Retrieve the configuration for a node, or the pubsub service's Retrieve the configuration for a node, or the pubsub service's
default configuration for new nodes. default configuration for new nodes.
Arguments: :param jid: The JID of the pubsub service.
jid -- The JID of the pubsub service. :param node: The node to retrieve the configuration for. If None,
node -- The node to retrieve the configuration for. If None,
the default configuration for new nodes will be the default configuration for new nodes will be
requested. Defaults to None. 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.
""" """
iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='get') iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='get')
if node is None: if node is None:
@ -357,15 +326,8 @@ class XEP_0060(BasePlugin):
""" """
Retrieve the subscriptions associated with a given node. Retrieve the subscriptions associated with a given node.
Arguments: :param jid: The JID of the pubsub service.
jid -- The JID of the pubsub service. :param node: The node to retrieve subscriptions from.
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.
""" """
iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='get') iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='get')
iq['pubsub_owner']['subscriptions']['node'] = node iq['pubsub_owner']['subscriptions']['node'] = node
@ -376,15 +338,8 @@ class XEP_0060(BasePlugin):
""" """
Retrieve the affiliations associated with a given node. Retrieve the affiliations associated with a given node.
Arguments: :param jid: The JID of the pubsub service.
jid -- The JID of the pubsub service. :param node: The node to retrieve affiliations from.
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.
""" """
iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='get') iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='get')
iq['pubsub_owner']['affiliations']['node'] = node iq['pubsub_owner']['affiliations']['node'] = node
@ -395,15 +350,8 @@ class XEP_0060(BasePlugin):
""" """
Delete a a pubsub node. Delete a a pubsub node.
Arguments: :param jid: The JID of the pubsub service.
jid -- The JID of the pubsub service. :param node: The node to delete.
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.
""" """
iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='set') iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='set')
iq['pubsub_owner']['delete']['node'] = node iq['pubsub_owner']['delete']['node'] = node
@ -433,18 +381,11 @@ class XEP_0060(BasePlugin):
the options as preconditions that the node's settings the options as preconditions that the node's settings
must match. must match.
Arguments: :param jid: The JID of the pubsub service.
jid -- The JID of the pubsub service. :param node: The node to publish the item to.
node -- The node to publish the item to. :param id: Optionally specify the ID of the item.
id -- Optionally specify the ID of the item. :param payload: The item content to publish.
payload -- The item content to publish. :param options: A form of publish options.
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.
""" """
iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='set') iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='set')
iq['pubsub']['publish']['node'] = node iq['pubsub']['publish']['node'] = node

30
slixmpp/plugins/xep_0066/oob.py
View File

@ -36,10 +36,6 @@ class XEP_0066(BasePlugin):
Events: Events:
oob_transfer -- Raised when a request to download a resource oob_transfer -- Raised when a request to download a resource
has been received. has been received.
Methods:
send_oob -- Send a request to another entity to download a file
or other addressable resource.
""" """
name = 'xep_0066' name = 'xep_0066'
@ -76,9 +72,8 @@ class XEP_0066(BasePlugin):
Register a handler to process download requests, either for all Register a handler to process download requests, either for all
JIDs or a single JID. JIDs or a single JID.
Arguments: :param jid: If None, then set the handler as a global default.
jid -- If None, then set the handler as a global default. :param handler: If None, then remove the existing handler for the
handler -- If None, then remove the existing handler for the
given JID, or reset the global handler if the JID given JID, or reset the global handler if the JID
is None. is None.
""" """
@ -98,17 +93,9 @@ class XEP_0066(BasePlugin):
Initiate a basic file transfer by sending the URL of Initiate a basic file transfer by sending the URL of
a file or other resource. a file or other resource.
Arguments: :param url: The URL of the resource to transfer.
url -- The URL of the resource to transfer. :param desc: An optional human readable description of the item
desc -- An optional human readable description of the item
that is to be transferred. 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.
""" """
iq = self.xmpp.Iq() iq = self.xmpp.Iq()
iq['type'] = 'set' iq['type'] = 'set'
@ -122,8 +109,7 @@ class XEP_0066(BasePlugin):
""" """
Execute the appropriate handler for a transfer request. Execute the appropriate handler for a transfer request.
Arguments: :param iq: The Iq stanza containing the OOB transfer request.
iq -- The Iq stanza containing the OOB transfer request.
""" """
if iq['to'] in self.url_handlers['jid']: if iq['to'] in self.url_handlers['jid']:
return self.url_handlers['jid'][iq['to']](iq) 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 Register a new handler using self.register_url_handler to
screen requests and download files. screen requests and download files.
Arguments: :param iq: The Iq stanza containing the OOB transfer request.
iq -- The Iq stanza containing the OOB transfer request.
""" """
raise XMPPError('service-unavailable') raise XMPPError('service-unavailable')
@ -149,8 +134,7 @@ class XEP_0066(BasePlugin):
""" """
Handle receiving an out-of-band transfer request. Handle receiving an out-of-band transfer request.
Arguments: :param iq: An Iq stanza containing an OOB transfer request.
iq -- An Iq stanza containing an OOB transfer request.
""" """
log.debug('Received out-of-band data request for %s from %s:' % ( log.debug('Received out-of-band data request for %s from %s:' % (
iq['oob_transfer']['url'], iq['from'])) iq['oob_transfer']['url'], iq['from']))

62
slixmpp/plugins/xep_0080/geoloc.py
View File

@ -39,48 +39,40 @@ class XEP_0080(BasePlugin):
""" """
Publish the user's current location. Publish the user's current location.
Arguments: :param accuracy: Horizontal GPS error in meters.
accuracy -- Horizontal GPS error in meters. :param alt: Altitude in meters above or below sea level.
alt -- Altitude in meters above or below sea level. :param area: A named area such as a campus or neighborhood.
area -- A named area such as a campus or neighborhood. :param bearing: GPS bearing (direction in which the entity is
bearing -- GPS bearing (direction in which the entity is
heading to reach its next waypoint), measured in heading to reach its next waypoint), measured in
decimal degrees relative to true north. decimal degrees relative to true north.
building -- A specific building on a street or in an area. :param building: A specific building on a street or in an area.
country -- The nation where the user is located. :param country: The nation where the user is located.
countrycode -- The ISO 3166 two-letter country code. :param countrycode: The ISO 3166 two-letter country code.
datum -- GPS datum. :param datum: GPS datum.
description -- A natural-language name for or description of :param description: A natural-language name for or description of
the location. the location.
error -- Horizontal GPS error in arc minutes. Obsoleted by :param error: Horizontal GPS error in arc minutes. Obsoleted by
the accuracy parameter. the accuracy parameter.
floor -- A particular floor in a building. :param floor: A particular floor in a building.
lat -- Latitude in decimal degrees North. :param lat: Latitude in decimal degrees North.
locality -- A locality within the administrative region, such :param locality: A locality within the administrative region, such
as a town or city. as a town or city.
lon -- Longitude in decimal degrees East. :param lon: Longitude in decimal degrees East.
postalcode -- A code used for postal delivery. :param postalcode: A code used for postal delivery.
region -- An administrative region of the nation, such :param region: An administrative region of the nation, such
as a state or province. as a state or province.
room -- A particular room in a building. :param room: A particular room in a building.
speed -- The speed at which the entity is moving, :param speed: The speed at which the entity is moving,
in meters per second. in meters per second.
street -- A thoroughfare within the locality, or a crossing :param street: A thoroughfare within the locality, or a crossing
of two thoroughfares. of two thoroughfares.
text -- A catch-all element that captures any other :param text: A catch-all element that captures any other
information about the location. information about the location.
timestamp -- UTC timestamp specifying the moment when the :param timestamp: UTC timestamp specifying the moment when the
reading was taken. reading was taken.
uri -- A URI or URL pointing to information about :param uri: A URI or URL pointing to information about
the location. the location.
:param options: Optional form of publish options.
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.
""" """
options = kwargs.get('options', None) options = kwargs.get('options', None)
ifrom = kwargs.get('ifrom', 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): def stop(self, ifrom=None, callback=None, timeout=None, timeout_callback=None):
""" """
Clear existing user location information to stop notifications. 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() geoloc = Geoloc()
return self.xmpp['xep_0163'].publish(geoloc, return self.xmpp['xep_0163'].publish(geoloc,

30
slixmpp/plugins/xep_0080/stanza.py
View File

@ -17,6 +17,9 @@ class Geoloc(ElementBase):
geographical or physical location of an entity. (XEP-0080: User Location) geographical or physical location of an entity. (XEP-0080: User Location)
Example <geoloc> stanzas: Example <geoloc> stanzas:
::
<geoloc xmlns='http://jabber.org/protocol/geoloc'/> <geoloc xmlns='http://jabber.org/protocol/geoloc'/>
<geoloc xmlns='http://jabber.org/protocol/geoloc' xml:lang='en'> <geoloc xmlns='http://jabber.org/protocol/geoloc' xml:lang='en'>
@ -28,6 +31,8 @@ class Geoloc(ElementBase):
</geoloc> </geoloc>
Stanza Interface: Stanza Interface:
::
accuracy -- Horizontal GPS error in meters. accuracy -- Horizontal GPS error in meters.
alt -- Altitude in meters above or below sea level. alt -- Altitude in meters above or below sea level.
area -- A named area such as a campus or neighborhood. area -- A named area such as a campus or neighborhood.
@ -61,6 +66,7 @@ class Geoloc(ElementBase):
reading was taken. reading was taken.
uri -- A URI or URL pointing to information about uri -- A URI or URL pointing to information about
the location. the location.
""" """
namespace = 'http://jabber.org/protocol/geoloc' namespace = 'http://jabber.org/protocol/geoloc'
@ -83,8 +89,7 @@ class Geoloc(ElementBase):
""" """
Set the value of the <accuracy> element. Set the value of the <accuracy> element.
Arguments: :param accuracy: Horizontal GPS error in meters
accuracy -- Horizontal GPS error in meters
""" """
self._set_sub_text('accuracy', text=str(accuracy)) self._set_sub_text('accuracy', text=str(accuracy))
return self return self
@ -106,8 +111,7 @@ class Geoloc(ElementBase):
""" """
Set the value of the <alt> element. Set the value of the <alt> element.
Arguments: :param alt: Altitude in meters above or below sea level
alt -- Altitude in meters above or below sea level
""" """
self._set_sub_text('alt', text=str(alt)) self._set_sub_text('alt', text=str(alt))
return self return self
@ -129,8 +133,7 @@ class Geoloc(ElementBase):
""" """
Set the value of the <bearing> element. Set the value of the <bearing> element.
Arguments: :param bearing: GPS bearing (direction in which the entity is heading
bearing -- GPS bearing (direction in which the entity is heading
to reach its next waypoint), measured in decimal to reach its next waypoint), measured in decimal
degrees relative to true north degrees relative to true north
""" """
@ -154,8 +157,7 @@ class Geoloc(ElementBase):
""" """
Set the value of the <error> element. Set the value of the <error> element.
Arguments: :param error: Horizontal GPS error in arc minutes; this
error -- Horizontal GPS error in arc minutes; this
element is deprecated in favor of <accuracy/> element is deprecated in favor of <accuracy/>
""" """
self._set_sub_text('error', text=str(error)) self._set_sub_text('error', text=str(error))
@ -178,8 +180,7 @@ class Geoloc(ElementBase):
""" """
Set the value of the <lat> element. Set the value of the <lat> element.
Arguments: :param lat: Latitude in decimal degrees North
lat -- Latitude in decimal degrees North
""" """
self._set_sub_text('lat', text=str(lat)) self._set_sub_text('lat', text=str(lat))
return self return self
@ -201,8 +202,7 @@ class Geoloc(ElementBase):
""" """
Set the value of the <lon> element. Set the value of the <lon> element.
Arguments: :param lon: Longitude in decimal degrees East
lon -- Longitude in decimal degrees East
""" """
self._set_sub_text('lon', text=str(lon)) self._set_sub_text('lon', text=str(lon))
return self return self
@ -224,8 +224,7 @@ class Geoloc(ElementBase):
""" """
Set the value of the <speed> element. Set the value of the <speed> element.
Arguments: :param speed: The speed at which the entity is moving,
speed -- The speed at which the entity is moving,
in meters per second in meters per second
""" """
self._set_sub_text('speed', text=str(speed)) self._set_sub_text('speed', text=str(speed))
@ -248,8 +247,7 @@ class Geoloc(ElementBase):
""" """
Set the value of the <timestamp> element. Set the value of the <timestamp> element.
Arguments: :param timestamp: UTC timestamp specifying the moment when
timestamp -- UTC timestamp specifying the moment when
the reading was taken the reading was taken
""" """
self._set_sub_text('timestamp', text=str(xep_0082.datetime(timestamp))) self._set_sub_text('timestamp', text=str(xep_0082.datetime(timestamp)))

8
slixmpp/plugins/xep_0084/avatar.py
View File

@ -92,14 +92,6 @@ class XEP_0084(BasePlugin):
def stop(self, ifrom=None, callback=None, timeout=None, timeout_callback=None): def stop(self, ifrom=None, callback=None, timeout=None, timeout_callback=None):
""" """
Clear existing avatar metadata information to stop notifications. 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() metadata = MetaData()
return self.xmpp['xep_0163'].publish(metadata, return self.xmpp['xep_0163'].publish(metadata,

13
slixmpp/plugins/xep_0085/stanza.py
View File

@ -14,6 +14,9 @@ class ChatState(ElementBase):
""" """
Example chat state stanzas: Example chat state stanzas:
::
<message> <message>
<active xmlns="http://jabber.org/protocol/chatstates" /> <active xmlns="http://jabber.org/protocol/chatstates" />
</message> </message>
@ -22,16 +25,6 @@ class ChatState(ElementBase):
<paused xmlns="http://jabber.org/protocol/chatstates" /> <paused xmlns="http://jabber.org/protocol/chatstates" />
</message> </message>
Stanza Interfaces:
chat_state
Attributes:
states
Methods:
get_chat_state
set_chat_state
del_chat_state
""" """
name = '' name = ''

2
slixmpp/plugins/xep_0086/legacy_error.py
View File

@ -26,6 +26,8 @@ class XEP_0086(BasePlugin):
Also see <http://xmpp.org/extensions/xep-0086.html>. Also see <http://xmpp.org/extensions/xep-0086.html>.
Configuration Values: Configuration Values:
::
override -- Indicates if applying legacy error codes should override -- Indicates if applying legacy error codes should
be done automatically. Defaults to True. be done automatically. Defaults to True.
If False, then inserting legacy error codes can If False, then inserting legacy error codes can

12
slixmpp/plugins/xep_0086/stanza.py
View File

@ -22,6 +22,8 @@ class LegacyError(ElementBase):
Also see <http://xmpp.org/extensions/xep-0086.html>. Also see <http://xmpp.org/extensions/xep-0086.html>.
Example legacy error stanzas: Example legacy error stanzas:
::
<error xmlns="jabber:client" code="501" type="cancel"> <error xmlns="jabber:client" code="501" type="cancel">
<feature-not-implemented <feature-not-implemented
xmlns="urn:ietf:params:xml:ns:xmpp-stanzas" /> xmlns="urn:ietf:params:xml:ns:xmpp-stanzas" />
@ -32,13 +34,8 @@ class LegacyError(ElementBase):
xmlns="urn:ietf:params:xml:ns:xmpp-stanzas" /> xmlns="urn:ietf:params:xml:ns:xmpp-stanzas" />
</error> </error>
Attributes: :var error_map: A map of error conditions to error types and
error_map -- A map of error conditions to error types and
code values. code values.
Methods:
setup -- Overrides ElementBase.setup
set_condition -- Remap the type and code interfaces when a
condition is set.
""" """
name = 'legacy' name = 'legacy'
@ -79,8 +76,7 @@ class LegacyError(ElementBase):
Set the error type and code based on the given error Set the error type and code based on the given error
condition value. condition value.
Arguments: :param value: The new error condition.
value -- The new error condition.
""" """
self.parent().set_condition(value) self.parent().set_condition(value)

5
slixmpp/plugins/xep_0092/stanza.py
View File

@ -17,6 +17,8 @@ class Version(ElementBase):
that the agent is running on. that the agent is running on.
Example version stanzas: Example version stanzas:
::
<iq type="get"> <iq type="get">
<query xmlns="jabber:iq:version" /> <query xmlns="jabber:iq:version" />
</iq> </iq>
@ -30,6 +32,9 @@ class Version(ElementBase):
</iq> </iq>
Stanza Interface: Stanza Interface:
::
name -- The human readable name of the software. name -- The human readable name of the software.
version -- The specific version of the software. version -- The specific version of the software.
os -- The name of the operating system running the program. os -- The name of the operating system running the program.

21
slixmpp/plugins/xep_0107/user_mood.py
View File

@ -45,17 +45,10 @@ class XEP_0107(BasePlugin):
""" """
Publish the user's current mood. Publish the user's current mood.
Arguments: :param value: The name of the mood to publish.
value -- The name of the mood to publish. :param text: Optional natural-language description or reason
text -- Optional natural-language description or reason
for the mood. for the mood.
options -- Optional form of publish options. :param 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.
""" """
mood = UserMood() mood = UserMood()
mood['value'] = value mood['value'] = value
@ -69,14 +62,6 @@ class XEP_0107(BasePlugin):
timeout_callback=None): timeout_callback=None):
""" """
Clear existing user mood information to stop notifications. 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() mood = UserMood()
self.xmpp['xep_0163'].publish(mood, node=UserMood.namespace, self.xmpp['xep_0163'].publish(mood, node=UserMood.namespace,

23
slixmpp/plugins/xep_0108/user_activity.py
View File

@ -39,19 +39,12 @@ class XEP_0108(BasePlugin):
""" """
Publish the user's current activity. Publish the user's current activity.
Arguments: :param general: The required general category of the activity.
general -- The required general category of the activity. :param specific: Optional specific activity being done as part
specific -- Optional specific activity being done as part
of the general category. of the general category.
text -- Optional natural-language description or reason :param text: Optional natural-language description or reason
for the activity. for the activity.
options -- Optional form of publish options. :param 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.
""" """
activity = UserActivity() activity = UserActivity()
activity['value'] = (general, specific) activity['value'] = (general, specific)
@ -66,14 +59,6 @@ class XEP_0108(BasePlugin):
timeout_callback=None): timeout_callback=None):
""" """
Clear existing user activity information to stop notifications. 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() activity = UserActivity()
self.xmpp['xep_0163'].publish(activity, node=UserActivity.namespace, self.xmpp['xep_0163'].publish(activity, node=UserActivity.namespace,

31
slixmpp/plugins/xep_0118/user_tune.py
View File

@ -39,21 +39,14 @@ class XEP_0118(BasePlugin):
""" """
Publish the user's current tune. Publish the user's current tune.
Arguments: :param artist: The artist or performer of the song.
artist -- The artist or performer of the song. :param length: The length of the song in seconds.
length -- The length of the song in seconds. :param rating: The user's rating of the song (from 1 to 10)
rating -- The user's rating of the song (from 1 to 10) :param source: The album name, website, or other source of the song.
source -- The album name, website, or other source of the song. :param title: The title of the song.
title -- The title of the song. :param track: The song's track number, or other unique identifier.
track -- The song's track number, or other unique identifier. :param uri: A URL to more information about the song.
uri -- A URL to more information about the song. :param options: Optional form of publish options.
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.
""" """
tune = UserTune() tune = UserTune()
tune['artist'] = artist tune['artist'] = artist
@ -74,14 +67,6 @@ class XEP_0118(BasePlugin):
def stop(self, ifrom=None, callback=None, timeout=None, timeout_callback=None): def stop(self, ifrom=None, callback=None, timeout=None, timeout_callback=None):
""" """
Clear existing user tune information to stop notifications. 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() tune = UserTune()
return self.xmpp['xep_0163'].publish(tune, return self.xmpp['xep_0163'].publish(tune,

7
slixmpp/plugins/xep_0122/stanza.py
View File

@ -7,6 +7,8 @@ class FormValidation(ElementBase):
Example: Example:
::
<field var='evt.date' type='text-single' label='Event Date/Time'> <field var='evt.date' type='text-single' label='Event Date/Time'>
<validate xmlns='http://jabber.org/protocol/xdata-validate' <validate xmlns='http://jabber.org/protocol/xdata-validate'
datatype='xs:dateTime'/> datatype='xs:dateTime'/>
@ -14,8 +16,9 @@ class FormValidation(ElementBase):
</field> </field>
Questions: 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' namespace = 'http://jabber.org/protocol/xdata-validate'

37
slixmpp/plugins/xep_0128/extended_disco.py
View File

@ -8,8 +8,10 @@
import logging import logging
from typing import Optional
import slixmpp import slixmpp
from slixmpp import Iq from slixmpp import Iq, JID
from slixmpp.xmlstream import register_stanza_plugin from slixmpp.xmlstream import register_stanza_plugin
from slixmpp.plugins import BasePlugin from slixmpp.plugins import BasePlugin
from slixmpp.plugins.xep_0004 import Form 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>. Also see <http://www.xmpp.org/extensions/xep-0128.html>.
Attributes: :var disco: A reference to the XEP-0030 plugin.
disco -- A reference to the XEP-0030 plugin. :var static: Object containing the default set of static
static -- Object containing the default set of static
node handlers. 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.
""" """
name = 'xep_0128' name = 'xep_0128'
@ -67,10 +62,9 @@ class XEP_0128(BasePlugin):
Replaces any existing extended information. Replaces any existing extended information.
Arguments: :param jid: The JID to modify.
jid -- The JID to modify. :param node: The node to modify.
node -- The node to modify. :param data: Either a form, or a list of forms to use
data -- Either a form, or a list of forms to use
as extended information, replacing any as extended information, replacing any
existing extensions. existing extensions.
""" """
@ -80,20 +74,19 @@ class XEP_0128(BasePlugin):
""" """
Add additional, extended identity information to a node. Add additional, extended identity information to a node.
Arguments: :param jid: The JID to modify.
jid -- The JID to modify. :param node: The node to modify.
node -- The node to modify. :param data: Either a form, or a list of forms to add
data -- Either a form, or a list of forms to add
as extended information. as extended information.
""" """
self.api['add_extended_info'](jid, node, None, kwargs) self.api['add_extended_info'](jid, node, None, kwargs)
def del_extended_info(self, jid=None, node=None, **kwargs): def del_extended_info(self, jid: Optional[JID] = None,
node: Optional[str] = None, **kwargs):
""" """
Remove all extended identity information to a node. Remove all extended identity information to a node.
Arguments: :param jid: The JID to modify.
jid -- The JID to modify. :param node: The node to modify.
node -- The node to modify.
""" """
self.api['del_extended_info'](jid, node, None, kwargs) self.api['del_extended_info'](jid, node, None, kwargs)

36
slixmpp/plugins/xep_0152/reachability.py
View File

@ -8,8 +8,11 @@
import logging import logging
from slixmpp import JID
from typing import Dict, List, Optional, Callable
from slixmpp.plugins.base import BasePlugin from slixmpp.plugins.base import BasePlugin
from slixmpp.plugins.xep_0152 import stanza, Reachability from slixmpp.plugins.xep_0152 import stanza, Reachability
from slixmpp.plugins.xep_0004 import Form
log = logging.getLogger(__name__) log = logging.getLogger(__name__)
@ -33,22 +36,18 @@ class XEP_0152(BasePlugin):
def session_bind(self, jid): def session_bind(self, jid):
self.xmpp['xep_0163'].register_pep('reachability', Reachability) self.xmpp['xep_0163'].register_pep('reachability', Reachability)
def publish_reachability(self, addresses, options=None, ifrom=None, def publish_reachability(self, addresses: List[Dict[str, str]],
callback=None, timeout=None, options: Optional[Form] = None,
timeout_callback=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. Publish alternative addresses where the user can be reached.
Arguments: :param addresses: A list of dictionaries containing the URI and
addresses -- A list of dictionaries containing the URI and
optional description for each address. optional description for each address.
options -- Optional form of publish options. :param 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.
""" """
if not isinstance(addresses, (list, tuple)): if not isinstance(addresses, (list, tuple)):
addresses = [addresses] addresses = [addresses]
@ -69,17 +68,12 @@ class XEP_0152(BasePlugin):
timeout=timeout, timeout=timeout,
timeout_callback=timeout_callback) 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. 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() reach = Reachability()
return self.xmpp['xep_0163'].publish(reach, return self.xmpp['xep_0163'].publish(reach,

44
slixmpp/plugins/xep_0163.py
View File

@ -8,9 +8,11 @@
import logging import logging
from slixmpp import asyncio from typing import Optional, Callable
from slixmpp.xmlstream import register_stanza_plugin from slixmpp import asyncio, JID
from slixmpp.xmlstream import register_stanza_plugin, ElementBase
from slixmpp.plugins.base import BasePlugin, register_plugin from slixmpp.plugins.base import BasePlugin, register_plugin
from slixmpp.plugins.xep_0004.stanza import Form
log = logging.getLogger(__name__) log = logging.getLogger(__name__)
@ -45,16 +47,15 @@ class XEP_0163(BasePlugin):
self.xmpp['xep_0030'].add_feature(stanza.namespace) self.xmpp['xep_0030'].add_feature(stanza.namespace)
self.xmpp['xep_0060'].map_node_event(stanza.namespace, name) 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 Mark an interest in a PEP subscription by including a disco
feature with the '+notify' extension. feature with the '+notify' extension.
Arguments: :param namespace: The base namespace to register as an interest, such
namespace -- The base namespace to register as an interest, such
as 'http://jabber.org/protocol/tune'. This may also as 'http://jabber.org/protocol/tune'. This may also
be a list of such namespaces. be a list of such namespaces.
jid -- Optionally specify the JID. :param jid: Optionally specify the JID.
""" """
if not isinstance(namespace, set) and not isinstance(namespace, list): if not isinstance(namespace, set) and not isinstance(namespace, list):
namespace = [namespace] namespace = [namespace]
@ -67,16 +68,15 @@ class XEP_0163(BasePlugin):
loop=self.xmpp.loop, 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 Mark an interest in a PEP subscription by including a disco
feature with the '+notify' extension. feature with the '+notify' extension.
Arguments: :param namespace: The base namespace to remove as an interest, such
namespace -- The base namespace to remove as an interest, such
as 'http://jabber.org/protocol/tune'. This may also as 'http://jabber.org/protocol/tune'. This may also
be a list of such namespaces. be a list of such namespaces.
jid -- Optionally specify the JID. :param jid: Optionally specify the JID.
""" """
if not isinstance(namespace, (set, list)): if not isinstance(namespace, (set, list)):
namespace = [namespace] namespace = [namespace]
@ -89,26 +89,24 @@ class XEP_0163(BasePlugin):
loop=self.xmpp.loop, loop=self.xmpp.loop,
) )
def publish(self, stanza, node=None, id=None, options=None, ifrom=None, def publish(self, stanza: ElementBase, node: Optional[str] = None,
timeout_callback=None, callback=None, timeout=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. Publish a PEP update.
This is just a (very) thin wrapper around the XEP-0060 publish() This is just a (very) thin wrapper around the XEP-0060 publish()
method to set the defaults expected by PEP. method to set the defaults expected by PEP.
Arguments: :param stanza: The PEP update stanza to publish.
stanza -- The PEP update stanza to publish. :param node: The node to publish the item to. If not specified,
node -- The node to publish the item to. If not specified,
the stanza's namespace will be used. the stanza's namespace will be used.
id -- Optionally specify the ID of the item. :param id: Optionally specify the ID of the item.
options -- A form of publish options. :param 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.
""" """
if node is None: if node is None:
node = stanza.namespace node = stanza.namespace

11
slixmpp/plugins/xep_0172/stanza.py
View File

@ -24,6 +24,9 @@ class UserNick(ElementBase):
the same as the nickname used in a MUC. the same as the nickname used in a MUC.
Example stanzas: Example stanzas:
::
<message to="user@example.com"> <message to="user@example.com">
<nick xmlns="http://jabber.org/nick/nick">The User</nick> <nick xmlns="http://jabber.org/nick/nick">The User</nick>
<body>...</body> <body>...</body>
@ -34,13 +37,11 @@ class UserNick(ElementBase):
</presence> </presence>
Stanza Interface: Stanza Interface:
::
nick -- A global, friendly or informal name chosen by a user. 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' namespace = 'http://jabber.org/protocol/nick'

35
slixmpp/plugins/xep_0172/user_nick.py
View File

@ -8,6 +8,8 @@
import logging import logging
from typing import Optional, Callable
from slixmpp import JID
from slixmpp.stanza.message import Message from slixmpp.stanza.message import Message
from slixmpp.stanza.presence import Presence from slixmpp.stanza.presence import Presence
from slixmpp.xmlstream import register_stanza_plugin 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.xmlstream.matcher import MatchXPath
from slixmpp.plugins.base import BasePlugin from slixmpp.plugins.base import BasePlugin
from slixmpp.plugins.xep_0172 import stanza, UserNick from slixmpp.plugins.xep_0172 import stanza, UserNick
from slixmpp.plugins.xep_0004.stanza import Form
log = logging.getLogger(__name__) log = logging.getLogger(__name__)
@ -42,20 +45,17 @@ class XEP_0172(BasePlugin):
def session_bind(self, jid): def session_bind(self, jid):
self.xmpp['xep_0163'].register_pep('user_nick', UserNick) self.xmpp['xep_0163'].register_pep('user_nick', UserNick)
def publish_nick(self, nick=None, options=None, ifrom=None, timeout_callback=None, def publish_nick(self, nick: Optional[str] = None,
callback=None, timeout=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. Publish the user's current nick.
Arguments: :param nick: The user nickname to publish.
nick -- The user nickname to publish. :param options: Optional form of publish options.
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.
""" """
nickname = UserNick() nickname = UserNick()
nickname['nick'] = nick nickname['nick'] = nick
@ -64,17 +64,12 @@ class XEP_0172(BasePlugin):
callback=callback, timeout=timeout, callback=callback, timeout=timeout,
timeout_callback=timeout_callback) 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. 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() nick = UserNick()
return self.xmpp['xep_0163'].publish(nick, node=UserNick.namespace, return self.xmpp['xep_0163'].publish(nick, node=UserNick.namespace,

51
slixmpp/plugins/xep_0196/user_gaming.py
View File

@ -8,8 +8,11 @@
import logging import logging
from slixmpp import JID
from typing import Optional, Callable
from slixmpp.plugins.base import BasePlugin from slixmpp.plugins.base import BasePlugin
from slixmpp.plugins.xep_0196 import stanza, UserGaming from slixmpp.plugins.xep_0196 import stanza, UserGaming
from slixmpp.plugins.xep_0004.stanza import Form
log = logging.getLogger(__name__) log = logging.getLogger(__name__)
@ -33,30 +36,30 @@ class XEP_0196(BasePlugin):
def session_bind(self, jid): def session_bind(self, jid):
self.xmpp['xep_0163'].register_pep('user_gaming', UserGaming) self.xmpp['xep_0163'].register_pep('user_gaming', UserGaming)
def publish_gaming(self, name=None, level=None, server_name=None, def publish_gaming(self, name: Optional[str] = None,
uri=None, character_name=None, level: Optional[str] = None,
character_profile=None, server_address=None, server_name: Optional[str] = None,
options=None, ifrom=None, callback=None, uri: Optional[str] = None,
timeout=None, timeout_callback=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. Publish the user's current gaming status.
Arguments: :param name: The name of the game.
name -- The name of the game. :param level: The user's level in the game.
level -- The user's level in the game. :param uri: A URI for the game or relevant gaming service
uri -- A URI for the game or relevant gaming service :param server_name: The name of the server where the user is playing.
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
server_address -- The hostname or IP address of the server where the
user is playing. user is playing.
character_name -- The name of the user's character in the game. :param character_name: The name of the user's character in the game.
character_profile -- A URI for a profile of the user's character. :param character_profile: A URI for a profile of the user's character.
options -- Optional form of publish options. :param 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.
""" """
gaming = UserGaming() gaming = UserGaming()
gaming['name'] = name gaming['name'] = name
@ -76,14 +79,6 @@ class XEP_0196(BasePlugin):
timeout_callback=None): timeout_callback=None):
""" """
Clear existing user gaming information to stop notifications. 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() gaming = UserGaming()
return self.xmpp['xep_0163'].publish(gaming, return self.xmpp['xep_0163'].publish(gaming,

25
slixmpp/plugins/xep_0199/ping.py
View File

@ -9,6 +9,8 @@
import time import time
import logging import logging
from typing import Optional, Callable
from slixmpp.jid import JID from slixmpp.jid import JID
from slixmpp.stanza import Iq from slixmpp.stanza import Iq
from slixmpp import asyncio from slixmpp import asyncio
@ -123,17 +125,13 @@ class XEP_0199(BasePlugin):
log.debug("Pinged by %s", iq['from']) log.debug("Pinged by %s", iq['from'])
iq.reply().send() iq.reply().send()
def send_ping(self, jid, ifrom=None, timeout=None, callback=None, def send_ping(self, jid: JID, ifrom: Optional[JID] = None,
timeout_callback=None): timeout: Optional[int] = None,
callback: Optional[Callable] = None,
timeout_callback: Optional[Callable] = None):
"""Send a ping request. """Send a ping request.
Arguments: :param jid: The JID that will receive the ping.
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.
""" """
if not timeout: if not timeout:
timeout = self.timeout timeout = self.timeout
@ -147,15 +145,12 @@ class XEP_0199(BasePlugin):
return iq.send(timeout=timeout, callback=callback, return iq.send(timeout=timeout, callback=callback,
timeout_callback=timeout_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. """Send a ping request and calculate RTT.
This is a coroutine. This is a coroutine.
Arguments: :param jid: The JID that will receive the ping.
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.
""" """
own_host = False own_host = False
if not jid: if not jid:

8
slixmpp/plugins/xep_0199/stanza.py
View File

@ -19,15 +19,11 @@ class Ping(ElementBase):
keepalive methods for detecting lost connections. keepalive methods for detecting lost connections.
Example ping stanza: Example ping stanza:
::
<iq type="get"> <iq type="get">
<ping xmlns="urn:xmpp:ping" /> <ping xmlns="urn:xmpp:ping" />
</iq> </iq>
Stanza Interface:
None
Methods:
None
""" """
name = 'ping' name = 'ping'

22
slixmpp/plugins/xep_0202/stanza.py
View File

@ -23,6 +23,8 @@ class EntityTime(ElementBase):
included. included.
Example <time> stanzas: Example <time> stanzas:
::
<iq type="result"> <iq type="result">
<time xmlns="urn:xmpp:time"> <time xmlns="urn:xmpp:time">
<utc>2011-07-03T11:37:12.234569</utc> <utc>2011-07-03T11:37:12.234569</utc>
@ -31,18 +33,11 @@ class EntityTime(ElementBase):
</iq> </iq>
Stanza Interface: Stanza Interface:
::
time -- The local time for the entity (updates utc and tzo). time -- The local time for the entity (updates utc and tzo).
utc -- The UTC equivalent to local time. utc -- The UTC equivalent to local time.
tzo -- The local timezone offset from UTC. 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' name = 'time'
@ -55,8 +50,7 @@ class EntityTime(ElementBase):
""" """
Set both the UTC and TZO fields given a time object. Set both the UTC and TZO fields given a time object.
Arguments: :param value: A datetime object or properly formatted
value -- A datetime object or properly formatted
string equivalent. string equivalent.
""" """
date = value date = value
@ -92,8 +86,7 @@ class EntityTime(ElementBase):
""" """
Set the timezone offset from UTC. Set the timezone offset from UTC.
Arguments: :param value: Either a tzinfo object or the number of
value -- Either a tzinfo object or the number of
seconds (positive or negative) to offset. seconds (positive or negative) to offset.
""" """
time = xep_0082.time(offset=value) time = xep_0082.time(offset=value)
@ -115,8 +108,7 @@ class EntityTime(ElementBase):
""" """
Set the time in UTC. Set the time in UTC.
Arguments: :param value: A datetime object or properly formatted
value -- A datetime object or properly formatted
string equivalent. string equivalent.
""" """
date = value date = value

20
slixmpp/plugins/xep_0202/time.py
View File

@ -8,6 +8,9 @@
import logging import logging
from typing import Optional
from slixmpp import JID
from slixmpp.stanza.iq import Iq from slixmpp.stanza.iq import Iq
from slixmpp.xmlstream import register_stanza_plugin from slixmpp.xmlstream import register_stanza_plugin
from slixmpp.xmlstream.handler import Callback from slixmpp.xmlstream.handler import Callback
@ -61,7 +64,7 @@ class XEP_0202(BasePlugin):
def session_bind(self, jid): def session_bind(self, jid):
self.xmpp['xep_0030'].add_feature('urn:xmpp:time') 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. 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 during plugin configuration with a function that maps JIDs to
times. times.
Arguments: :param iq: The Iq time request stanza.
iq -- The Iq time request stanza.
""" """
iq = iq.reply() iq = iq.reply()
iq['entity_time']['time'] = self.local_time(iq['to']) iq['entity_time']['time'] = self.local_time(iq['to'])
iq.send() 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. Request the time from another entity.
Arguments: :param to: JID of the entity to query.
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.
""" """
iq = self.xmpp.Iq() iq = self.xmpp.Iq()
iq['type'] = 'get' iq['type'] = 'get'

47
slixmpp/plugins/xep_0222.py
View File

@ -8,8 +8,11 @@
import logging 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.base import BasePlugin, register_plugin
from slixmpp.plugins.xep_0004.stanza import Form
log = logging.getLogger(__name__) log = logging.getLogger(__name__)
@ -43,27 +46,23 @@ class XEP_0222(BasePlugin):
callback=callback, callback=callback,
timeout=timeout) timeout=timeout)
def store(self, stanza, node=None, id=None, ifrom=None, options=None, def store(self, stanza: ElementBase, node: Optional[str] = None,
callback=None, timeout=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. Store public data via PEP.
This is just a (very) thin wrapper around the XEP-0060 publish() This is just a (very) thin wrapper around the XEP-0060 publish()
method to set the defaults expected by PEP. method to set the defaults expected by PEP.
Arguments: :param stanza: The private content to store.
stanza -- The private content to store. :param node: The node to publish the content to. If not specified,
node -- The node to publish the content to. If not specified,
the stanza's namespace will be used. the stanza's namespace will be used.
id -- Optionally specify the ID of the item. :param id: Optionally specify the ID of the item.
options -- Publish options to use, which will be modified to :param options: Publish options to use, which will be modified to
fit the persistent storage option profile. 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: if not options:
options = self.xmpp['xep_0004'].stanza.Form() options = self.xmpp['xep_0004'].stanza.Form()
@ -85,24 +84,26 @@ class XEP_0222(BasePlugin):
callback=callback, callback=callback,
timeout=timeout) timeout=timeout)
def retrieve(self, node, id=None, item_ids=None, ifrom=None, def retrieve(self, node: str, id: Optional[str] = None,
callback=None, timeout=None): item_ids: Optional[List[str]] = None,
ifrom: Optional[JID] = None,
callback: Optional[Callable] = None,
timeout: Optional[int] = None):
""" """
Retrieve public data via PEP. Retrieve public data via PEP.
This is just a (very) thin wrapper around the XEP-0060 publish() This is just a (very) thin wrapper around the XEP-0060 publish()
method to set the defaults expected by PEP. method to set the defaults expected by PEP.
Arguments: :param node: The node to retrieve content from.
node -- The node to retrieve content from. :param id: Optionally specify the ID of the item.
id -- Optionally specify the ID of the item. :param item_ids: Specify a group of IDs. If id is also specified, it
item_ids -- Specify a group of IDs. If id is also specified, it
will be included in item_ids. will be included in item_ids.
ifrom -- Specify the sender's JID. :param ifrom: Specify the sender's JID.
timeout -- The length of time (in seconds) to wait for a response :param timeout: The length of time (in seconds) to wait for a response
before exiting the send call if blocking is used. before exiting the send call if blocking is used.
Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT
callback -- Optional reference to a stream handler function. Will :param callback: Optional reference to a stream handler function. Will
be executed when a reply stanza is received. be executed when a reply stanza is received.
""" """
if item_ids is None: if item_ids is None:

49
slixmpp/plugins/xep_0223.py
View File

@ -8,8 +8,11 @@
import logging 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.base import BasePlugin, register_plugin
from slixmpp.plugins.xep_0004.stanza import Form
log = logging.getLogger(__name__) log = logging.getLogger(__name__)
@ -44,27 +47,24 @@ class XEP_0223(BasePlugin):
callback=callback, callback=callback,
timeout=timeout) timeout=timeout)
def store(self, stanza, node=None, id=None, ifrom=None, options=None, def store(self, stanza: ElementBase, node: Optional[str] = None,
callback=None, timeout=None, timeout_callback=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. Store private data via PEP.
This is just a (very) thin wrapper around the XEP-0060 publish() This is just a (very) thin wrapper around the XEP-0060 publish()
method to set the defaults expected by PEP. method to set the defaults expected by PEP.
Arguments: :param stanza: The private content to store.
stanza -- The private content to store. :param node: The node to publish the content to. If not specified,
node -- The node to publish the content to. If not specified,
the stanza's namespace will be used. the stanza's namespace will be used.
id -- Optionally specify the ID of the item. :param id: Optionally specify the ID of the item.
options -- Publish options to use, which will be modified to :param options: Publish options to use, which will be modified to
fit the persistent storage option profile. 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: if not options:
options = self.xmpp['xep_0004'].stanza.Form() options = self.xmpp['xep_0004'].stanza.Form()
@ -85,24 +85,27 @@ class XEP_0223(BasePlugin):
timeout=timeout, timeout=timeout,
timeout_callback=timeout_callback) timeout_callback=timeout_callback)
def retrieve(self, node, id=None, item_ids=None, ifrom=None, def retrieve(self, node: str, id: Optional[str] = None,
callback=None, timeout=None, timeout_callback=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. Retrieve private data via PEP.
This is just a (very) thin wrapper around the XEP-0060 publish() This is just a (very) thin wrapper around the XEP-0060 publish()
method to set the defaults expected by PEP. method to set the defaults expected by PEP.
Arguments: :param node: The node to retrieve content from.
node -- The node to retrieve content from. :param id: Optionally specify the ID of the item.
id -- Optionally specify the ID of the item. :param item_ids: Specify a group of IDs. If id is also specified, it
item_ids -- Specify a group of IDs. If id is also specified, it
will be included in item_ids. will be included in item_ids.
ifrom -- Specify the sender's JID. :param ifrom: Specify the sender's JID.
timeout -- The length of time (in seconds) to wait for a response :param timeout: The length of time (in seconds) to wait for a response
before exiting the send call if blocking is used. before exiting the send call if blocking is used.
Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT
callback -- Optional reference to a stream handler function. Will :param callback: Optional reference to a stream handler function. Will
be executed when a reply stanza is received. be executed when a reply stanza is received.
""" """
if item_ids is None: if item_ids is None:

2
slixmpp/plugins/xep_0231/stanza.py
View File

@ -1,6 +1,6 @@
""" """
Slixmpp: The Slick XMPP Library Slixmpp: The Slick XMPP Library
Copyright (C) 2012 Nathanael C. Fritz, Copyright (C) 2012 Nathanael C. Fritz
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr> Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
This file is part of Slixmpp. This file is part of Slixmpp.

24
slixmpp/plugins/xep_0249/invite.py
View File

@ -7,9 +7,10 @@
""" """
import logging import logging
from typing import Optional
import slixmpp import slixmpp
from slixmpp import Message from slixmpp import Message, JID
from slixmpp.plugins import BasePlugin from slixmpp.plugins import BasePlugin
from slixmpp.xmlstream import register_stanza_plugin from slixmpp.xmlstream import register_stanza_plugin
from slixmpp.xmlstream.handler import Callback from slixmpp.xmlstream.handler import Callback
@ -46,7 +47,7 @@ class XEP_0249(BasePlugin):
def session_bind(self, jid): def session_bind(self, jid):
self.xmpp['xep_0030'].add_feature(Invite.namespace) 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. Raise an event for all invitations received.
""" """
@ -55,25 +56,26 @@ class XEP_0249(BasePlugin):
self.xmpp.event('groupchat_direct_invite', msg) self.xmpp.event('groupchat_direct_invite', msg)
def send_invitation(self, jid, roomjid, password=None, def send_invitation(self, jid: JID, roomjid: JID,
reason=None, ifrom=None): password: Optional[str] = None,
reason: Optional[str] = None, *,
mfrom: Optional[JID] = None):
""" """
Send a direct MUC invitation to an XMPP entity. Send a direct MUC invitation to an XMPP entity.
Arguments: :param JID jid: The JID of the entity that will receive
jid -- The JID of the entity that will receive
the invitation the invitation
roomjid -- the address of the groupchat room to be joined :param JID roomjid: the address of the groupchat room to be joined
password -- a password needed for entry into a :param str password: a password needed for entry into a
password-protected room (OPTIONAL). password-protected room (OPTIONAL).
reason -- a human-readable purpose for the invitation :param str reason: a human-readable purpose for the invitation
(OPTIONAL). (OPTIONAL).
""" """
msg = self.xmpp.Message() msg = self.xmpp.Message()
msg['to'] = jid msg['to'] = jid
if ifrom is not None: if mfrom is not None:
msg['from'] = ifrom msg['from'] = mfrom
msg['groupchat_invite']['jid'] = roomjid msg['groupchat_invite']['jid'] = roomjid
if password is not None: if password is not None:
msg['groupchat_invite']['password'] = password msg['groupchat_invite']['password'] = password

6
slixmpp/plugins/xep_0249/stanza.py
View File

@ -17,6 +17,9 @@ class Invite(ElementBase):
done through the server). done through the server).
Example invite stanza: Example invite stanza:
::
<message from='crone1@shakespeare.lit/desktop' <message from='crone1@shakespeare.lit/desktop'
to='hecate@shakespeare.lit'> to='hecate@shakespeare.lit'>
<x xmlns='jabber:x:conference' <x xmlns='jabber:x:conference'
@ -26,6 +29,9 @@ class Invite(ElementBase):
</message> </message>
Stanza Interface: Stanza Interface:
::
jid -- The JID of the groupchat room jid -- The JID of the groupchat room
password -- The password used to gain entry in the room password -- The password used to gain entry in the room
(optional) (optional)

2
slixmpp/plugins/xep_0332/stanza/request.py
View File

@ -19,6 +19,8 @@ class HTTPRequest(ElementBase):
element to the server. Each `iq` stanza sent is of type `set`. element to the server. Each `iq` stanza sent is of type `set`.
Examples: Examples:
::
<iq type='set' from='a@b.com/browser' to='x@y.com' id='1'> <iq type='set' from='a@b.com/browser' to='x@y.com' id='1'>
<req xmlns='urn:xmpp:http' <req xmlns='urn:xmpp:http'
method='GET' method='GET'

2
slixmpp/plugins/xep_0332/stanza/response.py
View File

@ -21,6 +21,8 @@ class HTTPResponse(ElementBase):
in which the original requests were made. in which the original requests were made.
Examples: Examples:
::
<iq type='result' <iq type='result'
from='httpserver@clayster.com' from='httpserver@clayster.com'
to='httpclient@clayster.com/browser' id='2'> to='httpclient@clayster.com/browser' id='2'>

3
slixmpp/plugins/xep_0369/mix_core.py
View File

@ -79,7 +79,8 @@ class XEP_0369(BasePlugin):
async def get_channel_info(self, channel: JID) -> InfoType: async def get_channel_info(self, channel: JID) -> InfoType:
"""" """"
Get the contents of the channel info node. 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 :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)
""" """

3
slixmpp/plugins/xep_0377/stanza.py
View File

@ -14,6 +14,7 @@ class Report(ElementBase):
A spam/abuse report. A spam/abuse report.
Example sub stanza: Example sub stanza:
::
<report xmlns="urn:xmpp:reporting:0"> <report xmlns="urn:xmpp:reporting:0">
<text xml:lang="en"> <text xml:lang="en">
@ -23,6 +24,8 @@ class Report(ElementBase):
</report> </report>
Stanza Interface: Stanza Interface:
::
abuse -- Flag the report as abuse abuse -- Flag the report as abuse
spam -- Flag the report as spam spam -- Flag the report as spam
text -- Add a reason to the report text -- Add a reason to the report

2
slixmpp/plugins/xep_0421/stanza.py
View File

@ -24,6 +24,8 @@ class OccupantId(ElementBase):
Without occupant-id, getting the following messages from MUC history would Without occupant-id, getting the following messages from MUC history would
prevent a client from asserting senders are the same entity: prevent a client from asserting senders are the same entity:
::
<message type='groupchat' from='foo@muc/nick1' id='message1'> <message type='groupchat' from='foo@muc/nick1' id='message1'>
<body>Some message</body> <body>Some message</body>
<occupant-id xmlns='urn:xmpp:occupant-id:0' id='unique-opaque-id1'/> <occupant-id xmlns='urn:xmpp:occupant-id:0' id='unique-opaque-id1'/>

3
slixmpp/plugins/xep_0424/retraction.py
View File

@ -43,11 +43,12 @@ class XEP_0424(BasePlugin):
mfrom: Optional[JID] = None): mfrom: Optional[JID] = None):
""" """
Send a message retraction Send a message retraction
:param JID mto: The JID to retract the message from :param JID mto: The JID to retract the message from
:param str id: Message ID to retract :param str id: Message ID to retract
:param str mtype: Message type :param str mtype: Message type
:param bool include_fallback: Whether to include a fallback body :param bool include_fallback: Whether to include a fallback body
:param Optional[str] fallback_text: The contet of the fallback :param Optional[str] fallback_text: The content of the fallback
body. None will set the default value. body. None will set the default value.
""" """
if fallback_text is None: if fallback_text is None:

2
slixmpp/xmlstream/tostring.py
View File

@ -1,7 +1,7 @@
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
""" """
slixmpp.xmlstream.tostring slixmpp.xmlstream.tostring
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~
This module converts XML objects into Unicode strings and This module converts XML objects into Unicode strings and
intelligently includes namespaces only when necessary to intelligently includes namespaces only when necessary to

1
slixmpp/xmlstream/xmlstream.py
View File

@ -261,7 +261,6 @@ class XMLStream(asyncio.BaseProtocol):
connection will be upgraded to SSL/TLS later, using connection will be upgraded to SSL/TLS later, using
STARTTLS. Only use this value for old servers that STARTTLS. Only use this value for old servers that
have specific port for SSL/TLS have specific port for SSL/TLS
TODO fix the comment
:param force_starttls: If True, the connection will be aborted if :param force_starttls: If True, the connection will be aborted if
the server does not initiate a STARTTLS the server does not initiate a STARTTLS
negotiation. If None, the connection will be negotiation. If None, the connection will be