pep/slixmpp
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge branch 'documentation-update' into 'master'

Browse source 
Documentation update

See merge request poezio/slixmpp!116
This commit is contained in:
Link Mauve 2021-02-03 23:23:38 +01:00
commit c486c0e821
15 changed files with 121 additions and 108 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

16
docs/api/index.rst Normal file
View 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
View file

@ -0,0 +1,11 @@
Core Stanzas
------------
.. toctree::
:maxdepth: 2
rootstanza
message
presence
iq

15
docs/getting_started/index.rst Normal file
View file

@ -0,0 +1,15 @@
Getting Started (with examples)
-------------------------------
.. toctree::
:maxdepth: 3
echobot
sendlogout
component
presence
muc
proxy
scheduler
iq

55
docs/getting_started/iq.rst
View file

@ -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:

0
docs/create_plugin.rst → docs/howto/create_plugin.rst
View file

0
docs/features.rst → docs/howto/features.rst
View file

0
docs/guide_xep_0030.rst → docs/howto/guide_xep_0030.rst
View file

0
docs/handlersmatchers.rst → docs/howto/handlersmatchers.rst
View file

13
docs/howto/index.rst Normal file
View 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

0
docs/sasl.rst → docs/howto/sasl.rst
View file

0
docs/xeps.rst → docs/howto/xeps.rst
View file

0
docs/xmpp_tdg.rst → docs/howto/xmpp_tdg.rst
View file

109
docs/index.rst
View file

@ -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

2
docs/plugin_arch.rst
View file

@ -1,2 +0,0 @@
Plugin Architecture
===================

8
docs/sleekxmpp.rst Normal file
View file

@ -0,0 +1,8 @@
Coming from SleekXMPP
---------------------
.. toctree::
:maxdepth: 2
differences
using_asyncio