diff options
| -rw-r--r-- | docs/api/index.rst | 16 | ||||
| -rw-r--r-- | docs/api/stanza/index.rst | 11 | ||||
| -rw-r--r-- | docs/getting_started/index.rst | 15 | ||||
| -rw-r--r-- | docs/getting_started/iq.rst | 55 | ||||
| -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.rst | 13 | ||||
| -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.rst | 109 | ||||
| -rw-r--r-- | docs/plugin_arch.rst | 2 | ||||
| -rw-r--r-- | docs/sleekxmpp.rst | 8 |
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 |