Merge branch 'documentation-update' into 'master'
Documentation update See merge request poezio/slixmpp!116
This commit is contained in:
commit
c486c0e821
15 changed files with 121 additions and 108 deletions
16
docs/api/index.rst
Normal file
16
docs/api/index.rst
Normal file
|
@ -0,0 +1,16 @@
|
|||
API Reference
|
||||
-------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
|
||||
clientxmpp
|
||||
componentxmpp
|
||||
basexmpp
|
||||
exceptions
|
||||
xmlstream/jid
|
||||
xmlstream/stanzabase
|
||||
xmlstream/handler
|
||||
xmlstream/matcher
|
||||
xmlstream/xmlstream
|
||||
xmlstream/tostring
|
11
docs/api/stanza/index.rst
Normal file
11
docs/api/stanza/index.rst
Normal file
|
@ -0,0 +1,11 @@
|
|||
|
||||
Core Stanzas
|
||||
------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
rootstanza
|
||||
message
|
||||
presence
|
||||
iq
|
15
docs/getting_started/index.rst
Normal file
15
docs/getting_started/index.rst
Normal file
|
@ -0,0 +1,15 @@
|
|||
Getting Started (with examples)
|
||||
-------------------------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
|
||||
echobot
|
||||
sendlogout
|
||||
component
|
||||
presence
|
||||
muc
|
||||
proxy
|
||||
scheduler
|
||||
iq
|
||||
|
|
@ -3,7 +3,7 @@ Send/Receive IQ Stanzas
|
|||
|
||||
Unlike :class:`~slixmpp.stanza.message.Message` and
|
||||
:class:`~slixmpp.stanza.presence.Presence` stanzas which only use
|
||||
text data for basic usage, :class:`~slixmpp.stanza.iq.Iq` stanzas
|
||||
text data for basic usage, :class:`~slixmpp.stanza.Iq` stanzas
|
||||
require using XML payloads, and generally entail creating a new
|
||||
Slixmpp plugin to provide the necessary convenience methods to
|
||||
make working with them easier.
|
||||
|
@ -11,7 +11,7 @@ make working with them easier.
|
|||
Basic Use
|
||||
---------
|
||||
|
||||
XMPP's use of :class:`~slixmpp.stanza.iq.Iq` stanzas is built around
|
||||
XMPP's use of :class:`~slixmpp.stanza.Iq` stanzas is built around
|
||||
namespaced ``<query />`` elements. For clients, just sending the
|
||||
empty ``<query />`` element will suffice for retrieving information. For
|
||||
example, a very basic implementation of service discovery would just
|
||||
|
@ -26,7 +26,7 @@ need to be able to send:
|
|||
Creating Iq Stanzas
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Slixmpp provides built-in support for creating basic :class:`~slixmpp.stanza.iq.Iq`
|
||||
Slixmpp provides built-in support for creating basic :class:`~slixmpp.stanza.Iq`
|
||||
stanzas this way. The relevant methods are:
|
||||
|
||||
* :meth:`~slixmpp.basexmpp.BaseXMPP.make_iq`
|
||||
|
@ -37,7 +37,7 @@ stanzas this way. The relevant methods are:
|
|||
* :meth:`~slixmpp.basexmpp.BaseXMPP.make_iq_query`
|
||||
|
||||
These methods all follow the same pattern: create or modify an existing
|
||||
:class:`~slixmpp.stanza.iq.Iq` stanza, set the ``'type'`` value based
|
||||
:class:`~slixmpp.stanza.Iq` stanza, set the ``'type'`` value based
|
||||
on the method name, and finally add a ``<query />`` element with the given
|
||||
namespace. For example, to produce the query above, you would use:
|
||||
|
||||
|
@ -50,19 +50,17 @@ namespace. For example, to produce the query above, you would use:
|
|||
Sending Iq Stanzas
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Once an :class:`~slixmpp.stanza.iq.Iq` stanza is created, sending it
|
||||
over the wire is done using its :meth:`~slixmpp.stanza.iq.Iq.send()`
|
||||
Once an :class:`~slixmpp.stanza.Iq` stanza is created, sending it
|
||||
over the wire is done using its :meth:`~slixmpp.stanza.Iq.send()`
|
||||
method, like any other stanza object. However, there are a few extra
|
||||
options to control how to wait for the query's response.
|
||||
options to control how to wait for the query's response, as well as
|
||||
how to handle the result.
|
||||
|
||||
:meth:`~slixmpp.stanza.Iq.send()` returns an :class:`~asyncio.Future`
|
||||
object, which can be awaited on until a ``result`` is received.
|
||||
|
||||
These options are:
|
||||
|
||||
* ``block``: The default behaviour is that :meth:`~slixmpp.stanza.iq.Iq.send()`
|
||||
will block until a response is received and the response stanza will be the
|
||||
return value. Setting ``block`` to ``False`` will cause the call to return
|
||||
immediately. In which case, you will need to arrange some way to capture
|
||||
the response stanza if you need it.
|
||||
|
||||
* ``timeout``: When using the blocking behaviour, the call will eventually
|
||||
timeout with an error. The default timeout is 30 seconds, but this may
|
||||
be overidden two ways. To change the timeout globally, set:
|
||||
|
@ -79,28 +77,33 @@ These options are:
|
|||
|
||||
* ``callback``: When not using a blocking call, using the ``callback``
|
||||
argument is a simple way to register a handler that will execute
|
||||
whenever a response is finally received. Using this method, there
|
||||
is no timeout limit. In case you need to remove the callback, the
|
||||
name of the newly created callback is returned.
|
||||
whenever a response is finally received.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
cb_name = iq.send(callback=self.a_callback)
|
||||
iq.send(callback=self.a_callback)
|
||||
|
||||
# ... later if we need to cancel
|
||||
self.remove_handler(cb_name)
|
||||
* ``timeout_callback``: A callback to execute when the provided
|
||||
``timeout`` is reached before an answer is received.
|
||||
|
||||
Properly working with :class:`~slixmpp.stanza.iq.Iq` stanzas requires
|
||||
|
||||
.. note::
|
||||
|
||||
Both ``callback`` and ``timeout_callback`` can be effectively
|
||||
replaced using ``await``, and standard exception handling
|
||||
(see below), which provide a more linear and readable workflow.
|
||||
|
||||
Properly working with :class:`~slixmpp.stanza.Iq` stanzas requires
|
||||
handling the intended, normal flow, error responses, and timed out
|
||||
requests. To make this easier, two exceptions may be thrown by
|
||||
:meth:`~slixmpp.stanza.iq.Iq.send()`: :exc:`~slixmpp.exceptions.IqError`
|
||||
:meth:`~slixmpp.stanza.Iq.send()`: :exc:`~slixmpp.exceptions.IqError`
|
||||
and :exc:`~slixmpp.exceptions.IqTimeout`. These exceptions only
|
||||
apply to the default, blocking calls.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
try:
|
||||
resp = iq.send()
|
||||
resp = await iq.send()
|
||||
# ... do stuff with expected Iq result
|
||||
except IqError as e:
|
||||
err_resp = e.iq
|
||||
|
@ -116,7 +119,7 @@ exception:
|
|||
.. code-block:: python
|
||||
|
||||
try:
|
||||
resp = iq.send()
|
||||
resp = await iq.send()
|
||||
except XMPPError:
|
||||
# ... Don't care about the response
|
||||
pass
|
||||
|
@ -126,7 +129,7 @@ Advanced Use
|
|||
|
||||
Going beyond the basics provided by Slixmpp requires building at least a
|
||||
rudimentary Slixmpp plugin to create a :term:`stanza object` for
|
||||
interfacting with the :class:`~slixmpp.stanza.iq.Iq` payload.
|
||||
interfacting with the :class:`~slixmpp.stanza.Iq` payload.
|
||||
|
||||
.. seealso::
|
||||
|
||||
|
@ -135,13 +138,13 @@ interfacting with the :class:`~slixmpp.stanza.iq.Iq` payload.
|
|||
* :ref:`using-handlers-matchers`
|
||||
|
||||
|
||||
The typical way to respond to :class:`~slixmpp.stanza.iq.Iq` requests is
|
||||
The typical way to respond to :class:`~slixmpp.stanza.Iq` requests is
|
||||
to register stream handlers. As an example, suppose we create a stanza class
|
||||
named ``CustomXEP`` which uses the XML element ``<query xmlns="custom-xep" />``,
|
||||
and has a :attr:`~slixmpp.xmlstream.stanzabase.ElementBase.plugin_attrib` value
|
||||
of ``custom_xep``.
|
||||
|
||||
There are two types of incoming :class:`~slixmpp.stanza.iq.Iq` requests:
|
||||
There are two types of incoming :class:`~slixmpp.stanza.Iq` requests:
|
||||
``get`` and ``set``. You can register a handler that will accept both and then
|
||||
filter by type as needed, as so:
|
||||
|
||||
|
|
13
docs/howto/index.rst
Normal file
13
docs/howto/index.rst
Normal file
|
@ -0,0 +1,13 @@
|
|||
Tutorials, FAQs, and How To Guides
|
||||
----------------------------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
stanzas
|
||||
create_plugin
|
||||
features
|
||||
sasl
|
||||
handlersmatchers
|
||||
guide_xep_0030
|
||||
xmpp_tdg
|
109
docs/index.rst
109
docs/index.rst
|
@ -16,11 +16,6 @@ Slixmpp
|
|||
**Reporting bugs**
|
||||
You can report bugs at http://lab.louiz.org/poezio/slixmpp/issues.
|
||||
|
||||
.. note::
|
||||
slixmpp is a friendly fork of `SleekXMPP <https://github.com/fritzy/SleekXMPP>`_
|
||||
which goal is to use asyncio instead of threads to handle networking. See
|
||||
:ref:`differences`.
|
||||
|
||||
Slixmpp is an :ref:`MIT licensed <license>` XMPP library for Python 3.7+,
|
||||
|
||||
Slixmpp's design goals and philosphy are:
|
||||
|
@ -98,94 +93,27 @@ Here's your first Slixmpp Bot:
|
|||
xmpp.process()
|
||||
|
||||
|
||||
To read if you come from SleekXMPP
|
||||
----------------------------------
|
||||
Documentation Index
|
||||
-------------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
differences
|
||||
using_asyncio
|
||||
|
||||
|
||||
Getting Started (with Examples)
|
||||
-------------------------------
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
getting_started/echobot
|
||||
getting_started/sendlogout
|
||||
getting_started/component
|
||||
getting_started/presence
|
||||
getting_started/muc
|
||||
getting_started/proxy
|
||||
getting_started/scheduler
|
||||
getting_started/iq
|
||||
|
||||
|
||||
Tutorials, FAQs, and How To Guides
|
||||
----------------------------------
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
xeps
|
||||
xmpp_tdg
|
||||
howto/stanzas
|
||||
create_plugin
|
||||
features
|
||||
sasl
|
||||
handlersmatchers
|
||||
|
||||
Plugin Guides
|
||||
~~~~~~~~~~~~~
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
guide_xep_0030
|
||||
|
||||
Slixmpp Architecture and Design
|
||||
---------------------------------
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
|
||||
architecture
|
||||
plugin_arch
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
getting_started/index
|
||||
howto/index
|
||||
api/index
|
||||
api/stanza/index
|
||||
event_index
|
||||
api/clientxmpp
|
||||
api/componentxmpp
|
||||
api/basexmpp
|
||||
api/exceptions
|
||||
api/xmlstream/jid
|
||||
api/xmlstream/stanzabase
|
||||
api/xmlstream/handler
|
||||
api/xmlstream/matcher
|
||||
api/xmlstream/xmlstream
|
||||
api/xmlstream/tostring
|
||||
sleekxmpp
|
||||
architecture
|
||||
|
||||
Plugins
|
||||
~~~~~~~
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
api/plugins/index
|
||||
|
||||
Core Stanzas
|
||||
~~~~~~~~~~~~
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
api/stanza/rootstanza
|
||||
api/stanza/message
|
||||
api/stanza/presence
|
||||
api/stanza/iq
|
||||
|
||||
Additional Info
|
||||
---------------
|
||||
.. toctree::
|
||||
|
@ -200,9 +128,30 @@ Additional Info
|
|||
* :ref:`modindex`
|
||||
* :ref:`search`
|
||||
|
||||
|
||||
Slixmpp Credits
|
||||
---------------
|
||||
|
||||
**Maintainers:**
|
||||
- Florent Le Coz (`louiz@louiz.org <xmpp:louiz@louiz.org?message>`_),
|
||||
- Mathieu Pasquet (`mathieui@mathieui.net <xmpp:mathieui@mathieui.net?message>`_),
|
||||
- Emmanuel Gil Peyrot (`Link mauve <xmpp:linkmauve@linkmauve.fr?message>`_)
|
||||
- Maxime Buquet (`pep <xmpp:pep@bouah.net?message>`_)
|
||||
|
||||
**Contributors:**
|
||||
- Sam Whited (`Sam Whited <mailto:sam@samwhited.com>`_)
|
||||
- Dan Sully (`Dan Sully <mailto:daniel@electricalrain.com>`_)
|
||||
- Gasper Zejn (`Gasper Zejn <mailto:zejn@kiberpipa.org>`_)
|
||||
- Krzysztof Kotlenga (`Krzysztof Kotlenga <mailto:pocek@users.sf.net>`_)
|
||||
- Tsukasa Hiiragi (`Tsukasa Hiiragi <mailto:bakalolka@gmail.com>`_)
|
||||
|
||||
SleekXMPP Credits
|
||||
-----------------
|
||||
|
||||
Slixmpp is a friendly fork of `SleekXMPP <https://github.com/fritzy/SleekXMPP>`_
|
||||
which goal is to use asyncio instead of threads to handle networking. See
|
||||
:ref:`differences`. We are crediting SleekXMPP Authors here.
|
||||
|
||||
.. note::
|
||||
Those people made SleekXMPP, so you should not bother them if
|
||||
you have an issue with slixmpp. But it’s still fair to credit
|
||||
|
|
|
@ -1,2 +0,0 @@
|
|||
Plugin Architecture
|
||||
===================
|
8
docs/sleekxmpp.rst
Normal file
8
docs/sleekxmpp.rst
Normal file
|
@ -0,0 +1,8 @@
|
|||
Coming from SleekXMPP
|
||||
---------------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
differences
|
||||
using_asyncio
|
Loading…
Reference in a new issue