summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-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.rst17
-rw-r--r--docs/index.rst14
-rw-r--r--sleekxmpp/xmlstream/stanzabase.py2
-rw-r--r--sleekxmpp/xmlstream/tostring.py63
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: