diff --git a/docs/api/basexmpp.rst b/docs/api/basexmpp.rst index 841df3d..fa96322 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 8f87664..a6f32c4 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 0000000..989120c --- /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 afed765..f575299 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 038b787..82a8c2a 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 8a49e06..cbebd6c 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 525a479..cb5b327 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 0000000..b7afc07 Binary files /dev/null and b/docs/python-objects.inv differ diff --git a/sleekxmpp/xmlstream/tostring.py b/sleekxmpp/xmlstream/tostring.py index ed58049..8e729f7 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: