summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--sleekxmpp/xmlstream/stanzabase.py139
1 files changed, 126 insertions, 13 deletions
diff --git a/sleekxmpp/xmlstream/stanzabase.py b/sleekxmpp/xmlstream/stanzabase.py
index 9785da0b..51966a4e 100644
--- a/sleekxmpp/xmlstream/stanzabase.py
+++ b/sleekxmpp/xmlstream/stanzabase.py
@@ -893,6 +893,48 @@ class ElementBase(object):
class StanzaBase(ElementBase):
+
+ """
+ StanzaBase provides the foundation for all other stanza objects used by
+ SleekXMPP, and defines a basic set of interfaces common to nearly
+ all stanzas. These interfaces are the 'id', 'type', 'to', and 'from'
+ attributes. An additional interface, 'payload', is available to access
+ 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.
+ tag -- The namespaced version of the stanza's name.
+
+ Methods:
+ setType -- Set the type of the stanza.
+ getTo -- Return the stanza recipients JID.
+ setTo -- Set the stanza recipient's JID.
+ getFrom -- Return the stanza sender's JID.
+ setFrom -- Set the stanza sender's JID.
+ getPayload -- Return the stanza's XML contents.
+ setPayload -- Append to the stanza's XML contents.
+ delPayload -- Remove the stanza's XML contents.
+ clear -- Reset 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.
+ """
+
name = 'stanza'
namespace = 'jabber:client'
interfaces = set(('type', 'to', 'from', 'id', 'payload'))
@@ -901,6 +943,17 @@ class StanzaBase(ElementBase):
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
@@ -914,22 +967,69 @@ class StanzaBase(ElementBase):
self.tag = "{%s}%s" % (self.namespace, self.name)
def setType(self, value):
+ """
+ Set the stanza's 'type' attribute.
+
+ Only type values contained in StanzaBase.types are accepted.
+
+ Arguments:
+ value -- One of the values contained in StanzaBase.types
+ """
if value in self.types:
self.xml.attrib['type'] = value
return self
+ def getTo(self):
+ """Return the value of the stanza's 'to' attribute."""
+ return JID(self._getAttr('to'))
+
+ def setTo(self, value):
+ """
+ Set the 'to' attribute of the stanza.
+
+ Arguments:
+ value -- A string or JID object representing the recipient's JID.
+ """
+ return self._setAttr('to', str(value))
+
+ def getFrom(self):
+ """Return the value of the stanza's 'from' attribute."""
+ return JID(self._getAttr('from'))
+
+ def setFrom(self, value):
+ """
+ Set the 'from' attribute of the stanza.
+
+ Arguments:
+ from -- A string or JID object representing the sender's JID.
+ """
+ return self._setAttr('from', str(value))
+
def getPayload(self):
+ """Return a list of XML objects contained in the stanza."""
return self.xml.getchildren()
def setPayload(self, value):
+ """
+ Add XML content to the stanza.
+
+ Arguments:
+ value -- An XML object, or a stanza object.
+ """
self.xml.append(value)
return self
def delPayload(self):
+ """Remove the XML contents of the stanza."""
self.clear()
return self
def clear(self):
+ """
+ Remove all XML element contents and plugins.
+
+ Any attribute values will be preserved.
+ """
for child in self.xml.getchildren():
self.xml.remove(child)
for plugin in list(self.plugins.keys()):
@@ -937,6 +1037,12 @@ class StanzaBase(ElementBase):
return self
def reply(self):
+ """
+ Reset the stanza and swap its 'from' and 'to' attributes to prepare
+ for sending a reply stanza.
+
+ For client streams, the 'from' attribute is removed.
+ """
# if it's a component, use from
if self.stream and hasattr(self.stream, "is_component") and \
self.stream.is_component:
@@ -948,35 +1054,42 @@ class StanzaBase(ElementBase):
return self
def error(self):
+ """Set the stanza's type to 'error'."""
self['type'] = 'error'
return self
- def getTo(self):
- return JID(self._getAttr('to'))
-
- def setTo(self, value):
- return self._setAttr('to', str(value))
-
- def getFrom(self):
- return JID(self._getAttr('from'))
-
- def setFrom(self, value):
- return self._setAttr('from', str(value))
-
def unhandled(self):
+ """
+ Called when no handlers have been registered to process this
+ stanza.
+
+ Meant to be overridden.
+ """
pass
def exception(self, e):
+ """
+ Handle exceptions raised during stanza processing.
+
+ Meant to be overridden.
+ """
logging.exception('Error handling {%s}%s stanza' % (self.namespace,
self.name))
def send(self):
+ """Queue the stanza to be sent on the XML stream."""
self.stream.sendRaw(self.__str__())
def __copy__(self):
- return self.__class__(xml=copy.deepcopy(self.xml), stream=self.stream)
+ """
+ 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):
+ """Serialize the stanza's XML to a string."""
return tostring(self.xml, xmlns='',
stanza_ns=self.namespace,
stream=self.stream)