diff options
Diffstat (limited to 'sleekxmpp/xmlstream')
| -rw-r--r-- | sleekxmpp/xmlstream/stanzabase.py | 2 | ||||
| -rw-r--r-- | sleekxmpp/xmlstream/tostring.py | 63 |
2 files changed, 37 insertions, 28 deletions
diff --git a/sleekxmpp/xmlstream/stanzabase.py b/sleekxmpp/xmlstream/stanzabase.py index 2af5ec3c..6f27c361 100644 --- a/sleekxmpp/xmlstream/stanzabase.py +++ b/sleekxmpp/xmlstream/stanzabase.py @@ -1071,6 +1071,8 @@ class ElementBase(object): def __str__(self, top_level_ns=True): """Return a string serialization of the underlying XML object. + .. seealso:: :ref:`tostring` + :param bool top_level_ns: Display the top-most namespace. Defaults to True. """ diff --git a/sleekxmpp/xmlstream/tostring.py b/sleekxmpp/xmlstream/tostring.py index f9674b15..ed58049e 100644 --- a/sleekxmpp/xmlstream/tostring.py +++ b/sleekxmpp/xmlstream/tostring.py @@ -1,9 +1,16 @@ +# -*- coding: utf-8 -*- """ - SleekXMPP: The Sleek XMPP Library - Copyright (C) 2010 Nathanael C. Fritz - This file is part of SleekXMPP. + sleekxmpp.xmlstream.tostring + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - See the file LICENSE for copying permission. + This module converts XML objects into Unicode strings and + intelligently includes namespaces only when necessary to + keep the output readable. + + Part of SleekXMPP: The Sleek XMPP Library + + :copyright: (c) 2011 Nathanael C. Fritz + :license: MIT, see LICENSE for more details """ import sys @@ -14,26 +21,28 @@ if sys.version_info < (3, 0): def tostring(xml=None, xmlns='', stanza_ns='', stream=None, outbuffer='', top_level=False): - """ - Serialize an XML object to a Unicode string. - - If namespaces are provided using xmlns or stanza_ns, then elements - that use those namespaces will not include the xmlns attribute in - the output. - - Arguments: - xml -- The XML object to serialize. If the value is None, - then the XML object contained in this stanza - object will be used. - xmlns -- Optional namespace of an element wrapping the XML - object. - stanza_ns -- The namespace of the stanza object that contains - the XML object. - stream -- The XML stream that generated the XML object. - outbuffer -- Optional buffer for storing serializations during - recursive calls. - top_level -- Indicates that the element is the outermost - element. + """Serialize an XML object to a Unicode string. + + If namespaces are provided using ``xmlns`` or ``stanza_ns``, then + elements that use those namespaces will not include the xmlns attribute + in the output. + + :param XML xml: The XML object to serialize. If the value is ``None``, + then the XML object contained in this stanza + object will be used. + :param string xmlns: Optional namespace of an element wrapping the XML + object. + :param string stanza_ns: The namespace of the stanza object that contains + the XML object. + :param stream: The XML stream that generated the XML object. + :param string outbuffer: Optional buffer for storing serializations + during recursive calls. + :param bool top_level: Indicates that the element is the outermost + element. + + :type stream: :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream` + + :rtype: Unicode string """ # Add previous results to the start of the output. output = [outbuffer] @@ -102,11 +111,9 @@ def tostring(xml=None, xmlns='', stanza_ns='', stream=None, def xml_escape(text): - """ - Convert special characters in XML to escape sequences. + """Convert special characters in XML to escape sequences. - Arguments: - text -- The XML text to convert. + :param string text: The XML text to convert. """ if sys.version_info < (3, 0): if type(text) != types.UnicodeType: |