From 6906c15e8ee20633ae0bf94fee1a99d916ceedc8 Mon Sep 17 00:00:00 2001 From: Lance Stout Date: Tue, 22 Nov 2011 15:25:02 -0800 Subject: Update docs for tostring --- docs/api/stanzabase.rst | 121 ------------------------------------- docs/api/xmlstream.rst | 12 ---- docs/api/xmlstream/index.rst | 13 ++++ docs/api/xmlstream/stanzabase.rst | 123 ++++++++++++++++++++++++++++++++++++++ docs/api/xmlstream/tostring.rst | 17 ++++++ docs/index.rst | 14 +---- sleekxmpp/xmlstream/stanzabase.py | 2 + sleekxmpp/xmlstream/tostring.py | 63 ++++++++++--------- 8 files changed, 193 insertions(+), 172 deletions(-) delete mode 100644 docs/api/stanzabase.rst delete mode 100644 docs/api/xmlstream.rst create mode 100644 docs/api/xmlstream/index.rst create mode 100644 docs/api/xmlstream/stanzabase.rst create mode 100644 docs/api/xmlstream/tostring.rst diff --git a/docs/api/stanzabase.rst b/docs/api/stanzabase.rst deleted file mode 100644 index 5a2c9a06..00000000 --- a/docs/api/stanzabase.rst +++ /dev/null @@ -1,121 +0,0 @@ -========== -stanzabase -========== - -.. module:: sleekxmpp.xmlstream.stanzabase - -The :mod:`sleekmxpp.xmlstream.stanzabase` module provides a wrapper for the -standard :mod:`xml.etree.cElementTree` module that makes working with XML -less painful. Instead of having to manually move up and down an element -tree and insert subelements and attributes, you can interact with an object -that behaves like a normal dictionary or JSON object, which silently maps -keys to XML attributes and elements behind the scenes. - -Overview --------- - -The usefulness of this layer grows as the XML you have to work with -becomes nested. The base unit here, :class:`ElementBase`, can map to a -single XML element, or several depending on how advanced of a mapping -is desired from interface keys to XML structures. For example, a single -:class:`ElementBase` derived class could easily describe: - -.. code-block:: xml - - - Hi! - - Custom item 1 - Custom item 2 - Custom item 3 - - - -If that chunk of XML were put in the :class:`ElementBase` instance -``msg``, we could extract the data from the XML using:: - - >>> msg['extra'] - ['Custom item 1', 'Custom item 2', 'Custom item 3'] - -Provided we set up the handler for the ``'extra'`` interface to load the -```` element content into a list. - -The key concept is that given an XML structure that will be repeatedly -used, we can define a set of :term:`interfaces` which when we read from, -write to, or delete, will automatically manipulate the underlying XML -as needed. In addition, some of these interfaces may in turn reference -child objects which expose interfaces for particularly complex child -elements of the original XML chunk. - -.. seealso:: - :ref:`create-stanza-interfaces`. - -Because the :mod:`sleekxmpp.xmlstream.stanzabase` module was developed -as part of an `XMPP `_ library, these chunks of XML are -referred to as :term:`stanzas `, and in SleekXMPP we refer to a -subclass of :class:`ElementBase` which defines the interfaces needed for -interacting with a given :term:`stanza` a :term:`stanza object`. - -To make dealing with more complicated and nested :term:`stanzas ` -or XML chunks easier, :term:`stanza objects ` can be -composed in two ways: as iterable child objects or as plugins. Iterable -child stanzas, or :term:`substanzas`, are accessible through a special -``'substanzas'`` interface. This option is useful for stanzas which -may contain more than one of the same kind of element. When there is -only one child element, the plugin method is more useful. For plugins, -a parent stanza object delegates one of its XML child elements to the -plugin stanza object. Here is an example: - -.. code-block:: xml - - - - - - - -We can can arrange this stanza into two objects: an outer, wrapper object for -dealing with the ```` element and its attributes, and a plugin object to -control the ```` payload element. If we give the plugin object the -name ``'disco_info'`` (using its :attr:`ElementBase.plugin_attrib` value), then -we can access the plugin as so:: - - >>> iq['disco_info'] - ' - - ' - -We can then drill down through the plugin object's interfaces as desired:: - - >>> iq['disco_info']['identities'] - [('client', 'bot', 'SleekXMPP Bot')] - -Plugins may also add new interfaces to the parent stanza object as if they -had been defined by the parent directly, and can also override the behaviour -of an interface defined by the parent. - -.. seealso:: - - - :ref:`create-stanza-plugins` - - :ref:`create-extension-plugins` - - :ref:`override-parent-interfaces` - - -Registering Stanza Plugins --------------------------- - -.. autofunction:: register_stanza_plugin - -ElementBase ------------ - -.. autoclass:: ElementBase - :members: - :private-members: - :special-members: - -StanzaBase ----------- - -.. autoclass:: StanzaBase - :members: diff --git a/docs/api/xmlstream.rst b/docs/api/xmlstream.rst deleted file mode 100644 index 65200f66..00000000 --- a/docs/api/xmlstream.rst +++ /dev/null @@ -1,12 +0,0 @@ -========= -xmlstream -========= - -.. module:: sleekxmpp.xmlstream - -.. autoclass:: XMLStream - :members: - -.. toctree:: - - stanzabase diff --git a/docs/api/xmlstream/index.rst b/docs/api/xmlstream/index.rst new file mode 100644 index 00000000..22f9f3ff --- /dev/null +++ b/docs/api/xmlstream/index.rst @@ -0,0 +1,13 @@ +========= +xmlstream +========= + +.. module:: sleekxmpp.xmlstream + +.. autoclass:: XMLStream + :members: + +.. toctree:: + + stanzabase + tostring diff --git a/docs/api/xmlstream/stanzabase.rst b/docs/api/xmlstream/stanzabase.rst new file mode 100644 index 00000000..afed7655 --- /dev/null +++ b/docs/api/xmlstream/stanzabase.rst @@ -0,0 +1,123 @@ +.. _stanzabase: + +========== +stanzabase +========== + +.. module:: sleekxmpp.xmlstream.stanzabase + +The :mod:`sleekmxpp.xmlstream.stanzabase` module provides a wrapper for the +standard :mod:`xml.etree.cElementTree` module that makes working with XML +less painful. Instead of having to manually move up and down an element +tree and insert subelements and attributes, you can interact with an object +that behaves like a normal dictionary or JSON object, which silently maps +keys to XML attributes and elements behind the scenes. + +Overview +-------- + +The usefulness of this layer grows as the XML you have to work with +becomes nested. The base unit here, :class:`ElementBase`, can map to a +single XML element, or several depending on how advanced of a mapping +is desired from interface keys to XML structures. For example, a single +:class:`ElementBase` derived class could easily describe: + +.. code-block:: xml + + + Hi! + + Custom item 1 + Custom item 2 + Custom item 3 + + + +If that chunk of XML were put in the :class:`ElementBase` instance +``msg``, we could extract the data from the XML using:: + + >>> msg['extra'] + ['Custom item 1', 'Custom item 2', 'Custom item 3'] + +Provided we set up the handler for the ``'extra'`` interface to load the +```` element content into a list. + +The key concept is that given an XML structure that will be repeatedly +used, we can define a set of :term:`interfaces` which when we read from, +write to, or delete, will automatically manipulate the underlying XML +as needed. In addition, some of these interfaces may in turn reference +child objects which expose interfaces for particularly complex child +elements of the original XML chunk. + +.. seealso:: + :ref:`create-stanza-interfaces`. + +Because the :mod:`sleekxmpp.xmlstream.stanzabase` module was developed +as part of an `XMPP `_ library, these chunks of XML are +referred to as :term:`stanzas `, and in SleekXMPP we refer to a +subclass of :class:`ElementBase` which defines the interfaces needed for +interacting with a given :term:`stanza` a :term:`stanza object`. + +To make dealing with more complicated and nested :term:`stanzas ` +or XML chunks easier, :term:`stanza objects ` can be +composed in two ways: as iterable child objects or as plugins. Iterable +child stanzas, or :term:`substanzas`, are accessible through a special +``'substanzas'`` interface. This option is useful for stanzas which +may contain more than one of the same kind of element. When there is +only one child element, the plugin method is more useful. For plugins, +a parent stanza object delegates one of its XML child elements to the +plugin stanza object. Here is an example: + +.. code-block:: xml + + + + + + + +We can can arrange this stanza into two objects: an outer, wrapper object for +dealing with the ```` element and its attributes, and a plugin object to +control the ```` payload element. If we give the plugin object the +name ``'disco_info'`` (using its :attr:`ElementBase.plugin_attrib` value), then +we can access the plugin as so:: + + >>> iq['disco_info'] + ' + + ' + +We can then drill down through the plugin object's interfaces as desired:: + + >>> iq['disco_info']['identities'] + [('client', 'bot', 'SleekXMPP Bot')] + +Plugins may also add new interfaces to the parent stanza object as if they +had been defined by the parent directly, and can also override the behaviour +of an interface defined by the parent. + +.. seealso:: + + - :ref:`create-stanza-plugins` + - :ref:`create-extension-plugins` + - :ref:`override-parent-interfaces` + + +Registering Stanza Plugins +-------------------------- + +.. autofunction:: register_stanza_plugin + +ElementBase +----------- + +.. autoclass:: ElementBase + :members: + :private-members: + :special-members: + +StanzaBase +---------- + +.. autoclass:: StanzaBase + :members: 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 `_ - - `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 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: -- cgit v1.2.3