diff options
| author | Lance Stout <lancestout@gmail.com> | 2012-01-05 11:31:54 -0500 |
|---|---|---|
| committer | Lance Stout <lancestout@gmail.com> | 2012-01-05 11:31:54 -0500 |
| commit | 97378998a5f8c031444fd7a0c1b1007e9282df4d (patch) | |
| tree | e53e087c44d11707532118ad55d0c946f33e2f7f /docs/api/xmlstream | |
| download | slixmpp-97378998a5f8c031444fd7a0c1b1007e9282df4d.tar.gz slixmpp-97378998a5f8c031444fd7a0c1b1007e9282df4d.tar.bz2 slixmpp-97378998a5f8c031444fd7a0c1b1007e9282df4d.tar.xz slixmpp-97378998a5f8c031444fd7a0c1b1007e9282df4d.zip | |
Break the docs out into their own branch.
Diffstat (limited to 'docs/api/xmlstream')
| -rw-r--r-- | docs/api/xmlstream/filesocket.rst | 12 | ||||
| -rw-r--r-- | docs/api/xmlstream/handler.rst | 24 | ||||
| -rw-r--r-- | docs/api/xmlstream/jid.rst | 7 | ||||
| -rw-r--r-- | docs/api/xmlstream/matcher.rst | 41 | ||||
| -rw-r--r-- | docs/api/xmlstream/scheduler.rst | 11 | ||||
| -rw-r--r-- | docs/api/xmlstream/stanzabase.rst | 123 | ||||
| -rw-r--r-- | docs/api/xmlstream/tostring.rst | 46 | ||||
| -rw-r--r-- | docs/api/xmlstream/xmlstream.rst | 10 |
8 files changed, 274 insertions, 0 deletions
diff --git a/docs/api/xmlstream/filesocket.rst b/docs/api/xmlstream/filesocket.rst new file mode 100644 index 00000000..35f44019 --- /dev/null +++ b/docs/api/xmlstream/filesocket.rst @@ -0,0 +1,12 @@ +.. module:: sleekxmpp.xmlstream.filesocket + +.. _filesocket: + +Python 2.6 File Socket Shims +============================ + +.. autoclass:: FileSocket + :members: + +.. autoclass:: Socket26 + :members: diff --git a/docs/api/xmlstream/handler.rst b/docs/api/xmlstream/handler.rst new file mode 100644 index 00000000..33c0bf42 --- /dev/null +++ b/docs/api/xmlstream/handler.rst @@ -0,0 +1,24 @@ +Stanza Handlers +=============== + +The Basic Handler +----------------- +.. module:: sleekxmpp.xmlstream.handler.base + +.. autoclass:: BaseHandler + :members: + +Callback +-------- +.. module:: sleekxmpp.xmlstream.handler.callback + +.. autoclass:: Callback + :members: + + +Waiter +------ +.. module:: sleekxmpp.xmlstream.handler.waiter + +.. autoclass:: Waiter + :members: diff --git a/docs/api/xmlstream/jid.rst b/docs/api/xmlstream/jid.rst new file mode 100644 index 00000000..22a2db45 --- /dev/null +++ b/docs/api/xmlstream/jid.rst @@ -0,0 +1,7 @@ +Jabber IDs (JID) +================= + +.. module:: sleekxmpp.xmlstream.jid + +.. autoclass:: JID + :members: diff --git a/docs/api/xmlstream/matcher.rst b/docs/api/xmlstream/matcher.rst new file mode 100644 index 00000000..df3591bc --- /dev/null +++ b/docs/api/xmlstream/matcher.rst @@ -0,0 +1,41 @@ +Stanza Matchers +=============== + +The Basic Matcher +----------------- +.. module:: sleekxmpp.xmlstream.matcher.base + +.. autoclass:: MatcherBase + :members: + + +ID Matching +----------- +.. module:: sleekxmpp.xmlstream.matcher.id + +.. autoclass:: MatcherId + :members: + + +Stanza Path Matching +-------------------- +.. module:: sleekxmpp.xmlstream.matcher.stanzapath + +.. autoclass:: StanzaPath + :members: + + +XPath +----- +.. module:: sleekxmpp.xmlstream.matcher.xpath + +.. autoclass:: MatchXPath + :members: + + +XMLMask +------- +.. module:: sleekxmpp.xmlstream.matcher.xmlmask + +.. autoclass:: MatchXMLMask + :members: diff --git a/docs/api/xmlstream/scheduler.rst b/docs/api/xmlstream/scheduler.rst new file mode 100644 index 00000000..ff91701e --- /dev/null +++ b/docs/api/xmlstream/scheduler.rst @@ -0,0 +1,11 @@ +========= +Scheduler +========= + +.. module:: sleekxmpp.xmlstream.scheduler + +.. autoclass:: Task + :members: + +.. autoclass:: Scheduler + :members: diff --git a/docs/api/xmlstream/stanzabase.rst b/docs/api/xmlstream/stanzabase.rst new file mode 100644 index 00000000..f575299e --- /dev/null +++ b/docs/api/xmlstream/stanzabase.rst @@ -0,0 +1,123 @@ +.. _stanzabase: + +============== +Stanza Objects +============== + +.. module:: sleekxmpp.xmlstream.stanzabase + +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 +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 + + <message to="user@example.com" from="friend@example.com"> + <body>Hi!</body> + <x:extra> + <x:item>Custom item 1</x:item> + <x:item>Custom item 2</x:item> + <x:item>Custom item 3</x:item> + </x:extra> + </message> + +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 +``<x:item>`` 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 <http://xmpp.org>`_ library, these chunks of XML are +referred to as :term:`stanzas <stanza>`, 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 <stanza>` +or XML chunks easier, :term:`stanza objects <stanza object>` 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 + + <iq type="result"> + <query xmlns="http://jabber.org/protocol/disco#info"> + <identity category="client" type="bot" name="SleekXMPP Bot" /> + </query> + </iq> + +We can can arrange this stanza into two objects: an outer, wrapper object for +dealing with the ``<iq />`` element and its attributes, and a plugin object to +control the ``<query />`` 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'] + '<query xmlns="http://jabber.org/protocol/disco#info"> + <identity category="client" type="bot" name="SleekXMPP Bot" /> + </query>' + +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..82a8c2a5 --- /dev/null +++ b/docs/api/xmlstream/tostring.rst @@ -0,0 +1,46 @@ +.. 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('<foo xmlns="bar"><baz /></foo>') + >>> ET.tostring(xml) + '<ns0:foo xmlns:ns0="bar"><ns0:baz /></foo>' + >>> tostring(xml) + '<foo xmlns="bar"><baz /></foo>' + +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/api/xmlstream/xmlstream.rst b/docs/api/xmlstream/xmlstream.rst new file mode 100644 index 00000000..90a7a6af --- /dev/null +++ b/docs/api/xmlstream/xmlstream.rst @@ -0,0 +1,10 @@ +========== +XML Stream +========== + +.. module:: sleekxmpp.xmlstream.xmlstream + +.. autoexception:: RestartStream + +.. autoclass:: XMLStream + :members: |