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

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

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

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

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

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

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

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

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

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>
Example command stanzas:
::
<iq type="set">
<command xmlns="http://jabber.org/protocol/commands"
node="run_foo"
@ -46,6 +49,8 @@ class Command(ElementBase):
</iq>
Stanza Interface:
::
action -- The action to perform.
actions -- The set of allowable next actions.
node -- The node associated with the command.
@ -53,20 +58,6 @@ class Command(ElementBase):
sessionid -- A unique identifier for a command session.
status -- May be one of: canceled, completed, or executing.
Attributes:
actions -- A set of allowed action values.
statuses -- A set of allowed status values.
next_actions -- A set of allowed next action names.
Methods:
get_action -- Return the requested action.
get_actions -- Return the allowable next actions.
set_actions -- Set the allowable next actions.
del_actions -- Remove the current set of next actions.
get_notes -- Return a list of informative note data.
set_notes -- Set informative notes.
del_notes -- Remove any note data.
add_note -- Add a single note.
"""
name = 'command'
@ -93,8 +84,7 @@ class Command(ElementBase):
"""
Assign the set of allowable next actions.
Arguments:
values -- A list containing any combination of:
:param values: A list containing any combination of:
'prev', 'next', and 'complete'
"""
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.
Example set stanzas:
::
<iq type="get">
<query xmlns="http://jabber.org/protocol/disco#items">
<set xmlns="http://jabber.org/protocol/rsm">
@ -38,6 +40,8 @@ class Set(ElementBase):
</iq>
Stanza Interface:
::
first_index -- The index attribute of <first>
after -- The id defining from which item to start
before -- The id defining from which item to
@ -48,17 +52,6 @@ class Set(ElementBase):
index -- Used to set an index to start from
count -- The number of remote items available
Methods:
set_first_index -- Sets the index attribute for <first> and
creates the element if it doesn't exist
get_first_index -- Returns the value of the index
attribute for <first>
del_first_index -- Removes the index attribute for <first>
but keeps the element
set_before -- Sets the value of <before>, if the value is True
then the element will be created without a value
get_before -- Returns the value of <before>, if it is
empty it will return True
"""
namespace = 'http://jabber.org/protocol/rsm'
@ -70,6 +63,10 @@ class Set(ElementBase):
'count', 'index', 'last', 'max'}
def set_first_index(self, val):
"""
Sets the index attribute for <first> and
creates the element if it doesn't exist
"""
fi = self.xml.find("{%s}first" % (self.namespace))
if fi is not None:
if val:
@ -82,16 +79,26 @@ class Set(ElementBase):
self.xml.append(fi)
def get_first_index(self):
"""
Returns the value of the index attribute for <first>
"""
fi = self.xml.find("{%s}first" % (self.namespace))
if fi is not None:
return fi.attrib.get('index', '')
def del_first_index(self):
"""
Removes the index attribute for <first> but keeps the element
"""
fi = self.xml.find("{%s}first" % (self.namespace))
if fi is not None:
del fi.attrib['index']
def set_before(self, val):
"""
Sets the value of <before>, if the value is True
then the element will be created without a value
"""
b = self.xml.find("{%s}before" % (self.namespace))
if b is None and val is True:
self._set_sub_text('{%s}before' % self.namespace, '', True)
@ -99,6 +106,10 @@ class Set(ElementBase):
self._set_sub_text('{%s}before' % self.namespace, val)
def get_before(self):
"""
Returns the value of <before>, if it is
empty it will return True
"""
b = self.xml.find("{%s}before" % (self.namespace))
if b is not None and not b.text:
return True

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

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

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

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

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

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)
Example <geoloc> stanzas:
::
<geoloc xmlns='http://jabber.org/protocol/geoloc'/>
<geoloc xmlns='http://jabber.org/protocol/geoloc' xml:lang='en'>
@ -28,6 +31,8 @@ class Geoloc(ElementBase):
</geoloc>
Stanza Interface:
::
accuracy -- Horizontal GPS error in meters.
alt -- Altitude in meters above or below sea level.
area -- A named area such as a campus or neighborhood.
@ -61,6 +66,7 @@ class Geoloc(ElementBase):
reading was taken.
uri -- A URI or URL pointing to information about
the location.
"""
namespace = 'http://jabber.org/protocol/geoloc'
@ -83,8 +89,7 @@ class Geoloc(ElementBase):
"""
Set the value of the <accuracy> element.
Arguments:
accuracy -- Horizontal GPS error in meters
:param accuracy: Horizontal GPS error in meters
"""
self._set_sub_text('accuracy', text=str(accuracy))
return self
@ -106,8 +111,7 @@ class Geoloc(ElementBase):
"""
Set the value of the <alt> element.
Arguments:
alt -- Altitude in meters above or below sea level
:param alt: Altitude in meters above or below sea level
"""
self._set_sub_text('alt', text=str(alt))
return self
@ -129,8 +133,7 @@ class Geoloc(ElementBase):
"""
Set the value of the <bearing> element.
Arguments:
bearing -- GPS bearing (direction in which the entity is heading
:param bearing: GPS bearing (direction in which the entity is heading
to reach its next waypoint), measured in decimal
degrees relative to true north
"""
@ -154,8 +157,7 @@ class Geoloc(ElementBase):
"""
Set the value of the <error> element.
Arguments:
error -- Horizontal GPS error in arc minutes; this
:param error: Horizontal GPS error in arc minutes; this
element is deprecated in favor of <accuracy/>
"""
self._set_sub_text('error', text=str(error))
@ -178,8 +180,7 @@ class Geoloc(ElementBase):
"""
Set the value of the <lat> element.
Arguments:
lat -- Latitude in decimal degrees North
:param lat: Latitude in decimal degrees North
"""
self._set_sub_text('lat', text=str(lat))
return self
@ -201,8 +202,7 @@ class Geoloc(ElementBase):
"""
Set the value of the <lon> element.
Arguments:
lon -- Longitude in decimal degrees East
:param lon: Longitude in decimal degrees East
"""
self._set_sub_text('lon', text=str(lon))
return self
@ -224,8 +224,7 @@ class Geoloc(ElementBase):
"""
Set the value of the <speed> element.
Arguments:
speed -- The speed at which the entity is moving,
:param speed: The speed at which the entity is moving,
in meters per second
"""
self._set_sub_text('speed', text=str(speed))
@ -248,8 +247,7 @@ class Geoloc(ElementBase):
"""
Set the value of the <timestamp> element.
Arguments:
timestamp -- UTC timestamp specifying the moment when
:param timestamp: UTC timestamp specifying the moment when
the reading was taken
"""
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):
"""
Clear existing avatar metadata information to stop notifications.
Arguments:
ifrom -- Specify the sender's JID.
timeout -- The length of time (in seconds) to wait for a response
before exiting the send call if blocking is used.
Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT
callback -- Optional reference to a stream handler function. Will
be executed when a reply stanza is received.
"""
metadata = MetaData()
return self.xmpp['xep_0163'].publish(metadata,

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

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

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>.
Configuration Values:
::
override -- Indicates if applying legacy error codes should
be done automatically. Defaults to True.
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>.
Example legacy error stanzas:
::
<error xmlns="jabber:client" code="501" type="cancel">
<feature-not-implemented
xmlns="urn:ietf:params:xml:ns:xmpp-stanzas" />
@ -32,13 +34,8 @@ class LegacyError(ElementBase):
xmlns="urn:ietf:params:xml:ns:xmpp-stanzas" />
</error>
Attributes:
error_map -- A map of error conditions to error types and
:var error_map: A map of error conditions to error types and
code values.
Methods:
setup -- Overrides ElementBase.setup
set_condition -- Remap the type and code interfaces when a
condition is set.
"""
name = 'legacy'
@ -79,8 +76,7 @@ class LegacyError(ElementBase):
Set the error type and code based on the given error
condition value.
Arguments:
value -- The new error condition.
:param value: The new error condition.
"""
self.parent().set_condition(value)

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

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

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

@ -45,17 +45,10 @@ class XEP_0107(BasePlugin):
"""
Publish the user's current mood.
Arguments:
value -- The name of the mood to publish.
text -- Optional natural-language description or reason
:param value: The name of the mood to publish.
:param text: Optional natural-language description or reason
for the mood.
options -- Optional form of publish options.
ifrom -- Specify the sender's JID.
timeout -- The length of time (in seconds) to wait for a response
before exiting the send call if blocking is used.
Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT
callback -- Optional reference to a stream handler function. Will
be executed when a reply stanza is received.
:param options: Optional form of publish options.
"""
mood = UserMood()
mood['value'] = value
@ -69,14 +62,6 @@ class XEP_0107(BasePlugin):
timeout_callback=None):
"""
Clear existing user mood information to stop notifications.
Arguments:
ifrom -- Specify the sender's JID.
timeout -- The length of time (in seconds) to wait for a response
before exiting the send call if blocking is used.
Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT
callback -- Optional reference to a stream handler function. Will
be executed when a reply stanza is received.
"""
mood = UserMood()
self.xmpp['xep_0163'].publish(mood, node=UserMood.namespace,

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

@ -39,19 +39,12 @@ class XEP_0108(BasePlugin):
"""
Publish the user's current activity.
Arguments:
general -- The required general category of the activity.
specific -- Optional specific activity being done as part
:param general: The required general category of the activity.
:param specific: Optional specific activity being done as part
of the general category.
text -- Optional natural-language description or reason
:param text: Optional natural-language description or reason
for the activity.
options -- Optional form of publish options.
ifrom -- Specify the sender's JID.
timeout -- The length of time (in seconds) to wait for a response
before exiting the send call if blocking is used.
Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT
callback -- Optional reference to a stream handler function. Will
be executed when a reply stanza is received.
:param options: Optional form of publish options.
"""
activity = UserActivity()
activity['value'] = (general, specific)
@ -66,14 +59,6 @@ class XEP_0108(BasePlugin):
timeout_callback=None):
"""
Clear existing user activity information to stop notifications.
Arguments:
ifrom -- Specify the sender's JID.
timeout -- The length of time (in seconds) to wait for a response
before exiting the send call if blocking is used.
Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT
callback -- Optional reference to a stream handler function. Will
be executed when a reply stanza is received.
"""
activity = UserActivity()
self.xmpp['xep_0163'].publish(activity, node=UserActivity.namespace,

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

@ -39,21 +39,14 @@ class XEP_0118(BasePlugin):
"""
Publish the user's current tune.
Arguments:
artist -- The artist or performer of the song.
length -- The length of the song in seconds.
rating -- The user's rating of the song (from 1 to 10)
source -- The album name, website, or other source of the song.
title -- The title of the song.
track -- The song's track number, or other unique identifier.
uri -- A URL to more information about the song.
options -- Optional form of publish options.
ifrom -- Specify the sender's JID.
timeout -- The length of time (in seconds) to wait for a response
before exiting the send call if blocking is used.
Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT
callback -- Optional reference to a stream handler function. Will
be executed when a reply stanza is received.
:param artist: The artist or performer of the song.
:param length: The length of the song in seconds.
:param rating: The user's rating of the song (from 1 to 10)
:param source: The album name, website, or other source of the song.
:param title: The title of the song.
:param track: The song's track number, or other unique identifier.
:param uri: A URL to more information about the song.
:param options: Optional form of publish options.
"""
tune = UserTune()
tune['artist'] = artist
@ -74,14 +67,6 @@ class XEP_0118(BasePlugin):
def stop(self, ifrom=None, callback=None, timeout=None, timeout_callback=None):
"""
Clear existing user tune information to stop notifications.
Arguments:
ifrom -- Specify the sender's JID.
timeout -- The length of time (in seconds) to wait for a response
before exiting the send call if blocking is used.
Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT
callback -- Optional reference to a stream handler function. Will
be executed when a reply stanza is received.
"""
tune = UserTune()
return self.xmpp['xep_0163'].publish(tune,

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

@ -7,6 +7,8 @@ class FormValidation(ElementBase):
Example:
::
<field var='evt.date' type='text-single' label='Event Date/Time'>
<validate xmlns='http://jabber.org/protocol/xdata-validate'
datatype='xs:dateTime'/>
@ -14,8 +16,9 @@ class FormValidation(ElementBase):
</field>
Questions:
Should this look at the datatype value and convert the range values as appropriate?
Should this stanza provide a pass/fail for a value from the field, or convert field value to datatype?
* Should this look at the datatype value and convert the range values as appropriate?
* Should this stanza provide a pass/fail for a value from the field, or convert field value to datatype?
"""
namespace = 'http://jabber.org/protocol/xdata-validate'

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

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

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

@ -8,8 +8,11 @@
import logging
from slixmpp import JID
from typing import Dict, List, Optional, Callable
from slixmpp.plugins.base import BasePlugin
from slixmpp.plugins.xep_0152 import stanza, Reachability
from slixmpp.plugins.xep_0004 import Form
log = logging.getLogger(__name__)
@ -33,22 +36,18 @@ class XEP_0152(BasePlugin):
def session_bind(self, jid):
self.xmpp['xep_0163'].register_pep('reachability', Reachability)
def publish_reachability(self, addresses, options=None, ifrom=None,
callback=None, timeout=None,
timeout_callback=None):
def publish_reachability(self, addresses: List[Dict[str, str]],
options: Optional[Form] = None,
ifrom: Optional[JID] = None,
callback: Optional[Callable] = None,
timeout: Optional[int] = None,
timeout_callback: Optional[Callable] = None):
"""
Publish alternative addresses where the user can be reached.
Arguments:
addresses -- A list of dictionaries containing the URI and
:param addresses: A list of dictionaries containing the URI and
optional description for each address.
options -- Optional form of publish options.
ifrom -- Specify the sender's JID.
timeout -- The length of time (in seconds) to wait for a response
before exiting the send call if blocking is used.
Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT
callback -- Optional reference to a stream handler function. Will
be executed when a reply stanza is received.
:param options: Optional form of publish options.
"""
if not isinstance(addresses, (list, tuple)):
addresses = [addresses]
@ -69,17 +68,12 @@ class XEP_0152(BasePlugin):
timeout=timeout,
timeout_callback=timeout_callback)
def stop(self, ifrom=None, callback=None, timeout=None, timeout_callback=None):
def stop(self, ifrom: Optional[JID] = None,
callback: Optional[Callable] = None,
timeout: Optional[int] = None,
timeout_callback: Optional[Callable] = None):
"""
Clear existing user activity information to stop notifications.
Arguments:
ifrom -- Specify the sender's JID.
timeout -- The length of time (in seconds) to wait for a response
before exiting the send call if blocking is used.
Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT
callback -- Optional reference to a stream handler function. Will
be executed when a reply stanza is received.
"""
reach = Reachability()
return self.xmpp['xep_0163'].publish(reach,

44
slixmpp/plugins/xep_0163.py
View File

@ -8,9 +8,11 @@
import logging
from slixmpp import asyncio
from slixmpp.xmlstream import register_stanza_plugin
from typing import Optional, Callable
from slixmpp import asyncio, JID
from slixmpp.xmlstream import register_stanza_plugin, ElementBase
from slixmpp.plugins.base import BasePlugin, register_plugin
from slixmpp.plugins.xep_0004.stanza import Form
log = logging.getLogger(__name__)
@ -45,16 +47,15 @@ class XEP_0163(BasePlugin):
self.xmpp['xep_0030'].add_feature(stanza.namespace)
self.xmpp['xep_0060'].map_node_event(stanza.namespace, name)
def add_interest(self, namespace, jid=None):
def add_interest(self, namespace: str, jid: Optional[JID] = None):
"""
Mark an interest in a PEP subscription by including a disco
feature with the '+notify' extension.
Arguments:
namespace -- The base namespace to register as an interest, such
:param namespace: The base namespace to register as an interest, such
as 'http://jabber.org/protocol/tune'. This may also
be a list of such namespaces.
jid -- Optionally specify the JID.
:param jid: Optionally specify the JID.
"""
if not isinstance(namespace, set) and not isinstance(namespace, list):
namespace = [namespace]
@ -67,16 +68,15 @@ class XEP_0163(BasePlugin):
loop=self.xmpp.loop,
)
def remove_interest(self, namespace, jid=None):
def remove_interest(self, namespace: str, jid: Optional[JID] = None):
"""
Mark an interest in a PEP subscription by including a disco
feature with the '+notify' extension.
Arguments:
namespace -- The base namespace to remove as an interest, such
:param namespace: The base namespace to remove as an interest, such
as 'http://jabber.org/protocol/tune'. This may also
be a list of such namespaces.
jid -- Optionally specify the JID.
:param jid: Optionally specify the JID.
"""
if not isinstance(namespace, (set, list)):
namespace = [namespace]
@ -89,26 +89,24 @@ class XEP_0163(BasePlugin):
loop=self.xmpp.loop,
)
def publish(self, stanza, node=None, id=None, options=None, ifrom=None,
timeout_callback=None, callback=None, timeout=None):
def publish(self, stanza: ElementBase, node: Optional[str] = None,
id: Optional[str] = None,
options: Optional[Form] = None,
ifrom: Optional[JID] = None,
timeout_callback: Optional[Callable] = None,
callback: Optional[Callable] = None,
timeout: Optional[int] = None):
"""
Publish a PEP update.
This is just a (very) thin wrapper around the XEP-0060 publish()
method to set the defaults expected by PEP.
Arguments:
stanza -- The PEP update stanza to publish.
node -- The node to publish the item to. If not specified,
:param stanza: The PEP update stanza to publish.
:param node: The node to publish the item to. If not specified,
the stanza's namespace will be used.
id -- Optionally specify the ID of the item.
options -- A form of publish options.
ifrom -- Specify the sender's JID.
timeout -- The length of time (in seconds) to wait for a response
before exiting the send call if blocking is used.
Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT
callback -- Optional reference to a stream handler function. Will
be executed when a reply stanza is received.
:param id: Optionally specify the ID of the item.
:param options: A form of publish options.
"""
if node is None:
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.
Example stanzas:
::
<message to="user@example.com">
<nick xmlns="http://jabber.org/nick/nick">The User</nick>
<body>...</body>
@ -34,13 +37,11 @@ class UserNick(ElementBase):
</presence>
Stanza Interface:
::
nick -- A global, friendly or informal name chosen by a user.
Methods:
setup -- Overrides ElementBase.setup.
get_nick -- Return the nickname in the <nick> element.
set_nick -- Add a <nick> element with the given nickname.
del_nick -- Remove the <nick> element.
"""
namespace = 'http://jabber.org/protocol/nick'

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

@ -8,6 +8,8 @@
import logging
from typing import Optional, Callable
from slixmpp import JID
from slixmpp.stanza.message import Message
from slixmpp.stanza.presence import Presence
from slixmpp.xmlstream import register_stanza_plugin
@ -15,6 +17,7 @@ from slixmpp.xmlstream.handler import Callback
from slixmpp.xmlstream.matcher import MatchXPath
from slixmpp.plugins.base import BasePlugin
from slixmpp.plugins.xep_0172 import stanza, UserNick
from slixmpp.plugins.xep_0004.stanza import Form
log = logging.getLogger(__name__)
@ -42,20 +45,17 @@ class XEP_0172(BasePlugin):
def session_bind(self, jid):
self.xmpp['xep_0163'].register_pep('user_nick', UserNick)
def publish_nick(self, nick=None, options=None, ifrom=None, timeout_callback=None,
callback=None, timeout=None):
def publish_nick(self, nick: Optional[str] = None,
options: Optional[Form] = None,
ifrom: Optional[JID] = None,
timeout_callback: Optional[Callable] = None,
callback: Optional[Callable] = None,
timeout: Optional[int] = None):
"""
Publish the user's current nick.
Arguments:
nick -- The user nickname to publish.
options -- Optional form of publish options.
ifrom -- Specify the sender's JID.
timeout -- The length of time (in seconds) to wait for a response
before exiting the send call if blocking is used.
Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT
callback -- Optional reference to a stream handler function. Will
be executed when a reply stanza is received.
:param nick: The user nickname to publish.
:param options: Optional form of publish options.
"""
nickname = UserNick()
nickname['nick'] = nick
@ -64,17 +64,12 @@ class XEP_0172(BasePlugin):
callback=callback, timeout=timeout,
timeout_callback=timeout_callback)
def stop(self, ifrom=None, timeout_callback=None, callback=None, timeout=None):
def stop(self, ifrom: Optional[JID] = None,
timeout_callback: Optional[Callable] = None,
callback: Optional[Callable] = None,
timeout: Optional[int] = None):
"""
Clear existing user nick information to stop notifications.
Arguments:
ifrom -- Specify the sender's JID.
timeout -- The length of time (in seconds) to wait for a response
before exiting the send call if blocking is used.
Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT
callback -- Optional reference to a stream handler function. Will
be executed when a reply stanza is received.
"""
nick = UserNick()
return self.xmpp['xep_0163'].publish(nick, node=UserNick.namespace,

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

@ -8,8 +8,11 @@
import logging
from slixmpp import JID
from typing import Optional, Callable
from slixmpp.plugins.base import BasePlugin
from slixmpp.plugins.xep_0196 import stanza, UserGaming
from slixmpp.plugins.xep_0004.stanza import Form
log = logging.getLogger(__name__)
@ -33,30 +36,30 @@ class XEP_0196(BasePlugin):
def session_bind(self, jid):
self.xmpp['xep_0163'].register_pep('user_gaming', UserGaming)
def publish_gaming(self, name=None, level=None, server_name=None,
uri=None, character_name=None,
character_profile=None, server_address=None,
options=None, ifrom=None, callback=None,
timeout=None, timeout_callback=None):
def publish_gaming(self, name: Optional[str] = None,
level: Optional[str] = None,
server_name: Optional[str] = None,
uri: Optional[str] = None,
character_name: Optional[str] = None,
character_profile: Optional[str] = None,
server_address: Optional[str] = None,
options: Optional[Form] = None,
ifrom: Optional[JID] = None,
callback: Optional[Callable] = None,
timeout: Optional[int] = None,
timeout_callback: Optional[Callable]=None):
"""
Publish the user's current gaming status.
Arguments:
name -- The name of the game.
level -- The user's level in the game.
uri -- A URI for the game or relevant gaming service
server_name -- The name of the server where the user is playing.
server_address -- The hostname or IP address of the server where the
:param name: The name of the game.
:param level: The user's level in the game.
:param uri: A URI for the game or relevant gaming service
:param server_name: The name of the server where the user is playing.
:param server_address: The hostname or IP address of the server where the
user is playing.
character_name -- The name of the user's character in the game.
character_profile -- A URI for a profile of the user's character.
options -- Optional form of publish options.
ifrom -- Specify the sender's JID.
timeout -- The length of time (in seconds) to wait for a response
before exiting the send call if blocking is used.
Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT
callback -- Optional reference to a stream handler function. Will
be executed when a reply stanza is received.
:param character_name: The name of the user's character in the game.
:param character_profile: A URI for a profile of the user's character.
:param options: Optional form of publish options.
"""
gaming = UserGaming()
gaming['name'] = name
@ -76,14 +79,6 @@ class XEP_0196(BasePlugin):
timeout_callback=None):
"""
Clear existing user gaming information to stop notifications.
Arguments:
ifrom -- Specify the sender's JID.
timeout -- The length of time (in seconds) to wait for a response
before exiting the send call if blocking is used.
Defaults to slixmpp.xmlstream.RESPONSE_TIMEOUT
callback -- Optional reference to a stream handler function. Will
be executed when a reply stanza is received.
"""
gaming = UserGaming()
return self.xmpp['xep_0163'].publish(gaming,

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

@ -9,6 +9,8 @@
import time
import logging
from typing import Optional, Callable
from slixmpp.jid import JID
from slixmpp.stanza import Iq
from slixmpp import asyncio
@ -123,17 +125,13 @@ class XEP_0199(BasePlugin):
log.debug("Pinged by %s", iq['from'])
iq.reply().send()
def send_ping(self, jid, ifrom=None, timeout=None, callback=None,
timeout_callback=None):
def send_ping(self, jid: JID, ifrom: Optional[JID] = None,
timeout: Optional[int] = None,
callback: Optional[Callable] = None,
timeout_callback: Optional[Callable] = None):
"""Send a ping request.
Arguments:
jid -- The JID that will receive the ping.
ifrom -- Specifiy the sender JID.
timeout -- Time in seconds to wait for a response.
Defaults to self.timeout.
callback -- Optional handler to execute when a pong
is received.
:param jid: The JID that will receive the ping.
"""
if not timeout:
timeout = self.timeout
@ -147,15 +145,12 @@ class XEP_0199(BasePlugin):
return iq.send(timeout=timeout, callback=callback,
timeout_callback=timeout_callback)
async def ping(self, jid=None, ifrom=None, timeout=None):
async def ping(self, jid: Optional[JID] =None,
ifrom: Optional[JID] = None, timeout: Optional[int] = None) -> float:
"""Send a ping request and calculate RTT.
This is a coroutine.
Arguments:
jid -- The JID that will receive the ping.
ifrom -- Specifiy the sender JID.
timeout -- Time in seconds to wait for a response.
Defaults to self.timeout.
:param jid: The JID that will receive the ping.
"""
own_host = False
if not jid:

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

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

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

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

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

@ -8,6 +8,9 @@
import logging
from typing import Optional
from slixmpp import JID
from slixmpp.stanza.iq import Iq
from slixmpp.xmlstream import register_stanza_plugin
from slixmpp.xmlstream.handler import Callback
@ -61,7 +64,7 @@ class XEP_0202(BasePlugin):
def session_bind(self, jid):
self.xmpp['xep_0030'].add_feature('urn:xmpp:time')
def _handle_time_request(self, iq):
def _handle_time_request(self, iq: Iq):
"""
Respond to a request for the local time.
@ -69,26 +72,17 @@ class XEP_0202(BasePlugin):
during plugin configuration with a function that maps JIDs to
times.
Arguments:
iq -- The Iq time request stanza.
:param iq: The Iq time request stanza.
"""
iq = iq.reply()
iq['entity_time']['time'] = self.local_time(iq['to'])
iq.send()
def get_entity_time(self, to, ifrom=None, **iqargs):
def get_entity_time(self, to: JID, ifrom: Optional[JID] = None, **iqargs):
"""
Request the time from another entity.
Arguments:
to -- JID of the entity to query.
ifrom -- Specifiy the sender's JID.
block -- If true, block and wait for the stanzas' reply.
timeout -- The time in seconds to block while waiting for
a reply. If None, then wait indefinitely.
callback -- Optional callback to execute when a reply is
received instead of blocking and waiting for
the reply.
:param to: JID of the entity to query.
"""
iq = self.xmpp.Iq()
iq['type'] = 'get'

47
slixmpp/plugins/xep_0222.py
View File

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

49
slixmpp/plugins/xep_0223.py
View File

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

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

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

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

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

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

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

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`.
Examples:
::
<iq type='set' from='a@b.com/browser' to='x@y.com' id='1'>
<req xmlns='urn:xmpp:http'
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.
Examples:
::
<iq type='result'
from='httpserver@clayster.com'
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:
""""
Get the contents of the channel info node.
:param JID channel: The MIX channel
:param channel: The MIX channel
:returns: a dict containing the last modified time and form contents
(Name, Description, Contact per the spec, YMMV)
"""

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

@ -14,6 +14,7 @@ class Report(ElementBase):
A spam/abuse report.
Example sub stanza:
::
<report xmlns="urn:xmpp:reporting:0">
<text xml:lang="en">
@ -23,6 +24,8 @@ class Report(ElementBase):
</report>
Stanza Interface:
::
abuse -- Flag the report as abuse
spam -- Flag the report as spam
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
prevent a client from asserting senders are the same entity:
::
<message type='groupchat' from='foo@muc/nick1' id='message1'>
<body>Some message</body>
<occupant-id xmlns='urn:xmpp:occupant-id:0' id='unique-opaque-id1'/>

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

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

2
slixmpp/xmlstream/tostring.py
View File

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

1
slixmpp/xmlstream/xmlstream.py
View File

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