pep/slixmpp
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
slixmpp/docs/architecture.rst

151 lines
5.4 KiB
ReStructuredText
Raw Normal View History

Start of docs for 1.0
2011-08-13 00:33:32 +00:00
.. index:: XMLStream, BaseXMPP, ClientXMPP, ComponentXMPP
Rename to slixmpp
2014-07-17 12:19:04 +00:00
Slixmpp Architecture
Start of docs for 1.0
2011-08-13 00:33:32 +00:00
======================
Rename to slixmpp
2014-07-17 12:19:04 +00:00
The core of Slixmpp is contained in four classes: ``XMLStream``,
Start of docs for 1.0
2011-08-13 00:33:32 +00:00
``BaseXMPP``, ``ClientXMPP``, and ``ComponentXMPP``. Along side this
stack is a library for working with XML objects that eliminates most
of the tedium of creating/manipulating XML.
.. image:: _static/images/arch_layers.png
:height: 300px
:align: center
.. index:: XMLStream
The Foundation: XMLStream
-------------------------
Rename to slixmpp
2014-07-17 12:19:04 +00:00
:class:`~slixmpp.xmlstream.xmlstream.XMLStream` is a mostly XMPP-agnostic
Some more docs house cleaning
2011-11-22 23:25:24 +00:00
class whose purpose is to read and write from a bi-directional XML stream.
It also allows for callback functions to execute when XML matching given
patterns is received; these callbacks are also referred to as :term:`stream
handlers <stream handler>`. The class also provides a basic eventing system
which can be triggered either manually or on a timed schedule.
Start of docs for 1.0
2011-08-13 00:33:32 +00:00
Update the documentation and examples - update most of the examples with slixmpp - change the help channels pointed out in the doc - add a page listing differences from slixmpp and how to use asyncio nicely with slixmpp - fix some in-code rst documentation
2015-02-24 17:58:40 +00:00
The event loop
~~~~~~~~~~~~~~
:class:`~slixmpp.xmlstream.xmlstream.XMLStream` instances inherit the
:class:`asyncio.BaseProtocol` class, and therefore do not have to handle
reads and writes directly, but receive data through
:meth:`~slixmpp.xmlstream.xmlstream.XMLStream.data_received` and write
data in the socket transport.
Upon receiving data, :term:`stream handlers <stream handler>` are run
immediately, except if they are coroutines, in which case they are
scheduled using :meth:`asyncio.async`.
:term:`Event handlers <event handler>` (which are called inside
:term:`stream handlers <stream handler>`) work the same way.
Start of docs for 1.0
2011-08-13 00:33:32 +00:00
How XML Text is Turned into Action
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To demonstrate the flow of information, let's consider what happens
when this bit of XML is received (with an assumed namespace of
``jabber:client``):
.. code-block:: xml
<message to="user@example.com" from="friend@example.net">
<body>Hej!</body>
</message>
Update the documentation and examples - update most of the examples with slixmpp - change the help channels pointed out in the doc - add a page listing differences from slixmpp and how to use asyncio nicely with slixmpp - fix some in-code rst documentation
2015-02-24 17:58:40 +00:00
#. **Convert XML strings into objects.**
Start of docs for 1.0
2011-08-13 00:33:32 +00:00
Incoming text is parsed and converted into XML objects (using
ElementTree) which are then wrapped into what are referred to as
:term:`Stanza objects <stanza object>`. The appropriate class for the
new object is determined using a map of namespaced element names to
classes.
Rename to slixmpp
2014-07-17 12:19:04 +00:00
Our incoming XML is thus turned into a :class:`~slixmpp.stanza.Message`
Some more docs house cleaning
2011-11-22 23:25:24 +00:00
:term:`stanza object` because the namespaced element name
``{jabber:client}message`` is associated with the class
Rename to slixmpp
2014-07-17 12:19:04 +00:00
:class:`~slixmpp.stanza.Message`.
Start of docs for 1.0
2011-08-13 00:33:32 +00:00
Update the documentation and examples - update most of the examples with slixmpp - change the help channels pointed out in the doc - add a page listing differences from slixmpp and how to use asyncio nicely with slixmpp - fix some in-code rst documentation
2015-02-24 17:58:40 +00:00
#. **Match stanza objects to callbacks.**
Start of docs for 1.0
2011-08-13 00:33:32 +00:00
These objects are then compared against the stored patterns associated
Update the documentation and examples - update most of the examples with slixmpp - change the help channels pointed out in the doc - add a page listing differences from slixmpp and how to use asyncio nicely with slixmpp - fix some in-code rst documentation
2015-02-24 17:58:40 +00:00
with the registered callback handlers.
Start of docs for 1.0
2011-08-13 00:33:32 +00:00
Update the documentation and examples - update most of the examples with slixmpp - change the help channels pointed out in the doc - add a page listing differences from slixmpp and how to use asyncio nicely with slixmpp - fix some in-code rst documentation
2015-02-24 17:58:40 +00:00
Each handler matching our :term:`stanza object` is then added to a list.
Start of docs for 1.0
2011-08-13 00:33:32 +00:00
Update the documentation and examples - update most of the examples with slixmpp - change the help channels pointed out in the doc - add a page listing differences from slixmpp and how to use asyncio nicely with slixmpp - fix some in-code rst documentation
2015-02-24 17:58:40 +00:00
#. **Processing callbacks**
Start of docs for 1.0
2011-08-13 00:33:32 +00:00
Update the documentation and examples - update most of the examples with slixmpp - change the help channels pointed out in the doc - add a page listing differences from slixmpp and how to use asyncio nicely with slixmpp - fix some in-code rst documentation
2015-02-24 17:58:40 +00:00
Every handler in the list is then called with the :term:`stanza object`
as a parameter; if the handler is a
:class:`~slixmpp.xmlstream.handler.CoroutineCallback`
then it will be scheduled in the event loop using :meth:`asyncio.async`
instead of run.
Start of docs for 1.0
2011-08-13 00:33:32 +00:00
Update the documentation and examples - update most of the examples with slixmpp - change the help channels pointed out in the doc - add a page listing differences from slixmpp and how to use asyncio nicely with slixmpp - fix some in-code rst documentation
2015-02-24 17:58:40 +00:00
#. **Raise Custom Events**
Start of docs for 1.0
2011-08-13 00:33:32 +00:00
Since a :term:`stream handler` shouldn't block, if extensive processing
for a stanza is required (such as needing to send and receive an
Rename to slixmpp
2014-07-17 12:19:04 +00:00
:class:`~slixmpp.stanza.Iq` stanza), then custom events must be used.
Some more docs house cleaning
2011-11-22 23:25:24 +00:00
These events are not explicitly tied to the incoming XML stream and may
Update the documentation and examples - update most of the examples with slixmpp - change the help channels pointed out in the doc - add a page listing differences from slixmpp and how to use asyncio nicely with slixmpp - fix some in-code rst documentation
2015-02-24 17:58:40 +00:00
be raised at any time.
Start of docs for 1.0
2011-08-13 00:33:32 +00:00
Update the documentation and examples - update most of the examples with slixmpp - change the help channels pointed out in the doc - add a page listing differences from slixmpp and how to use asyncio nicely with slixmpp - fix some in-code rst documentation
2015-02-24 17:58:40 +00:00
In contrast to :term:`stream handlers <stream handler>`, these functions
are referred to as :term:`event handlers <event handler>`.
Start of docs for 1.0
2011-08-13 00:33:32 +00:00
Some more docs house cleaning
2011-11-22 23:25:24 +00:00
The code for :meth:`BaseXMPP._handle_message` follows this pattern, and
Update the documentation and examples - update most of the examples with slixmpp - change the help channels pointed out in the doc - add a page listing differences from slixmpp and how to use asyncio nicely with slixmpp - fix some in-code rst documentation
2015-02-24 17:58:40 +00:00
raises a ``'message'`` event
Start of docs for 1.0
2011-08-13 00:33:32 +00:00
Update the documentation and examples - update most of the examples with slixmpp - change the help channels pointed out in the doc - add a page listing differences from slixmpp and how to use asyncio nicely with slixmpp - fix some in-code rst documentation
2015-02-24 17:58:40 +00:00
.. code-block:: python
Start of docs for 1.0
2011-08-13 00:33:32 +00:00
Update the documentation and examples - update most of the examples with slixmpp - change the help channels pointed out in the doc - add a page listing differences from slixmpp and how to use asyncio nicely with slixmpp - fix some in-code rst documentation
2015-02-24 17:58:40 +00:00
self.event('message', msg)
Start of docs for 1.0
2011-08-13 00:33:32 +00:00
Update the documentation and examples - update most of the examples with slixmpp - change the help channels pointed out in the doc - add a page listing differences from slixmpp and how to use asyncio nicely with slixmpp - fix some in-code rst documentation
2015-02-24 17:58:40 +00:00
#. **Process Custom Events**
Start of docs for 1.0
2011-08-13 00:33:32 +00:00
Update the documentation and examples - update most of the examples with slixmpp - change the help channels pointed out in the doc - add a page listing differences from slixmpp and how to use asyncio nicely with slixmpp - fix some in-code rst documentation
2015-02-24 17:58:40 +00:00
The :term:`event handlers <event handler>` are then executed, passing
the stanza as the only argument.
Start of docs for 1.0
2011-08-13 00:33:32 +00:00
.. note::
Remove all trailing whitespaces.
2014-08-17 19:53:34 +00:00
Events may be raised without needing :term:`stanza objects <stanza object>`.
For example, you could use ``self.event('custom', {'a': 'b'})``.
You don't even need any arguments: ``self.event('no_parameters')``.
Start of docs for 1.0
2011-08-13 00:33:32 +00:00
However, every event handler MUST accept at least one argument.
Finally, after a long trek, our message is handed off to the user's
custom handler in order to do awesome stuff::
Update the documentation and examples - update most of the examples with slixmpp - change the help channels pointed out in the doc - add a page listing differences from slixmpp and how to use asyncio nicely with slixmpp - fix some in-code rst documentation
2015-02-24 17:58:40 +00:00
reply = msg.reply()
reply['body'] = "Hey! This is awesome!"
reply.send()
Start of docs for 1.0
2011-08-13 00:33:32 +00:00
.. index:: BaseXMPP, XMLStream
Raising XMPP Awareness: BaseXMPP
--------------------------------
Rename to slixmpp
2014-07-17 12:19:04 +00:00
While :class:`~slixmpp.xmlstream.xmlstream.XMLStream` attempts to shy away
from anything too XMPP specific, :class:`~slixmpp.basexmpp.BaseXMPP`'s
Some more docs house cleaning
2011-11-22 23:25:24 +00:00
sole purpose is to provide foundational support for sending and receiving
XMPP stanzas. This support includes registering the basic message,
presence, and iq stanzas, methods for creating and sending stanzas, and
default handlers for incoming messages and keeping track of presence
notifications.
Start of docs for 1.0
2011-08-13 00:33:32 +00:00
The plugin system for adding new XEP support is also maintained by
Rename to slixmpp
2014-07-17 12:19:04 +00:00
:class:`~slixmpp.basexmpp.BaseXMPP`.
Start of docs for 1.0
2011-08-13 00:33:32 +00:00
.. index:: ClientXMPP, BaseXMPP
ClientXMPP
----------
Rename to slixmpp
2014-07-17 12:19:04 +00:00
:class:`~slixmpp.clientxmpp.ClientXMPP` extends
:class:`~slixmpp.clientxmpp.BaseXMPP` with additional logic for connecting
Some more docs house cleaning
2011-11-22 23:25:24 +00:00
to an XMPP server by performing DNS lookups. It also adds support for stream
Start of docs for 1.0
2011-08-13 00:33:32 +00:00
features such as STARTTLS and SASL.
.. index:: ComponentXMPP, BaseXMPP
ComponentXMPP
-------------
Rename to slixmpp
2014-07-17 12:19:04 +00:00
:class:`~slixmpp.componentxmpp.ComponentXMPP` is only a thin layer on top of
:class:`~slixmpp.basexmpp.BaseXMPP` that implements the component handshake
Some more docs house cleaning
2011-11-22 23:25:24 +00:00
protocol.
Reference in a new issue Copy permalink