From b87c4d786d1c093af3368b8bcfb9c3754fc1ba7a Mon Sep 17 00:00:00 2001 From: Lance Stout Date: Tue, 22 Nov 2011 16:25:33 -0800 Subject: Update tostring docs, plus more doc cleanup --- docs/api/xmlstream/tostring.rst | 39 ++++++++++++++++++++++++++++++++++----- 1 file changed, 34 insertions(+), 5 deletions(-) (limited to 'docs/api/xmlstream/tostring.rst') 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('') + >>> ET.tostring(xml) + '' + >>> tostring(xml) + '' + +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: ``&``, ``<``, ``>``, ``'``, and ``"``. + +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 -- cgit v1.2.3