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 ```` elements. For clients, just sending the empty ```` 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 ```` 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 ````, 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 similarity index 100% rename from docs/create_plugin.rst rename to docs/howto/create_plugin.rst diff --git a/docs/features.rst b/docs/howto/features.rst similarity index 100% rename from docs/features.rst rename to docs/howto/features.rst diff --git a/docs/guide_xep_0030.rst b/docs/howto/guide_xep_0030.rst similarity index 100% rename from docs/guide_xep_0030.rst rename to docs/howto/guide_xep_0030.rst diff --git a/docs/handlersmatchers.rst b/docs/howto/handlersmatchers.rst similarity index 100% rename from docs/handlersmatchers.rst rename to 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 similarity index 100% rename from docs/sasl.rst rename to docs/howto/sasl.rst diff --git a/docs/xeps.rst b/docs/howto/xeps.rst similarity index 100% rename from docs/xeps.rst rename to docs/howto/xeps.rst diff --git a/docs/xmpp_tdg.rst b/docs/howto/xmpp_tdg.rst similarity index 100% rename from docs/xmpp_tdg.rst rename to 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 `_ - which goal is to use asyncio instead of threads to handle networking. See - :ref:`differences`. - Slixmpp is an :ref:`MIT licensed ` 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 `_), + - Mathieu Pasquet (`mathieui@mathieui.net `_), + - Emmanuel Gil Peyrot (`Link mauve `_) + - Maxime Buquet (`pep `_) + +**Contributors:** + - Sam Whited (`Sam Whited `_) + - Dan Sully (`Dan Sully `_) + - Gasper Zejn (`Gasper Zejn `_) + - Krzysztof Kotlenga (`Krzysztof Kotlenga `_) + - Tsukasa Hiiragi (`Tsukasa Hiiragi `_) + SleekXMPP Credits ----------------- +Slixmpp is a friendly fork of `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