summaryrefslogtreecommitdiff
path: root/sleekxmpp/xmlstream/stanzabase.py
diff options
context:
space:
mode:
authorLance Stout <lancestout@gmail.com>2011-11-21 21:50:40 -0800
committerLance Stout <lancestout@gmail.com>2011-11-21 21:51:19 -0800
commit2b0a05ee32a28659b7358685bbe86b6bc20124d9 (patch)
tree2a2a24c5bde3fa3404402683b340985f00bd1645 /sleekxmpp/xmlstream/stanzabase.py
parentbc2d0ee9a88de9abb151fe399777c1914f9c5e92 (diff)
downloadslixmpp-2b0a05ee32a28659b7358685bbe86b6bc20124d9.tar.gz
slixmpp-2b0a05ee32a28659b7358685bbe86b6bc20124d9.tar.bz2
slixmpp-2b0a05ee32a28659b7358685bbe86b6bc20124d9.tar.xz
slixmpp-2b0a05ee32a28659b7358685bbe86b6bc20124d9.zip
Update stanzabase docs
Diffstat (limited to 'sleekxmpp/xmlstream/stanzabase.py')
-rw-r--r--sleekxmpp/xmlstream/stanzabase.py887
1 files changed, 440 insertions, 447 deletions
diff --git a/sleekxmpp/xmlstream/stanzabase.py b/sleekxmpp/xmlstream/stanzabase.py
index 23de30bf..3c5cf8df 100644
--- a/sleekxmpp/xmlstream/stanzabase.py
+++ b/sleekxmpp/xmlstream/stanzabase.py
@@ -1,9 +1,15 @@
+# -*- coding: utf-8 -*-
"""
- SleekXMPP: The Sleek XMPP Library
- Copyright (C) 2010 Nathanael C. Fritz
- This file is part of SleekXMPP.
+ sleekxmpp.xmlstream.stanzabase
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- See the file LICENSE for copying permission.
+ This module implements a wrapper layer for XML objects
+ that allows them to be treated like dictionaries.
+
+ Part of SleekXMPP: The Sleek XMPP Library
+
+ :copyright: (c) 2011 Nathanael C. Fritz
+ :license: MIT, see LICENSE for more details
"""
import copy
@@ -28,15 +34,22 @@ def register_stanza_plugin(stanza, plugin, iterable=False, overrides=False):
"""
Associate a stanza object as a plugin for another stanza.
- Arguments:
- stanza -- The class of the parent stanza.
- plugin -- The class of the plugin stanza.
- iterable -- Indicates if the plugin stanza should be
- included in the parent stanza's iterable
- 'substanzas' interface results.
- overrides -- Indicates if the plugin should be allowed
- to override the interface handlers for
- the parent stanza.
+ >>> from sleekxmpp.xmlstream import register_stanza_plugin
+ >>> register_stanza_plugin(Iq, CustomStanza)
+
+ :param class stanza: The class of the parent stanza.
+ :param class plugin: The class of the plugin stanza.
+ :param bool iterable: Indicates if the plugin stanza should be
+ included in the parent stanza's iterable
+ ``'substanzas'`` interface results.
+ :param bool overrides: Indicates if the plugin should be allowed
+ to override the interface handlers for
+ the parent stanza, based on the plugin's
+ ``overrides`` field.
+
+ .. versionadded:: 1.0-Beta1
+ Made ``register_stanza_plugin`` the default name. The prior
+ ``registerStanzaPlugin`` function name remains as an alias.
"""
tag = "{%s}%s" % (plugin.namespace, plugin.name)
@@ -73,23 +86,23 @@ class ElementBase(object):
to the Ruby XMPP library Blather's stanza implementation.
Stanzas are defined by their name, namespace, and interfaces. For
- example, a simplistic Message stanza could be defined as:
+ example, a simplistic Message stanza could be defined as::
- >>> class Message(ElementBase):
- ... name = "message"
- ... namespace = "jabber:client"
- ... interfaces = set(('to', 'from', 'type', 'body'))
- ... sub_interfaces = set(('body',))
+ >>> class Message(ElementBase):
+ ... name = "message"
+ ... namespace = "jabber:client"
+ ... interfaces = set(('to', 'from', 'type', 'body'))
+ ... sub_interfaces = set(('body',))
- The resulting Message stanza's contents may be accessed as so:
+ The resulting Message stanza's contents may be accessed as so::
- >>> message['to'] = "user@example.com"
- >>> message['body'] = "Hi!"
- >>> message['body']
- "Hi!"
- >>> del message['body']
- >>> message['body']
- ""
+ >>> message['to'] = "user@example.com"
+ >>> message['body'] = "Hi!"
+ >>> message['body']
+ "Hi!"
+ >>> del message['body']
+ >>> message['body']
+ ""
The interface values map to either custom access methods, stanza
XML attributes, or (if the interface is also in sub_interfaces) the
@@ -100,164 +113,171 @@ class ElementBase(object):
"Interface" is the titlecase version of the interface name.
Stanzas may be extended through the use of plugins. A plugin
- is simply a stanza that has a plugin_attrib value. For example:
+ is simply a stanza that has a plugin_attrib value. For example::
- >>> class MessagePlugin(ElementBase):
- ... name = "custom_plugin"
- ... namespace = "custom"
- ... interfaces = set(('useful_thing', 'custom'))
- ... plugin_attrib = "custom"
+ >>> class MessagePlugin(ElementBase):
+ ... name = "custom_plugin"
+ ... namespace = "custom"
+ ... interfaces = set(('useful_thing', 'custom'))
+ ... plugin_attrib = "custom"
The plugin stanza class must be associated with its intended
- container stanza by using register_stanza_plugin as so:
+ container stanza by using register_stanza_plugin as so::
- >>> register_stanza_plugin(Message, MessagePlugin)
+ >>> register_stanza_plugin(Message, MessagePlugin)
The plugin may then be accessed as if it were built-in to the parent
- stanza.
+ stanza::
- >>> message['custom']['useful_thing'] = 'foo'
+ >>> message['custom']['useful_thing'] = 'foo'
If a plugin provides an interface that is the same as the plugin's
plugin_attrib value, then the plugin's interface may be assigned
directly from the parent stanza, as shown below, but retrieving
- information will require all interfaces to be used, as so:
+ information will require all interfaces to be used, as so::
- >>> message['custom'] = 'bar' # Same as using message['custom']['custom']
- >>> message['custom']['custom'] # Must use all interfaces
- 'bar'
+ >>> message['custom'] = 'bar' # Same as using message['custom']['custom']
+ >>> message['custom']['custom'] # Must use all interfaces
+ 'bar'
If the plugin sets the value is_extension = True, then both setting
and getting an interface value that is the same as the plugin's
- plugin_attrib value will work, as so:
-
- >>> message['custom'] = 'bar' # Using is_extension=True
- >>> message['custom']
- 'bar'
-
-
- Class Attributes:
- name -- The name of the stanza's main element.
- namespace -- The namespace of the stanza's main element.
- interfaces -- A set of attribute and element names that may
- be accessed using dictionary syntax.
- sub_interfaces -- A subset of the set of interfaces which map
- to subelements instead of attributes.
- subitem -- A set of stanza classes which are allowed to
- be added as substanzas. Deprecated version
- of plugin_iterables.
- overrides -- A list of interfaces prepended with 'get_',
- 'set_', or 'del_'. If the stanza is registered
- as a plugin with overrides=True, then the
- parent's interface handlers will be
- overridden by the plugin's matching handler.
- types -- A set of generic type attribute values.
- tag -- The namespaced name of the stanza's root
- element. Example: "{foo_ns}bar"
- plugin_attrib -- The interface name that the stanza uses to be
- accessed as a plugin from another stanza.
- plugin_attrib_map -- A mapping of plugin attribute names with the
- associated plugin stanza classes.
- plugin_iterables -- A set of stanza classes which are allowed to
- be added as substanzas.
- plugin_overrides -- A mapping of interfaces prepended with 'get_',
- 'set_' or 'del_' to plugin attrib names. Allows
- a plugin to override the behaviour of a parent
- stanza's interface handlers.
- plugin_tag_map -- A mapping of plugin stanza tag names with
- the associated plugin stanza classes.
- is_extension -- When True, allows the stanza to provide one
- additional interface to the parent stanza,
- extending the interfaces supported by the
- parent. Defaults to False.
- xml_ns -- The XML namespace,
- http://www.w3.org/XML/1998/namespace,
- for use with xml:lang values.
-
- Instance Attributes:
- xml -- The stanza's XML contents.
- parent -- The parent stanza of this stanza.
- plugins -- A map of enabled plugin names with the
- initialized plugin stanza objects.
- values -- A dictionary of the stanza's interfaces
- and interface values, including plugins.
-
- Class Methods
- tag_name -- Return the namespaced version of the stanza's
- root element's name.
-
- Methods:
- setup -- Initialize the stanza's XML contents.
- enable -- Instantiate a stanza plugin.
- Alias for init_plugin.
- init_plugin -- Instantiate a stanza plugin.
- _get_stanza_values -- Return a dictionary of stanza interfaces and
- their values.
- _set_stanza_values -- Set stanza interface values given a dictionary
- of interfaces and values.
- __getitem__ -- Return the value of a stanza interface.
- __setitem__ -- Set the value of a stanza interface.
- __delitem__ -- Remove the value of a stanza interface.
- _set_attr -- Set an attribute value of the main
- stanza element.
- _del_attr -- Remove an attribute from the main
- stanza element.
- _get_attr -- Return an attribute's value from the main
- stanza element.
- _get_sub_text -- Return the text contents of a subelement.
- _set_sub_text -- Set the text contents of a subelement.
- _del_sub -- Remove a subelement.
- match -- Compare the stanza against an XPath expression.
- find -- Return subelement matching an XPath expression.
- findall -- Return subelements matching an XPath expression.
- get -- Return the value of a stanza interface, with an
- optional default value.
- keys -- Return the set of interface names accepted by
- the stanza.
- append -- Add XML content or a substanza to the stanza.
- appendxml -- Add XML content to the stanza.
- pop -- Remove a substanza.
- next -- Return the next iterable substanza.
- clear -- Reset the stanza's XML contents.
- _fix_ns -- Apply the stanza's namespace to non-namespaced
- elements in an XPath expression.
+ plugin_attrib value will work, as so::
+
+ >>> message['custom'] = 'bar' # Using is_extension=True
+ >>> message['custom']
+ 'bar'
+
+
+ :param xml: Initialize the stanza object with an existing XML object.
+ :param parent: Optionally specify a parent stanza object will will
+ contain this substanza.
"""
+ #: The XML tag name of the element, not including any namespace
+ #: prefixes. For example, an :class:`ElementBase` object for ``<message />``
+ #: would use ``name = 'message'``.
name = 'stanza'
- plugin_attrib = 'plugin'
+
+ #: The XML namespace for the element. Given ``<foo xmlns="bar" />``,
+ #: then ``namespace = "bar"`` should be used. The default namespace
+ #: is ``jabber:client`` since this is being used in an XMPP library.
namespace = 'jabber:client'
+
+ #: For :class:`ElementBase` subclasses which are intended to be used
+ #: as plugins, the ``plugin_attrib`` value defines the plugin name.
+ #: Plugins may be accessed by using the ``plugin_attrib`` value as
+ #: the interface. An example using ``plugin_attrib = 'foo'``:
+ #:
+ #: register_stanza_plugin(Message, FooPlugin)
+ #: msg = Message()
+ #: msg['foo']['an_interface_from_the_foo_plugin']
+ plugin_attrib = 'plugin'
+
+ #: The set of keys that the stanza provides for accessing and
+ #: manipulating the underlying XML object. This set may be augmented
+ #: with the :attr:`plugin_attrib` value of any registered
+ #: stanza plugins.
interfaces = set(('type', 'to', 'from', 'id', 'payload'))
- types = set(('get', 'set', 'error', None, 'unavailable', 'normal', 'chat'))
+
+ #: A subset of :attr:`interfaces` which maps interfaces to direct
+ #: subelements of the underlying XML object. Using this set, the text
+ #: of these subelements may be set, retrieved, or removed without
+ #: needing to define custom methods.
sub_interfaces = tuple()
- overrides = {}
- plugin_attrib_map = {}
+
+ #: In some cases you may wish to override the behaviour of one of the
+ #: parent stanza's interfaces. The ``overrides`` list specifies the
+ #: interface name and access method to be overridden. For example,
+ #: to override setting the parent's ``'condition'`` interface you
+ #: would use::
+ #:
+ #: overrides = ['set_condition']
+ #:
+ #: Getting and deleting the ``'condition'`` interface would not
+ #: be affected.
+ #:
+ #: .. versionadded:: 1.0-Beta5
+ overrides = []
+
+ #: If you need to add a new interface to an existing stanza, you
+ #: can create a plugin and set ``is_extension = True``. Be sure
+ #: to set the :attr:`plugin_attrib` value to the desired interface
+ #: name, and that it is the only interface listed in
+ #: :attr:`interfaces`. Requests for the new interface from the
+ #: parent stanza will be passed to the plugin directly.
+ #:
+ #: .. versionadded:: 1.0-Beta5
+ is_extension = False
+
+ #: A map of interface operations to the overriding functions.
+ #: For example, after overriding the ``set`` operation for
+ #: the interface ``body``, :attr:`plugin_overrides` would be::
+ #:
+ #: {'set_body': <some function>}
+ #:
+ #: .. versionadded: 1.0-Beta5
plugin_overrides = {}
- plugin_iterables = set()
+
+ #: A mapping of the :attr:`plugin_attrib` values of registered
+ #: plugins to their respective classes.
+ plugin_attrib_map = {}
+
+ #: A mapping of root element tag names (in ``'{namespace}elementname'``
+ #: format) to the plugin classes responsible for them.
plugin_tag_map = {}
+
+ #: The set of stanza classes that can be iterated over using
+ #: the 'substanzas' interface. Classes are added to this set
+ #: when registering a plugin with ``iterable=True``::
+ #:
+ #: register_stanza_plugin(DiscoInfo, DiscoItem, iterable=True)
+ #:
+ #: .. versionadded:: 1.0-Beta5
+ plugin_iterables = set()
+
+ #: A deprecated version of :attr:`plugin_iterables` that remains
+ #: for backward compatibility. It required a parent stanza to
+ #: know beforehand what stanza classes would be iterable::
+ #:
+ #: class DiscoItem(ElementBase):
+ #: ...
+ #:
+ #: class DiscoInfo(ElementBase):
+ #: subitem = (DiscoItem, )
+ #: ...
+ #:
+ #: .. deprecated:: 1.0-Beta5
subitem = set()
- is_extension = False
+
+ #: The default XML namespace: ``http://www.w3.org/XML/1998/namespace``.
xml_ns = 'http://www.w3.org/XML/1998/namespace'
def __init__(self, xml=None, parent=None):
- """
- Create a new stanza object.
+ self._index = 0
- Arguments:
- xml -- Initialize the stanza with optional existing XML.
- parent -- Optional stanza object that contains this stanza.
- """
+ #: The underlying XML object for the stanza. It is a standard
+ #: :class:`xml.etree.cElementTree` object.
self.xml = xml
+
+ #: An ordered dictionary of plugin stanzas, mapped by their
+ #: :attr:`plugin_attrib` value.
self.plugins = OrderedDict()
+
+ #: A list of child stanzas whose class is included in
+ #: :attr:`plugin_iterables`.
self.iterables = []
- self._index = 0
+
+ #: The name of the tag for the stanza's root element. It is the
+ #: same as calling :meth:`tag_name()` and is formatted as
+ #: ``'{namespace}elementname'``.
self.tag = self.tag_name()
- if parent is None:
- self.parent = None
- else:
- self.parent = weakref.ref(parent)
- ElementBase.values = property(ElementBase._get_stanza_values,
- ElementBase._set_stanza_values)
+ #: A :class:`weakref.weakref` to the parent stanza, if there is one.
+ #: If not, then :attr:`parent` is ``None``.
+ self.parent = None
+ if parent is not None:
+ self.parent = weakref.ref(parent)
if self.subitem is not None:
for sub in self.subitem:
@@ -278,15 +298,14 @@ class ElementBase(object):
break
def setup(self, xml=None):
- """
- Initialize the stanza's XML contents.
+ """Initialize the stanza's XML contents.
- Will return True if XML was generated according to the stanza's
- definition.
+ Will return ``True`` if XML was generated according to the stanza's
+ definition instead of building a stanza object from an existing
+ XML object.
- Arguments:
- xml -- Optional XML object to use for the stanza's content
- instead of generating XML.
+ :param xml: An existing XML object to use for the stanza's content
+ instead of generating new XML.
"""
if self.xml is None:
self.xml = xml
@@ -310,22 +329,20 @@ class ElementBase(object):
return False
def enable(self, attrib):
- """
- Enable and initialize a stanza plugin.
+ """Enable and initialize a stanza plugin.
- Alias for init_plugin.
+ Alias for :meth:`init_plugin`.
- Arguments:
- attrib -- The stanza interface for the plugin.
+ :param string attrib: The :attr:`plugin_attrib` value of the
+ plugin to enable.
"""
return self.init_plugin(attrib)
def init_plugin(self, attrib):
- """
- Enable and initialize a stanza plugin.
+ """Enable and initialize a stanza plugin.
- Arguments:
- attrib -- The stanza interface for the plugin.
+ :param string attrib: The :attr:`plugin_attrib` value of the
+ plugin to enable.
"""
if attrib not in self.plugins:
plugin_class = self.plugin_attrib_map[attrib]
@@ -333,10 +350,23 @@ class ElementBase(object):
return self
def _get_stanza_values(self):
- """
- Return a dictionary of the stanza's interface values.
+ """Return A JSON/dictionary version of the XML content
+ exposed through the stanza's interfaces::
+
+ >>> msg = Message()
+ >>> msg.values
+ {'body': '', 'from': , 'mucnick': '', 'mucroom': '',
+ 'to': , 'type': 'normal', 'id': '', 'subject': ''}
+
+ Likewise, assigning to :attr:`values` will change the XML
+ content::
- Stanza plugin values are included as nested dictionaries.
+ >>> msg = Message()
+ >>> msg.values = {'body': 'Hi!', 'to': 'user@example.com'}
+ >>> msg
+ '<message to="user@example.com"><body>Hi!</body></message>'
+
+ .. versionadded:: 1.0-Beta1
"""
values = {}
for interface in self.interfaces:
@@ -352,15 +382,15 @@ class ElementBase(object):
return values
def _set_stanza_values(self, values):
- """
- Set multiple stanza interface values using a dictionary.
+ """Set multiple stanza interface values using a dictionary.
Stanza plugin values may be set using nested dictionaries.
- Arguments:
- values -- A dictionary mapping stanza interface with values.
- Plugin interfaces may accept a nested dictionary that
- will be used recursively.
+ :param values: A dictionary mapping stanza interface with values.
+ Plugin interfaces may accept a nested dictionary that
+ will be used recursively.
+
+ .. versionadded:: 1.0-Beta1
"""
iterable_interfaces = [p.plugin_attrib for \
p in self.plugin_iterables]
@@ -393,30 +423,31 @@ class ElementBase(object):
return self
def __getitem__(self, attrib):
- """
- Return the value of a stanza interface using dictionary-like syntax.
+ """Return the value of a stanza interface using dict-like syntax.
+
+ Example::
- Example:
>>> msg['body']
'Message contents'
Stanza interfaces are typically mapped directly to the underlying XML
- object, but can be overridden by the presence of a get_attrib method
- (or get_foo where the interface is named foo, etc).
+ object, but can be overridden by the presence of a ``get_attrib``
+ method (or ``get_foo`` where the interface is named ``'foo'``, etc).
The search order for interface value retrieval for an interface
- named 'foo' is:
- 1. The list of substanzas.
- 2. The result of calling the get_foo override handler.
- 3. The result of calling get_foo.
- 4. The result of calling getFoo.
- 5. The contents of the foo subelement, if foo is a sub interface.
- 6. The value of the foo attribute of the XML object.
- 7. The plugin named 'foo'
+ named ``'foo'`` is:
+
+ 1. The list of substanzas (``'substanzas'``)
+ 2. The result of calling the ``get_foo`` override handler.
+ 3. The result of calling ``get_foo``.
+ 4. The result of calling ``getFoo``.
+ 5. The contents of the ``foo`` subelement, if ``foo`` is listed
+ in :attr:`sub_interfaces`.
+ 6. The value of the ``foo`` attribute of the XML object.
+ 7. The plugin named ``'foo'``
8. An empty string.
- Arguments:
- attrib -- The name of the requested stanza interface.
+ :param string attrib: The name of the requested stanza interface.
"""
if attrib == 'substanzas':
return self.iterables
@@ -452,33 +483,34 @@ class ElementBase(object):
return ''
def __setitem__(self, attrib, value):
- """
- Set the value of a stanza interface using dictionary-like syntax.
+ """Set the value of a stanza interface using dictionary-like syntax.
+
+ Example::
- Example:
>>> msg['body'] = "Hi!"
>>> msg['body']
'Hi!'
Stanza interfaces are typically mapped directly to the underlying XML
- object, but can be overridden by the presence of a set_attrib method
- (or set_foo where the interface is named foo, etc).
+ object, but can be overridden by the presence of a ``set_attrib``
+ method (or ``set_foo`` where the interface is named ``'foo'``, etc).
The effect of interface value assignment for an interface
- named 'foo' will be one of:
+ named ``'foo'`` will be one of:
+
1. Delete the interface's contents if the value is None.
- 2. Call the set_foo override handler, if it exists.
- 3. Call set_foo, if it exists.
- 4. Call setFoo, if it exists.
- 5. Set the text of a foo element, if foo is in sub_interfaces.
- 6. Set the value of a top level XML attribute name foo.
- 7. Attempt to pass value to a plugin named foo using the plugin's
- foo interface.
+ 2. Call the ``set_foo`` override handler, if it exists.
+ 3. Call ``set_foo``, if it exists.
+ 4. Call ``setFoo``, if it exists.
+ 5. Set the text of a ``foo`` element, if ``'foo'`` is
+ in :attr:`sub_interfaces`.
+ 6. Set the value of a top level XML attribute named ``foo``.
+ 7. Attempt to pass the value to a plugin named ``'foo'`` using
+ the plugin's ``'foo'`` interface.
8. Do nothing.
- Arguments:
- attrib -- The name of the stanza interface to modify.
- value -- The new value of the stanza interface.
+ :param string attrib: The name of the stanza interface to modify.
+ :param value: The new value of the stanza interface.
"""
if attrib in self.interfaces:
if value is not None:
@@ -513,10 +545,10 @@ class ElementBase(object):
return self
def __delitem__(self, attrib):
- """
- Delete the value of a stanza interface using dictionary-like syntax.
+ """Delete the value of a stanza interface using dict-like syntax.
+
+ Example::
- Example:
>>> msg['body'] = "Hi!"
>>> msg['body']
'Hi!'
@@ -525,21 +557,22 @@ class ElementBase(object):
''
Stanza interfaces are typically mapped directly to the underlyig XML
- object, but can be overridden by the presence of a del_attrib method
- (or del_foo where the interface is named foo, etc).
+ object, but can be overridden by the presence of a ``del_attrib``
+ method (or ``del_foo`` where the interface is named ``'foo'``, etc).
- The effect of deleting a stanza interface value named foo will be
+ The effect of deleting a stanza interface value named ``foo`` will be
one of:
- 1. Call del_foo override handler, if it exists.
- 2. Call del_foo, if it exists.
- 3. Call delFoo, if it exists.
- 4. Delete foo element, if foo is in sub_interfaces.
- 5. Delete top level XML attribute named foo.
- 6. Remove the foo plugin, if it was loaded.
+
+ 1. Call ``del_foo`` override handler, if it exists.
+ 2. Call ``del_foo``, if it exists.
+ 3. Call ``delFoo``, if it exists.
+ 4. Delete ``foo`` element, if ``'foo'`` is in
+ :attr:`sub_interfaces`.
+ 5. Delete top level XML attribute named ``foo``.
+ 6. Remove the ``foo`` plugin, if it was loaded.
7. Do nothing.
- Arguments:
- attrib -- The name of the affected stanza interface.
+ :param attrib: The name of the affected stanza interface.
"""
if attrib in self.interfaces:
del_method = "del_%s" % attrib.lower()
@@ -576,16 +609,14 @@ class ElementBase(object):
return self
def _set_attr(self, name, value):
- """
- Set the value of a top level attribute of the underlying XML object.
+ """Set the value of a top level attribute of the XML object.
If the new value is None or an empty string, then the attribute will
be removed.
- Arguments:
- name -- The name of the attribute.
- value -- The new value of the attribute, or None or '' to
- remove it.
+ :param name: The name of the attribute.
+ :param value: The new value of the attribute, or None or '' to
+ remove it.
"""
if value is None or value == '':
self.__delitem__(name)
@@ -593,43 +624,36 @@ class ElementBase(object):
self.xml.attrib[name] = value
def _del_attr(self, name):
- """
- Remove a top level attribute of the underlying XML object.
+ """Remove a top level attribute of the XML object.
- Arguments:
- name -- The name of the attribute.
+ :param name: The name of the attribute.
"""
if name in self.xml.attrib:
del self.xml.attrib[name]
def _get_attr(self, name, default=''):
- """
- Return the value of a top level attribute of the underlying
- XML object.
+ """Return the value of a top level attribute of the XML object.
In case the attribute has not been set, a default value can be
returned instead. An empty string is returned if no other default
is supplied.
- Arguments:
- name -- The name of the attribute.
- default -- Optional value to return if the attribute has not
- been set. An empty string is returned otherwise.
+ :param name: The name of the attribute.
+ :param default: Optional value to return if the attribute has not
+ been set. An empty string is returned otherwise.
"""
return self.xml.attrib.get(name, default)
def _get_sub_text(self, name, default=''):
- """
- Return the text contents of a sub element.
+ """Return the text contents of a sub element.
In case the element does not exist, or it has no textual content,
a default value can be returned instead. An empty string is returned
if no other default is supplied.
- Arguments:
- name -- The name or XPath expression of the element.
- default -- Optional default to return if the element does
- not exists. An empty string is returned otherwise.
+ :param name: The name or XPath expression of the element.
+ :param default: Optional default to return if the element does
+ not exists. An empty string is returned otherwise.
"""
name = self._fix_ns(name)
stanza = self.xml.find(name)
@@ -639,8 +663,7 @@ class ElementBase(object):
return stanza.text
def _set_sub_text(self, name, text=None, keep=False):
- """
- Set the text contents of a sub element.
+ """Set the text contents of a sub element.
In case the element does not exist, a element will be created,
and its text contents will be set.
@@ -648,13 +671,12 @@ class ElementBase(object):
If the text is set to an empty string, or None, then the
element will be removed, unless keep is set to True.
- Arguments:
- name -- The name or XPath expression of the element.
- text -- The new textual content of the element. If the text
- is an empty string or None, the element will be removed
- unless the parameter keep is True.
- keep -- Indicates if the element should be kept if its text is
- removed. Defaults to False.
+ :param name: The name or XPath expression of the element.
+ :param text: The new textual content of the element. If the text
+ is an empty string or None, the element will be removed
+ unless the parameter keep is True.
+ :param keep: Indicates if the element should be kept if its text is
+ removed. Defaults to False.
"""
path = self._fix_ns(name, split=True)
element = self.xml.find(name)
@@ -682,17 +704,15 @@ class ElementBase(object):
return element
def _del_sub(self, name, all=False):
- """
- Remove sub elements that match the given name or XPath.
+ """Remove sub elements that match the given name or XPath.
If the element is in a path, then any parent elements that become
empty after deleting the element may also be deleted if requested
by setting all=True.
- Arguments:
- name -- The name or XPath expression for the element(s) to remove.
- all -- If True, remove all empty elements in the path to the
- deleted element. Defaults to False.
+ :param name: The name or XPath expression for the element(s) to remove.
+ :param bool all: If True, remove all empty elements in the path to the
+ deleted element. Defaults to False.
"""
path = self._fix_ns(name, split=True)
original_target = path[-1]
@@ -720,19 +740,22 @@ class ElementBase(object):
return
def match(self, xpath):
- """
- Compare a stanza object with an XPath expression. If the XPath matches
- the contents of the stanza object, the match is successful.
+ """Compare a stanza object with an XPath-like expression.
+
+ If the XPath matches the contents of the stanza object, the match
+ is successful.
The XPath expression may include checks for stanza attributes.
- For example:
- presence@show=xa@priority=2/status
- Would match a presence stanza whose show value is set to 'xa', has a
- priority value of '2', and has a status element.
+ For example::
- Arguments:
- xpath -- The XPath expression to check against. It may be either a
- string or a list of element names with attribute checks.
+ 'presence@show=xa@priority=2/status'
+
+ Would match a presence stanza whose show value is set to ``'xa'``,
+ has a priority value of ``'2'``, and has a status element.
+
+ :param string xpath: The XPath expression to check against. It
+ may be either a string or a list of element
+ names with attribute checks.
"""
if isinstance(xpath, str):
xpath = self._fix_ns(xpath, split=True, propagate_ns=False)
@@ -781,44 +804,46 @@ class ElementBase(object):
return True
def find(self, xpath):
- """
- Find an XML object in this stanza given an XPath expression.
+ """Find an XML object in this stanza given an XPath expression.
Exposes ElementTree interface for backwards compatibility.
- Note that matching on attribute values is not supported in Python 2.6
- or Python 3.1
+ .. note::
- Arguments:
- xpath -- An XPath expression matching a single desired element.
+ Matching on attribute values is not supported in Python 2.6
+ or Python 3.1
+
+ :param string xpath: An XPath expression matching a single
+ desired element.
"""
return self.xml.find(xpath)
def findall(self, xpath):
- """
- Find multiple XML objects in this stanza given an XPath expression.
+ """Find multiple XML objects in this stanza given an XPath expression.
Exposes ElementTree interface for backwards compatibility.
- Note that matching on attribute values is not supported in Python 2.6
- or Python 3.1.
+ .. note::
- Arguments:
- xpath -- An XPath expression matching multiple desired elements.
+ Matching on attribute values is not supported in Python 2.6
+ or Python 3.1.
+
+ :param string xpath: An XPath expression matching multiple
+ desired elements.
"""
return self.xml.findall(xpath)
def get(self, key, default=None):
- """
- Return the value of a stanza interface. If the found value is None
- or an empty string, return the supplied default value.
+ """Return the value of a stanza interface.
+
+ If the found value is None or an empty string, return the supplied
+ default value.
Allows stanza objects to be used like dictionaries.
- Arguments:
- key -- The name of the stanza interface to check.
- default -- Value to return if the stanza interface has a value
- of None or "". Will default to returning None.
+ :param string key: The name of the stanza interface to check.
+ :param default: Value to return if the stanza interface has a value
+ of ``None`` or ``""``. Will default to returning None.
"""
value = self[key]
if value is None or value == '':
@@ -826,8 +851,7 @@ class ElementBase(object):
return value
def keys(self):
- """
- Return the names of all stanza interfaces provided by the
+ """Return the names of all stanza interfaces provided by the
stanza object.
Allows stanza objects to be used like dictionaries.
@@ -840,17 +864,15 @@ class ElementBase(object):
return out
def append(self, item):
- """
- Append either an XML object or a substanza to this stanza object.
+ """Append either an XML object or a substanza to this stanza object.
If a substanza object is appended, it will be added to the list
of iterable stanzas.
Allows stanza objects to be used like lists.
- Arguments:
- item -- Either an XML object or a stanza object to add to
- this stanza's contents.
+ :param item: Either an XML object or a stanza object to add to
+ this stanza's contents.
"""
if not isinstance(item, ElementBase):
if type(item) == XML_TYPE:
@@ -862,41 +884,34 @@ class ElementBase(object):
return self
def appendxml(self, xml):
- """
- Append an XML object to the stanza's XML.
+ """Append an XML object to the stanza's XML.
The added XML will not be included in the list of
iterable substanzas.
- Arguments:
- xml -- The XML object to add to the stanza.
+ :param XML xml: The XML object to add to the stanza.
"""
self.xml.append(xml)
return self
def pop(self, index=0):
- """
- Remove and return the last substanza in the list of
+ """Remove and return the last substanza in the list of
iterable substanzas.
Allows stanza objects to be used like lists.
- Arguments:
- index -- The index of the substanza to remove.
+ :param int index: The index of the substanza to remove.
"""
substanza = self.iterables.pop(index)
self.xml.remove(substanza.xml)
return substanza
def next(self):
- """
- Return the next iterable substanza.
- """
+ """Return the next iterable substanza."""
return self.__next__()
def clear(self):
- """
- Remove all XML element contents and plugins.
+ """Remove all XML element contents and plugins.
Any attribute values will be preserved.
"""
@@ -908,43 +923,44 @@ class ElementBase(object):
@classmethod
def tag_name(cls):
- """
- Return the namespaced name of the stanza's root element.
+ """Return the namespaced name of the stanza's root element.
+
+ The format for the tag name is::
- For example, for the stanza <foo xmlns="bar" />,
- stanza.tag would return "{bar}foo".
+ '{namespace}elementname'
+
+ For example, for the stanza ``<foo xmlns="bar" />``,
+ ``stanza.tag_name()`` would return ``"{bar}foo"``.
"""
return "{%s}%s" % (cls.namespace, cls.name)
@property
def attrib(self):
- """
- DEPRECATED
-
- For backwards compatibility, stanza.attrib returns the stanza itself.
+ """Return the stanza object itself.
Older implementations of stanza objects used XML objects directly,
- requiring the use of .attrib to access attribute values.
+ requiring the use of ``.attrib`` to access attribute values.
Use of the dictionary syntax with the stanza object itself for
accessing stanza interfaces is preferred.
+
+ .. deprecated:: 1.0
"""
return self
def _fix_ns(self, xpath, split=False, propagate_ns=True):
- """
- Apply the stanza's namespace to elements in an XPath expression.
-
- Arguments:
- xpath -- The XPath expression to fix with namespaces.
- split -- Indicates if the fixed XPath should be left as a
- list of element names with namespaces. Defaults to
- False, which returns a flat string path.
- propagate_ns -- Overrides propagating parent element namespaces
- to child elements. Useful if you wish to simply
- split an XPath that has non-specified namespaces,
- and child and parent namespaces are known not to
- always match. Defaults to True.
+ """Apply the stanza's namespace to elements in an XPath expression.
+
+ :param string xpath: The XPath expression to fix with namespaces.
+ :param bool split: Indicates if the fixed XPath should be left as a
+ list of element names with namespaces. Defaults to
+ False, which returns a flat string path.
+ :param bool propagate_ns: Overrides propagating parent element
+ namespaces to child elements. Useful if
+ you wish to simply split an XPath that has
+ non-specified namespaces, and child and
+ parent namespaces are known not to always
+ match. Defaults to True.
"""
fixed = []
# Split the XPath into a series of blocks, where a block
@@ -975,14 +991,12 @@ class ElementBase(object):
return '/'.join(fixed)
def __eq__(self, other):
- """
- Compare the stanza object with another to test for equality.
+ """Compare the stanza object with another to test for equality.
Stanzas are equal if their interfaces return the same values,
and if they are both instances of ElementBase.
- Arguments:
- other -- The stanza object to compare against.
+ :param ElementBase other: The stanza object to compare against.
"""
if not isinstance(other, ElementBase):
return False
@@ -1004,42 +1018,35 @@ class ElementBase(object):
return True
def __ne__(self, other):
- """
- Compare the stanza object with another to test for inequality.
+ """Compare the stanza object with another to test for inequality.
Stanzas are not equal if their interfaces return different values,
or if they are not both instances of ElementBase.
- Arguments:
- other -- The stanza object to compare against.
+ :param ElementBase other: The stanza object to compare against.
"""
return not self.__eq__(other)
def __bool__(self):
- """
- Stanza objects should be treated as True in boolean contexts.
+ """Stanza objects should be treated as True in boolean contexts.
Python 3.x version.
"""
return True
def __nonzero__(self):
- """
- Stanza objects should be treated as True in boolean contexts.
+ """Stanza objects should be treated as True in boolean contexts.
Python 2.x version.
"""
return True
def __len__(self):
- """
- Return the number of iterable substanzas contained in this stanza.
- """
+ """Return the number of iterable substanzas in this stanza."""
return len(self.iterables)
def __iter__(self):
- """
- Return an iterator object for iterating over the stanza's substanzas.
+ """Return an iterator object for the stanza's substanzas.
The iterator is the stanza object itself. Attempting to use two
iterators on the same stanza at the same time is discouraged.
@@ -1048,9 +1055,7 @@ class ElementBase(object):
return self
def __next__(self):
- """
- Return the next iterable substanza.
- """
+ """Return the next iterable substanza."""
self._index += 1
if self._index > len(self.iterables):
self._index = 0
@@ -1058,19 +1063,16 @@ class ElementBase(object):
return self.iterables[self._index - 1]
def __copy__(self):
- """
- Return a copy of the stanza object that does not share the same
+ """Return a copy of the stanza object that does not share the same
underlying XML object.
"""
return self.__class__(xml=copy.deepcopy(self.xml), parent=self.parent)
def __str__(self, top_level_ns=True):
- """
- Return a string serialization of the underlying XML object.
+ """Return a string serialization of the underlying XML object.
- Arguments:
- top_level_ns -- Display the top-most namespace.
- Defaults to True.
+ :param bool top_level_ns: Display the top-most namespace.
+ Defaults to True.
"""
stanza_ns = '' if top_level_ns else self.namespace
return tostring(self.xml, xmlns='',
@@ -1078,9 +1080,7 @@ class ElementBase(object):
top_level=not top_level_ns)
def __repr__(self):
- """
- Use the stanza's serialized XML as its representation.
- """
+ """Use the stanza's serialized XML as its representation."""
return self.__str__()
@@ -1094,56 +1094,40 @@ class StanzaBase(ElementBase):
the XML contents of the stanza. Most stanza objects will provided more
specific interfaces, however.
- Stanza Interface:
- from -- A JID object representing the sender's JID.
- id -- An optional id value that can be used to associate stanzas
- with their replies.
- payload -- The XML contents of the stanza.
- to -- A JID object representing the recipient's JID.
- type -- The type of stanza, typically will be 'normal', 'error',
- 'get', or 'set', etc.
-
- Attributes:
- stream -- The XMLStream instance that will handle sending this stanza.
-
- Methods:
- set_type -- Set the type of the stanza.
- get_to -- Return the stanza recipients JID.
- set_to -- Set the stanza recipient's JID.
- get_from -- Return the stanza sender's JID.
- set_from -- Set the stanza sender's JID.
- get_payload -- Return the stanza's XML contents.
- set_payload -- Append to the stanza's XML contents.
- del_payload -- Remove the stanza's XML contents.
- reply -- Reset the stanza and modify the 'to' and 'from'
- attributes to prepare for sending a reply.
- error -- Set the stanza's type to 'error'.
- unhandled -- Callback for when the stanza is not handled by a
- stream handler.
- exception -- Callback for if an exception is raised while
- handling the stanza.
- send -- Send the stanza using the stanza's stream.
+ **Stanza Interfaces:**
+
+ :id: An optional id value that can be used to associate stanzas
+ :to: A JID object representing the recipient's JID.
+ :from: A JID object representing the sender's JID.
+ with their replies.
+ :type: The type of stanza, typically will be ``'normal'``,
+ ``'error'``, ``'get'``, or ``'set'``, etc.
+ :payload: The XML contents of the stanza.
+
+ :param XMLStream stream: Optional :class:`sleekxmpp.xmlstream.XMLStream`
+ object responsible for sending this stanza.
+ :param XML xml: Optional XML contents to initialize stanza values.
+ :param string stype: Optional stanza type value.
+ :param sto: Optional string or :class:`sleekxmpp.xmlstream.JID`
+ object of the recipient's JID.
+ :param sfrom: Optional string or :class:`sleekxmpp.xmlstream.JID`
+ object of the sender's JID.
+ :param string sid: Optional ID value for the stanza.
"""
- name = 'stanza'
+ #: The default XMPP client namespace
namespace = 'jabber:client'
+
+ #: There is a small set of attributes which apply to all XMPP stanzas:
+ #: the stanza type, the to and from JIDs, the stanza ID, and, especially
+ #: in the case of an Iq stanza, a payload.
interfaces = set(('type', 'to', 'from', 'id', 'payload'))
+
+ #: A basic set of allowed values for the ``'type'`` interface.
types = set(('get', 'set', 'error', None, 'unavailable', 'normal', 'chat'))
- sub_interfaces = tuple()
def __init__(self, stream=None, xml=None, stype=None,
sto=None, sfrom=None, sid=None):
- """
- Create a new stanza.
-
- Arguments:
- stream -- Optional XMLStream responsible for sending this stanza.
- xml -- Optional XML contents to initialize stanza values.
- stype -- Optional stanza type value.
- sto -- Optional string or JID object of the recipient's JID.
- sfrom -- Optional string or JID object of the sender's JID.
- sid -- Optional ID value for the stanza.
- """
self.stream = stream
if stream is not None:
self.namespace = stream.default_ns
@@ -1157,38 +1141,34 @@ class StanzaBase(ElementBase):
self.tag = "{%s}%s" % (self.namespace, self.name)
def set_type(self, value):
- """
- Set the stanza's 'type' attribute.
+ """Set the stanza's ``'type'`` attribute.
- Only type values contained in StanzaBase.types are accepted.
+ Only type values contained in :attr:`types` are accepted.
- Arguments:
- value -- One of the values contained in StanzaBase.types
+ :param string value: One of the values contained in :attr:`types`
"""
if value in self.types:
self.xml.attrib['type'] = value
return self
def get_to(self):
- """Return the value of the stanza's 'to' attribute."""
+ """Return the value of the stanza's ``'to'`` attribute."""
return JID(self._get_attr('to'))
def set_to(self, value):
- """
- Set the 'to' attribute of the stanza.
+ """Set the ``'to'`` attribute of the stanza.
- Arguments:
- value -- A string or JID object representing the recipient's JID.
+ :param value: A string or :class:`sleekxmpp.xmlstream.JID` object
+ representing the recipient's JID.
"""
return self._set_attr('to', str(value))
def get_from(self):
- """Return the value of the stanza's 'from' attribute."""
+ """Return the value of the stanza's ``'from'`` attribute."""
return JID(self._get_attr('from'))
def set_from(self, value):
- """
- Set the 'from' attribute of the stanza.
+ """Set the 'from' attribute of the stanza.
Arguments:
from -- A string or JID object representing the sender's JID.
@@ -1200,12 +1180,10 @@ class StanzaBase(ElementBase):
return self.xml.getchildren()
def set_payload(self, value):
- """
- Add XML content to the stanza.
+ """Add XML content to the stanza.
- Arguments:
- value -- Either an XML or a stanza object, or a list
- of XML or stanza objects.
+ :param value: Either an XML or a stanza object, or a list
+ of XML or stanza objects.
"""
if not isinstance(value, list):
value = [value]
@@ -1219,16 +1197,17 @@ class StanzaBase(ElementBase):
return self
def reply(self, clear=True):
- """
- Swap the 'from' and 'to' attributes to prepare the stanza for
- sending a reply. If clear=True, then also remove the stanza's
+ """Prepare the stanza for sending a reply.
+
+ Swaps the ``'from'`` and ``'to'`` attributes.
+
+ If ``clear=True``, then also remove the stanza's
contents to make room for the reply content.
- For client streams, the 'from' attribute is removed.
+ For client streams, the ``'from'`` attribute is removed.
- Arguments:
- clear -- Indicates if the stanza's contents should be
- removed. Defaults to True
+ :param bool clear: Indicates if the stanza's contents should be
+ removed. Defaults to ``True``.
"""
# if it's a component, use from
if self.stream and hasattr(self.stream, "is_component") and \
@@ -1242,22 +1221,19 @@ class StanzaBase(ElementBase):
return self
def error(self):
- """Set the stanza's type to 'error'."""
+ """Set the stanza's type to ``'error'``."""
self['type'] = 'error'
return self
def unhandled(self):
- """
- Called when no handlers have been registered to process this
- stanza.
+ """Called if no handlers have been registered to process this stanza.
Meant to be overridden.
"""
pass
def exception(self, e):
- """
- Handle exceptions raised during stanza processing.
+ """Handle exceptions raised during stanza processing.
Meant to be overridden.
"""
@@ -1265,30 +1241,26 @@ class StanzaBase(ElementBase):
self.name)
def send(self, now=False):
- """
- Queue the stanza to be sent on the XML stream.
- Arguments:
- now -- Indicates if the queue should be skipped and the
- stanza sent immediately. Useful for stream
- initialization. Defaults to False.
+ """Queue the stanza to be sent on the XML stream.
+
+ :param bool now: Indicates if the queue should be skipped and the
+ stanza sent immediately. Useful for stream
+ initialization. Defaults to ``False``.
"""
self.stream.send_raw(self.__str__(), now=now)
def __copy__(self):
- """
- Return a copy of the stanza object that does not share the
+ """Return a copy of the stanza object that does not share the
same underlying XML object, but does share the same XML stream.
"""
return self.__class__(xml=copy.deepcopy(self.xml),
stream=self.stream)
def __str__(self, top_level_ns=False):
- """
- Serialize the stanza's XML to a string.
+ """Serialize the stanza's XML to a string.
- Arguments:
- top_level_ns -- Display the top-most namespace.
- Defaults to False.
+ :param bool top_level_ns: Display the top-most namespace.
+ Defaults to ``False``.
"""
stanza_ns = '' if top_level_ns else self.namespace
return tostring(self.xml, xmlns='',
@@ -1297,6 +1269,27 @@ class StanzaBase(ElementBase):
top_level=not top_level_ns)
+#: A JSON/dictionary version of the XML content exposed through
+#: the stanza interfaces::
+#:
+#: >>> msg = Message()
+#: >>> msg.values
+#: {'body': '', 'from': , 'mucnick': '', 'mucroom': '',
+#: 'to': , 'type': 'normal', 'id': '', 'subject': ''}
+#:
+#: Likewise, assigning to the :attr:`values` will change the XML
+#: content::
+#:
+#: >>> msg = Message()
+#: >>> msg.values = {'body': 'Hi!', 'to': 'user@example.com'}
+#: >>> msg
+#: '<message to="user@example.com"><body>Hi!</body></message>'
+#:
+#: Child stanzas are exposed as nested dictionaries.
+ElementBase.values = property(ElementBase._get_stanza_values,
+ ElementBase._set_stanza_values)
+
+
# To comply with PEP8, method names now use underscores.
# Deprecated method names are re-mapped for backwards compatibility.
ElementBase.initPlugin = ElementBase.init_plugin