summaryrefslogtreecommitdiff
path: root/docs/api/xmlstream/tostring.rst
diff options
context:
space:
mode:
authorLance Stout <lancestout@gmail.com>2012-01-05 11:31:54 -0500
committerLance Stout <lancestout@gmail.com>2012-01-05 11:31:54 -0500
commit97378998a5f8c031444fd7a0c1b1007e9282df4d (patch)
treee53e087c44d11707532118ad55d0c946f33e2f7f /docs/api/xmlstream/tostring.rst
downloadslixmpp-97378998a5f8c031444fd7a0c1b1007e9282df4d.tar.gz
slixmpp-97378998a5f8c031444fd7a0c1b1007e9282df4d.tar.bz2
slixmpp-97378998a5f8c031444fd7a0c1b1007e9282df4d.tar.xz
slixmpp-97378998a5f8c031444fd7a0c1b1007e9282df4d.zip
Break the docs out into their own branch.
Diffstat (limited to 'docs/api/xmlstream/tostring.rst')
-rw-r--r--docs/api/xmlstream/tostring.rst46
1 files changed, 46 insertions, 0 deletions
diff --git a/docs/api/xmlstream/tostring.rst b/docs/api/xmlstream/tostring.rst
new file mode 100644
index 00000000..82a8c2a5
--- /dev/null
+++ b/docs/api/xmlstream/tostring.rst
@@ -0,0 +1,46 @@
+.. 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