summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLink Mauve <linkmauve@linkmauve.fr>2021-02-03 23:23:38 +0100
committerLink Mauve <linkmauve@linkmauve.fr>2021-02-03 23:23:38 +0100
commitc486c0e8219da4cdea6988b2948ffc93cb381bec (patch)
treecc4937fd4239c9bdfd2d3634d0afa4d42ef6e3fd
parentd8dbfaa37e62b230650c14151658be448137ea0e (diff)
parentf8c39bae60d7b9125ffc5d2c90ce59147fb46785 (diff)
downloadslixmpp-c486c0e8219da4cdea6988b2948ffc93cb381bec.tar.gz
slixmpp-c486c0e8219da4cdea6988b2948ffc93cb381bec.tar.bz2
slixmpp-c486c0e8219da4cdea6988b2948ffc93cb381bec.tar.xz
slixmpp-c486c0e8219da4cdea6988b2948ffc93cb381bec.zip
Merge branch 'documentation-update' into 'master'
Documentation update See merge request poezio/slixmpp!116
-rw-r--r--docs/api/index.rst16
-rw-r--r--docs/api/stanza/index.rst11
-rw-r--r--docs/getting_started/index.rst15
-rw-r--r--docs/getting_started/iq.rst55
-rw-r--r--docs/howto/create_plugin.rst (renamed from docs/create_plugin.rst)0
-rw-r--r--docs/howto/features.rst (renamed from docs/features.rst)0
-rw-r--r--docs/howto/guide_xep_0030.rst (renamed from docs/guide_xep_0030.rst)0
-rw-r--r--docs/howto/handlersmatchers.rst (renamed from docs/handlersmatchers.rst)0
-rw-r--r--docs/howto/index.rst13
-rw-r--r--docs/howto/sasl.rst (renamed from docs/sasl.rst)0
-rw-r--r--docs/howto/xeps.rst (renamed from docs/xeps.rst)0
-rw-r--r--docs/howto/xmpp_tdg.rst (renamed from docs/xmpp_tdg.rst)0
-rw-r--r--docs/index.rst109
-rw-r--r--docs/plugin_arch.rst2
-rw-r--r--docs/sleekxmpp.rst8
15 files changed, 121 insertions, 108 deletions
diff --git a/docs/api/index.rst b/docs/api/index.rst
new file mode 100644
index 00000000..aefa0f56
--- /dev/null
+++ b/docs/api/index.rst
@@ -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
diff --git a/docs/api/stanza/index.rst b/docs/api/stanza/index.rst
new file mode 100644
index 00000000..2af0d630
--- /dev/null
+++ b/docs/api/stanza/index.rst
@@ -0,0 +1,11 @@
+
+Core Stanzas
+------------
+
+.. toctree::
+ :maxdepth: 2
+
+ rootstanza
+ message
+ presence
+ iq
diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst
new file mode 100644
index 00000000..97c34a22
--- /dev/null
+++ b/docs/getting_started/index.rst
@@ -0,0 +1,15 @@
+Getting Started (with examples)
+-------------------------------
+
+.. toctree::
+ :maxdepth: 3
+
+ echobot
+ sendlogout
+ component
+ presence
+ muc
+ proxy
+ scheduler
+ iq
+
diff --git a/docs/getting_started/iq.rst b/docs/getting_started/iq.rst
index be15e170..aac75712 100644
--- a/docs/getting_started/iq.rst
+++ b/docs/getting_started/iq.rst
@@ -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,18 +50,16 @@ 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.
-These options are:
+:meth:`~slixmpp.stanza.Iq.send()` returns an :class:`~asyncio.Future`
+object, which can be awaited on until a ``result`` is received.
-* ``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.
+These options are:
* ``timeout``: When using the blocking behaviour, the call will eventually
timeout with an error. The default timeout is 30 seconds, but this may
@@ -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)
+
+* ``timeout_callback``: A callback to execute when the provided
+ ``timeout`` is reached before an answer is received.
+
+
+.. note::
- # ... later if we need to cancel
- self.remove_handler(cb_name)
+ 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.Iq` stanzas requires
+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:
diff --git a/docs/create_plugin.rst b/docs/howto/create_plugin.rst
index 437374c7..437374c7 100644
--- a/docs/create_plugin.rst
+++ b/docs/howto/create_plugin.rst
diff --git a/docs/features.rst b/docs/howto/features.rst
index 4d93d5c3..4d93d5c3 100644
--- a/docs/features.rst
+++ b/docs/howto/features.rst
diff --git a/docs/guide_xep_0030.rst b/docs/howto/guide_xep_0030.rst
index a3af4857..a3af4857 100644
--- a/docs/guide_xep_0030.rst
+++ b/docs/howto/guide_xep_0030.rst
diff --git a/docs/handlersmatchers.rst b/docs/howto/handlersmatchers.rst
index 628c4142..628c4142 100644
--- a/docs/handlersmatchers.rst
+++ b/docs/howto/handlersmatchers.rst
diff --git a/docs/howto/index.rst b/docs/howto/index.rst
new file mode 100644
index 00000000..b05dc499
--- /dev/null
+++ b/docs/howto/index.rst
@@ -0,0 +1,13 @@
+Tutorials, FAQs, and How To Guides
+----------------------------------
+
+.. toctree::
+ :maxdepth: 2
+
+ stanzas
+ create_plugin
+ features
+ sasl
+ handlersmatchers
+ guide_xep_0030
+ xmpp_tdg
diff --git a/docs/sasl.rst b/docs/howto/sasl.rst
index 46c45c2a..46c45c2a 100644
--- a/docs/sasl.rst
+++ b/docs/howto/sasl.rst
diff --git a/docs/xeps.rst b/docs/howto/xeps.rst
index c5b4592d..c5b4592d 100644
--- a/docs/xeps.rst
+++ b/docs/howto/xeps.rst
diff --git a/docs/xmpp_tdg.rst b/docs/howto/xmpp_tdg.rst
index 53194e13..53194e13 100644
--- a/docs/xmpp_tdg.rst
+++ b/docs/howto/xmpp_tdg.rst
diff --git a/docs/index.rst b/docs/index.rst
index a01109cd..d088e015 100644
--- a/docs/index.rst
+++ b/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
-----------------------------------
-
-.. toctree::
- :maxdepth: 1
-
- differences
- using_asyncio
-
+Documentation Index
+-------------------
-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
diff --git a/docs/plugin_arch.rst b/docs/plugin_arch.rst
deleted file mode 100644
index 0141b793..00000000
--- a/docs/plugin_arch.rst
+++ /dev/null
@@ -1,2 +0,0 @@
-Plugin Architecture
-===================
diff --git a/docs/sleekxmpp.rst b/docs/sleekxmpp.rst
new file mode 100644
index 00000000..12f02377
--- /dev/null
+++ b/docs/sleekxmpp.rst
@@ -0,0 +1,8 @@
+Coming from SleekXMPP
+---------------------
+
+.. toctree::
+ :maxdepth: 2
+
+ differences
+ using_asyncio