From c66a4d4097a249efc029b761d6150378a54bf702 Mon Sep 17 00:00:00 2001 From: mathieui Date: Tue, 24 Feb 2015 18:58:40 +0100 Subject: Update the documentation and examples - update most of the examples with slixmpp - change the help channels pointed out in the doc - add a page listing differences from slixmpp and how to use asyncio nicely with slixmpp - fix some in-code rst documentation --- docs/getting_started/component.rst | 14 +++------- docs/getting_started/echobot.rst | 53 +++++-------------------------------- docs/getting_started/muc.rst | 14 +++------- docs/getting_started/proxy.rst | 6 ++--- docs/getting_started/sendlogout.rst | 6 ++--- 5 files changed, 16 insertions(+), 77 deletions(-) (limited to 'docs/getting_started') diff --git a/docs/getting_started/component.rst b/docs/getting_started/component.rst index 484a8e84..34aeda26 100644 --- a/docs/getting_started/component.rst +++ b/docs/getting_started/component.rst @@ -7,19 +7,11 @@ Create and Run a Server Component .. note:: If you have any issues working through this quickstart guide - or the other tutorials here, please either send a message to the - `mailing list `_ - or join the chat room at `sleek@conference.jabber.org - `_. + join the chat room at `slixmpp@muc.poez.io + `_. If you have not yet installed Slixmpp, do so now by either checking out a version -from `Github `_, or installing it using ``pip`` -or ``easy_install``. - -.. code-block:: sh - - pip install slixmpp # Or: easy_install slixmpp - +with `Git `_. Many XMPP applications eventually graduate to requiring to run as a server component in order to meet scalability requirements. To demonstrate how to diff --git a/docs/getting_started/echobot.rst b/docs/getting_started/echobot.rst index 013d6816..bb40a0b5 100644 --- a/docs/getting_started/echobot.rst +++ b/docs/getting_started/echobot.rst @@ -7,19 +7,11 @@ Slixmpp Quickstart - Echo Bot .. note:: If you have any issues working through this quickstart guide - or the other tutorials here, please either send a message to the - `mailing list `_ - or join the chat room at `sleek@conference.jabber.org - `_. + join the chat room at `slixmpp@muc.poez.io + `_. If you have not yet installed Slixmpp, do so now by either checking out a version -from `Github `_, or installing it using ``pip`` -or ``easy_install``. - -.. code-block:: sh - - pip install slixmpp # Or: easy_install slixmpp - +with `Git `_. As a basic starting project, we will create an echo bot which will reply to any messages sent to it. We will also go through adding some basic command line configuration @@ -44,6 +36,7 @@ To get started, here is a brief outline of the structure that the final project # -*- coding: utf-8 -*- import sys + import asyncio import logging import getpass from optparse import OptionParser @@ -59,24 +52,6 @@ To get started, here is a brief outline of the structure that the final project '''Finally, we connect the bot and start listening for messages''' -Default Encoding ----------------- -XMPP requires support for UTF-8 and so Slixmpp must use UTF-8 as well. In -Python3 this is simple because Unicode is the default string type. For Python2.6+ -the situation is not as easy because standard strings are simply byte arrays and -use ASCII. We can get Python to use UTF-8 as the default encoding by including: - -.. code-block:: python - - if sys.version_info < (3, 0): - from slixmpp.util.misc_ops import setdefaultencoding - setdefaultencoding('utf8') - -.. warning:: - - Until we are able to ensure that Slixmpp will always use Unicode in Python2.6+, this - may cause issues embedding Slixmpp into other applications which assume ASCII encoding. - Creating the EchoBot Class -------------------------- @@ -313,9 +288,9 @@ the ``EchoBot.__init__`` method instead. xmpp.ssl_version = ssl.PROTOCOL_SSLv3 Now we're ready to connect and begin echoing messages. If you have the package -``dnspython`` installed, then the :meth:`slixmpp.clientxmpp.ClientXMPP` method +``aiodns`` installed, then the :meth:`slixmpp.clientxmpp.ClientXMPP` method will perform a DNS query to find the appropriate server to connect to for the -given JID. If you do not have ``dnspython``, then Slixmpp will attempt to +given JID. If you do not have ``aiodns``, then Slixmpp will attempt to connect to the hostname used by the JID, unless an address tuple is supplied to :meth:`slixmpp.clientxmpp.ClientXMPP`. @@ -330,22 +305,6 @@ to :meth:`slixmpp.clientxmpp.ClientXMPP`. else: print('Unable to connect') -.. note:: - - For Google Talk users withouth ``dnspython`` installed, the above code - should look like: - - .. code-block:: python - - if __name__ == '__main__': - - # .. option parsing & echo bot configuration - - if xmpp.connect(('talk.google.com', 5222)): - xmpp.process(block=True) - else: - print('Unable to connect') - To begin responding to messages, you'll see we called :meth:`slixmpp.basexmpp.BaseXMPP.process` which will start the event handling, send queue, and XML reader threads. It will also call the :meth:`slixmpp.plugins.base.BasePlugin.post_init` method on all registered plugins. By diff --git a/docs/getting_started/muc.rst b/docs/getting_started/muc.rst index 8e41790f..4dd1ff93 100644 --- a/docs/getting_started/muc.rst +++ b/docs/getting_started/muc.rst @@ -7,19 +7,11 @@ Mulit-User Chat (MUC) Bot .. note:: If you have any issues working through this quickstart guide - or the other tutorials here, please either send a message to the - `mailing list `_ - or join the chat room at `sleek@conference.jabber.org - `_. + join the chat room at `slixmpp@muc.poez.io + `_. If you have not yet installed Slixmpp, do so now by either checking out a version -from `Github `_, or installing it using ``pip`` -or ``easy_install``. - -.. code-block:: sh - - pip install slixmpp # Or: easy_install slixmpp - +from `Git `_. Now that you've got the basic gist of using Slixmpp by following the echobot example (:ref:`echobot`), we can use one of the bundled plugins diff --git a/docs/getting_started/proxy.rst b/docs/getting_started/proxy.rst index e45b2b3a..22439d4e 100644 --- a/docs/getting_started/proxy.rst +++ b/docs/getting_started/proxy.rst @@ -7,10 +7,8 @@ Enable HTTP Proxy Support .. note:: If you have any issues working through this quickstart guide - or the other tutorials here, please either send a message to the - `mailing list `_ - or join the chat room at `sleek@conference.jabber.org - `_. + join the chat room at `slixmpp@muc.poez.io + `_. In some instances, you may wish to route XMPP traffic through an HTTP proxy, probably to get around restrictive firewalls. diff --git a/docs/getting_started/sendlogout.rst b/docs/getting_started/sendlogout.rst index 7669e340..d5882c42 100644 --- a/docs/getting_started/sendlogout.rst +++ b/docs/getting_started/sendlogout.rst @@ -4,10 +4,8 @@ Sign in, Send a Message, and Disconnect .. note:: If you have any issues working through this quickstart guide - or the other tutorials here, please either send a message to the - `mailing list `_ - or join the chat room at `sleek@conference.jabber.org - `_. + join the chat room at `slixmpp@muc.poez.io + `_. A common use case for Slixmpp is to send one-off messages from time to time. For example, one use case could be sending out a notice when -- cgit v1.2.3