From 6906c15e8ee20633ae0bf94fee1a99d916ceedc8 Mon Sep 17 00:00:00 2001 From: Lance Stout Date: Tue, 22 Nov 2011 15:25:02 -0800 Subject: [PATCH] Update docs for tostring --- docs/api/{xmlstream.rst => xmlstream/index.rst} | 1 + docs/api/{ => xmlstream}/stanzabase.rst | 2 + docs/api/xmlstream/tostring.rst | 17 +++++++ docs/index.rst | 14 ++---- sleekxmpp/xmlstream/stanzabase.py | 2 + sleekxmpp/xmlstream/tostring.py | 63 ++++++++++++++----------- 6 files changed, 60 insertions(+), 39 deletions(-) rename docs/api/{xmlstream.rst => xmlstream/index.rst} (91%) rename docs/api/{ => xmlstream}/stanzabase.rst (99%) create mode 100644 docs/api/xmlstream/tostring.rst diff --git a/docs/api/xmlstream.rst b/docs/api/xmlstream/index.rst similarity index 91% rename from docs/api/xmlstream.rst rename to docs/api/xmlstream/index.rst index 65200f6..22f9f3f 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 similarity index 99% rename from docs/api/stanzabase.rst rename to docs/api/xmlstream/stanzabase.rst index 5a2c9a0..afed765 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 0000000..038b787 --- /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 6898b50..525a479 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 `_ - - `1.0 RC2 `_ - - `1.0 RC1 `_ - - `1.0 Beta6.1 `_ - - `1.0 Beta5 `_ - - `1.0 Beta4 `_ - - `1.0 Beta3 `_ - - `1.0 Beta2 `_ - - `1.0 Beta1 `_ **Develop Releases** - `Latest Develop Version `_ @@ -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 2af5ec3..6f27c36 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 f9674b1..ed58049 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: -- 2.11.4.GIT