diff options
| -rw-r--r-- | docs/api/xmlstream/index.rst (renamed from docs/api/xmlstream.rst) | 1 | ||||
| -rw-r--r-- | docs/api/xmlstream/stanzabase.rst (renamed from docs/api/stanzabase.rst) | 2 | ||||
| -rw-r--r-- | docs/api/xmlstream/tostring.rst | 17 | ||||
| -rw-r--r-- | docs/index.rst | 14 | ||||
| -rw-r--r-- | sleekxmpp/xmlstream/stanzabase.py | 2 | ||||
| -rw-r--r-- | sleekxmpp/xmlstream/tostring.py | 63 |
6 files changed, 60 insertions, 39 deletions
diff --git a/docs/api/xmlstream.rst b/docs/api/xmlstream/index.rst index 65200f66..22f9f3ff 100644 --- a/docs/api/xmlstream.rst +++ b/docs/api/xmlstream/index.rst @@ -10,3 +10,4 @@ xmlstream .. toctree:: stanzabase + tostring diff --git a/docs/api/stanzabase.rst b/docs/api/xmlstream/stanzabase.rst index 5a2c9a06..afed7655 100644 --- a/docs/api/stanzabase.rst +++ b/docs/api/xmlstream/stanzabase.rst @@ -1,3 +1,5 @@ +.. _stanzabase: + ========== stanzabase ========== diff --git a/docs/api/xmlstream/tostring.rst b/docs/api/xmlstream/tostring.rst new file mode 100644 index 00000000..038b7876 --- /dev/null +++ b/docs/api/xmlstream/tostring.rst @@ -0,0 +1,17 @@ +======== +tostring +======== + +.. module:: sleekxmpp.xmlstream.tostring + +.. _tostring: + +XML Serialization +----------------- + +.. autofunction:: tostring + +Escaping Special Characters +--------------------------- + +.. autofunction:: xml_escape diff --git a/docs/index.rst b/docs/index.rst index 6898b506..525a479f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,16 +12,8 @@ SleekXMPP ``master`` branch, while the latest development version is in the ``develop`` branch. - **Stable Releases** + **Latest Stable Release** - `1.0 RC3 <http://github.com/fritzy/SleekXMPP/zipball/1.0-RC3>`_ - - `1.0 RC2 <http://github.com/fritzy/SleekXMPP/zipball/1.0-RC2>`_ - - `1.0 RC1 <http://github.com/fritzy/SleekXMPP/zipball/1.0-RC1>`_ - - `1.0 Beta6.1 <http://github.com/fritzy/SleekXMPP/zipball/1.0-Beta6.1>`_ - - `1.0 Beta5 <http://github.com/fritzy/SleekXMPP/zipball/1.0-Beta5>`_ - - `1.0 Beta4 <http://github.com/fritzy/SleekXMPP/zipball/1.0-Beta4>`_ - - `1.0 Beta3 <http://github.com/fritzy/SleekXMPP/zipball/1.0-Beta3>`_ - - `1.0 Beta2 <http://github.com/fritzy/SleekXMPP/zipball/1.0-Beta2>`_ - - `1.0 Beta1 <http://github.com/fritzy/SleekXMPP/zipball/1.0-Beta1>`_ **Develop Releases** - `Latest Develop Version <http://github.com/fritzy/SleekXMPP/zipball/develop>`_ @@ -90,7 +82,7 @@ Tutorials, FAQs, and How To Guides faq xeps xmpp_tdg - create_stanzas + howto/stanzas create_plugin features sasl @@ -119,7 +111,7 @@ API Reference event_index api/clientxmpp api/basexmpp - api/xmlstream + api/xmlstream/index Additional Info --------------- 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: |