summaryrefslogtreecommitdiff
path: root/examples/custom_stanzas/stanza.py
diff options
context:
space:
mode:
authorLance Stout <lancestout@gmail.com>2012-05-14 22:12:52 -0700
committerLance Stout <lancestout@gmail.com>2012-05-14 22:12:52 -0700
commite0bcd5d72245908200afde1ea4c4cb980f054f8d (patch)
tree8b9d7a1fd5c9b05d2dd4933668ea008983eabdb2 /examples/custom_stanzas/stanza.py
parentba854e7d85870dd90307c0c2f408d10d83e4fc33 (diff)
downloadslixmpp-e0bcd5d72245908200afde1ea4c4cb980f054f8d.tar.gz
slixmpp-e0bcd5d72245908200afde1ea4c4cb980f054f8d.tar.bz2
slixmpp-e0bcd5d72245908200afde1ea4c4cb980f054f8d.tar.xz
slixmpp-e0bcd5d72245908200afde1ea4c4cb980f054f8d.zip
Add more documentation to the custom stanza examples.
Diffstat (limited to 'examples/custom_stanzas/stanza.py')
-rw-r--r--examples/custom_stanzas/stanza.py48
1 files changed, 48 insertions, 0 deletions
diff --git a/examples/custom_stanzas/stanza.py b/examples/custom_stanzas/stanza.py
index ca85a0f0..50d0f9f2 100644
--- a/examples/custom_stanzas/stanza.py
+++ b/examples/custom_stanzas/stanza.py
@@ -1,8 +1,56 @@
from sleekxmpp.xmlstream import ElementBase
class Action(ElementBase):
+
+ """
+ A stanza class for XML content of the form:
+
+ <action xmlns="sleekxmpp:custom:actions">
+ <method>X</method>
+ <param>X</param>
+ <status>X</status>
+ </action>
+ """
+
+ #: The `name` field refers to the basic XML tag name of the
+ #: stanza. Here, the tag name will be 'action'.
name = 'action'
+
+ #: The namespace of the main XML tag.
namespace = 'sleekxmpp:custom:actions'
+
+ #: The `plugin_attrib` value is the name that can be used
+ #: with a parent stanza to access this stanza. For example
+ #: from an Iq stanza object, accessing:
+ #:
+ #: iq['action']
+ #:
+ #: would reference an Action object, and will even create
+ #: an Action object and append it to the Iq stanza if
+ #: one doesn't already exist.
plugin_attrib = 'action'
+
+ #: Stanza objects expose dictionary-like interfaces for
+ #: accessing and manipulating substanzas and other values.
+ #: The set of interfaces defined here are the names of
+ #: these dictionary-like interfaces provided by this stanza
+ #: type. For example, an Action stanza object can use:
+ #:
+ #: action['method'] = 'foo'
+ #: print(action['param'])
+ #: del action['status']
+ #:
+ #: to set, get, or remove its values.
interfaces = set(('method', 'param', 'status'))
+
+ #: By default, values in the `interfaces` set are mapped to
+ #: attribute values. This can be changed such that an interface
+ #: maps to a subelement's text value by adding interfaces to
+ #: the sub_interfaces set. For example, here all interfaces
+ #: are marked as sub_interfaces, and so the XML produced will
+ #: look like:
+ #:
+ #: <action xmlns="sleekxmpp:custom:actions">
+ #: <method>foo</method>
+ #: </action>
sub_interfaces = interfaces