summaryrefslogtreecommitdiff
path: root/docs/api/xmlstream/tostring.rst
diff options
context:
space:
mode:
authorLance Stout <lancestout@gmail.com>2011-11-22 16:25:33 -0800
committerLance Stout <lancestout@gmail.com>2011-11-22 16:25:33 -0800
commitb87c4d786d1c093af3368b8bcfb9c3754fc1ba7a (patch)
tree435e41e36c61c77c1118996b6eaba17e22f12f37 /docs/api/xmlstream/tostring.rst
parent329b0df3f6e5649fde4716ad3acc661bdd3b4901 (diff)
downloadslixmpp-b87c4d786d1c093af3368b8bcfb9c3754fc1ba7a.tar.gz
slixmpp-b87c4d786d1c093af3368b8bcfb9c3754fc1ba7a.tar.bz2
slixmpp-b87c4d786d1c093af3368b8bcfb9c3754fc1ba7a.tar.xz
slixmpp-b87c4d786d1c093af3368b8bcfb9c3754fc1ba7a.zip
Update tostring docs, plus more doc cleanup
Diffstat (limited to 'docs/api/xmlstream/tostring.rst')
-rw-r--r--docs/api/xmlstream/tostring.rst39
1 files changed, 34 insertions, 5 deletions
diff --git a/docs/api/xmlstream/tostring.rst b/docs/api/xmlstream/tostring.rst
index 038b7876..82a8c2a5 100644
--- a/docs/api/xmlstream/tostring.rst
+++ b/docs/api/xmlstream/tostring.rst
@@ -1,17 +1,46 @@
-========
-tostring
-========
-
.. module:: sleekxmpp.xmlstream.tostring
.. _tostring:
XML Serialization
------------------
+=================
+
+Since the XML layer of SleekXMPP is based on :mod:`~xml.etree.ElementTree`,
+why not just use the built-in :func:`~xml.etree.ElementTree.tostring`
+method? The answer is that using that method produces ugly results when
+using namespaces. The :func:`tostring()` method used here intelligently
+hides namespaces when able and does not introduce excessive namespace
+prefixes::
+
+ >>> from sleekxmpp.xmlstream.tostring import tostring
+ >>> from xml.etree import cElementTree as ET
+ >>> xml = ET.fromstring('<foo xmlns="bar"><baz /></foo>')
+ >>> ET.tostring(xml)
+ '<ns0:foo xmlns:ns0="bar"><ns0:baz /></foo>'
+ >>> tostring(xml)
+ '<foo xmlns="bar"><baz /></foo>'
+
+As a side effect of this namespace hiding, using :func:`tostring()` may
+produce unexpected results depending on how the :func:`tostring()` method
+is invoked. For example, when sending XML on the wire, the main XMPP
+stanzas with their namespace of ``jabber:client`` will not include the
+namespace because that is already declared by the stream header. But, if
+you create a :class:`~sleekxmpp.stanza.message.Message` instance and dump
+it to the terminal, the ``jabber:client`` namespace will appear.
.. autofunction:: tostring
Escaping Special Characters
---------------------------
+In order to prevent errors when sending arbitrary text as the textual
+content of an XML element, certain characters must be escaped. These
+are: ``&``, ``<``, ``>``, ``"``, and ``'``. The default escaping
+mechanism is to replace those characters with their equivalent escape
+entities: ``&amp;``, ``&lt;``, ``&gt;``, ``&apos;``, and ``&quot;``.
+
+In the future, the use of CDATA sections may be allowed to reduce the
+size of escaped text or for when other XMPP processing agents do not
+undertand these entities.
+
.. autofunction:: xml_escape