From b87c4d786d1c093af3368b8bcfb9c3754fc1ba7a Mon Sep 17 00:00:00 2001 From: Lance Stout Date: Tue, 22 Nov 2011 16:25:33 -0800 Subject: Update tostring docs, plus more doc cleanup --- docs/api/basexmpp.rst | 2 +- docs/api/clientxmpp.rst | 13 ++----------- docs/api/componentxmpp.rst | 8 ++++++++ docs/api/xmlstream/stanzabase.rst | 12 ++++++------ docs/api/xmlstream/tostring.rst | 39 +++++++++++++++++++++++++++++++++----- docs/conf.py | 2 ++ docs/index.rst | 4 +++- docs/python-objects.inv | Bin 0 -> 105830 bytes sleekxmpp/xmlstream/tostring.py | 7 ++++--- 9 files changed, 60 insertions(+), 27 deletions(-) create mode 100644 docs/api/componentxmpp.rst create mode 100644 docs/python-objects.inv diff --git a/docs/api/basexmpp.rst b/docs/api/basexmpp.rst index 841df3db..fa96322e 100644 --- a/docs/api/basexmpp.rst +++ b/docs/api/basexmpp.rst @@ -1,5 +1,5 @@ ======== -basexmpp +BaseXMPP ======== .. module:: sleekxmpp.basexmpp diff --git a/docs/api/clientxmpp.rst b/docs/api/clientxmpp.rst index 8f87664e..a6f32c43 100644 --- a/docs/api/clientxmpp.rst +++ b/docs/api/clientxmpp.rst @@ -1,17 +1,8 @@ ========== -clientxmpp +ClientXMPP ========== .. module:: sleekxmpp.clientxmpp .. autoclass:: ClientXMPP - - .. automethod:: connect - - .. automethod:: register_feature - - .. automethod:: get_roster - - .. automethod:: update_roster - - .. automethod:: del_roster_item + :members: diff --git a/docs/api/componentxmpp.rst b/docs/api/componentxmpp.rst new file mode 100644 index 00000000..989120c2 --- /dev/null +++ b/docs/api/componentxmpp.rst @@ -0,0 +1,8 @@ +============= +ComponentXMPP +============= + +.. module:: sleekxmpp.componentxmpp + +.. autoclass:: ComponentXMPP + :members: diff --git a/docs/api/xmlstream/stanzabase.rst b/docs/api/xmlstream/stanzabase.rst index afed7655..f575299e 100644 --- a/docs/api/xmlstream/stanzabase.rst +++ b/docs/api/xmlstream/stanzabase.rst @@ -1,13 +1,13 @@ .. _stanzabase: -========== -stanzabase -========== +============== +Stanza Objects +============== .. 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 +The :mod:`~sleekmxpp.xmlstream.stanzabase` module provides a wrapper for the +standard :mod:`~xml.etree.ElementTree` 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 @@ -52,7 +52,7 @@ elements of the original XML chunk. .. seealso:: :ref:`create-stanza-interfaces`. -Because the :mod:`sleekxmpp.xmlstream.stanzabase` module was developed +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 diff --git a/docs/api/xmlstream/tostring.rst b/docs/api/xmlstream/tostring.rst index 038b7876..82a8c2a5 100644 --- a/docs/api/xmlstream/tostring.rst +++ b/docs/api/xmlstream/tostring.rst @@ -1,17 +1,46 @@ -======== -tostring -======== - .. module:: sleekxmpp.xmlstream.tostring .. _tostring: XML Serialization ------------------ +================= + +Since the XML layer of SleekXMPP is based on :mod:`~xml.etree.ElementTree`, +why not just use the built-in :func:`~xml.etree.ElementTree.tostring` +method? The answer is that using that method produces ugly results when +using namespaces. The :func:`tostring()` method used here intelligently +hides namespaces when able and does not introduce excessive namespace +prefixes:: + + >>> from sleekxmpp.xmlstream.tostring import tostring + >>> from xml.etree import cElementTree as ET + >>> xml = ET.fromstring('') + >>> ET.tostring(xml) + '' + >>> tostring(xml) + '' + +As a side effect of this namespace hiding, using :func:`tostring()` may +produce unexpected results depending on how the :func:`tostring()` method +is invoked. For example, when sending XML on the wire, the main XMPP +stanzas with their namespace of ``jabber:client`` will not include the +namespace because that is already declared by the stream header. But, if +you create a :class:`~sleekxmpp.stanza.message.Message` instance and dump +it to the terminal, the ``jabber:client`` namespace will appear. .. autofunction:: tostring Escaping Special Characters --------------------------- +In order to prevent errors when sending arbitrary text as the textual +content of an XML element, certain characters must be escaped. These +are: ``&``, ``<``, ``>``, ``"``, and ``'``. The default escaping +mechanism is to replace those characters with their equivalent escape +entities: ``&``, ``<``, ``>``, ``'``, and ``"``. + +In the future, the use of CDATA sections may be allowed to reduce the +size of escaped text or for when other XMPP processing agents do not +undertand these entities. + .. autofunction:: xml_escape diff --git a/docs/conf.py b/docs/conf.py index 8a49e062..cbebd6ce 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -218,3 +218,5 @@ man_pages = [ ('index', 'sleekxmpp', u'SleekXMPP Documentation', [u'Nathan Fritz, Lance Stout'], 1) ] + +intersphinx_mapping = {'python': ('http://docs.python.org/3.2', 'python-objects.inv')} diff --git a/docs/index.rst b/docs/index.rst index 525a479f..cb5b327e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -110,8 +110,10 @@ API Reference event_index api/clientxmpp + api/componentxmpp api/basexmpp - api/xmlstream/index + api/xmlstream/stanzabase + api/xmlstream/tostring Additional Info --------------- diff --git a/docs/python-objects.inv b/docs/python-objects.inv new file mode 100644 index 00000000..b7afc07e Binary files /dev/null and b/docs/python-objects.inv differ diff --git a/sleekxmpp/xmlstream/tostring.py b/sleekxmpp/xmlstream/tostring.py index ed58049e..8e729f79 100644 --- a/sleekxmpp/xmlstream/tostring.py +++ b/sleekxmpp/xmlstream/tostring.py @@ -27,9 +27,7 @@ def tostring(xml=None, xmlns='', stanza_ns='', stream=None, 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 XML xml: The XML object to serialize. :param string xmlns: Optional namespace of an element wrapping the XML object. :param string stanza_ns: The namespace of the stanza object that contains @@ -40,6 +38,8 @@ def tostring(xml=None, xmlns='', stanza_ns='', stream=None, :param bool top_level: Indicates that the element is the outermost element. + + :type xml: :py:class:`~xml.etree.ElementTree.Element` :type stream: :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream` :rtype: Unicode string @@ -114,6 +114,7 @@ def xml_escape(text): """Convert special characters in XML to escape sequences. :param string text: The XML text to convert. + :rtype: Unicode string """ if sys.version_info < (3, 0): if type(text) != types.UnicodeType: -- cgit v1.2.3