From 01061a0355b05c8452b1ef8ca998cd2c51ab4c9e Mon Sep 17 00:00:00 2001
From: Lance Stout <lancestout@gmail.com>
Date: Sat, 13 Aug 2011 20:58:53 -0700
Subject: More documentation!
Finished the echo bot quickstart.
Added placeholders for other guides we need.
---
LICENSE | 4 +-
docs/getting_started/component.rst | 2 +
docs/getting_started/echobot.rst | 512 ++++++++++++++++++++++++++++++++++++
docs/getting_started/iq.rst | 2 +
docs/getting_started/muc.rst | 2 +
docs/getting_started/presence.rst | 2 +
docs/getting_started/proxy.rst | 2 +
docs/getting_started/scheduler.rst | 2 +
docs/getting_started/sendlogout.rst | 5 +
docs/handlersmatchers.rst | 2 +
docs/index.rst | 35 ++-
docs/quickstart.rst | 300 ---------------------
docs/sasl.rst | 2 +
docs/xeps.rst | 2 +
examples/echo_client.py | 3 +-
15 files changed, 567 insertions(+), 310 deletions(-)
create mode 100644 docs/getting_started/component.rst
create mode 100644 docs/getting_started/echobot.rst
create mode 100644 docs/getting_started/iq.rst
create mode 100644 docs/getting_started/muc.rst
create mode 100644 docs/getting_started/presence.rst
create mode 100644 docs/getting_started/proxy.rst
create mode 100644 docs/getting_started/scheduler.rst
create mode 100644 docs/getting_started/sendlogout.rst
create mode 100644 docs/handlersmatchers.rst
delete mode 100644 docs/quickstart.rst
create mode 100644 docs/sasl.rst
create mode 100644 docs/xeps.rst
diff --git a/LICENSE b/LICENSE
index e66eb513..612dd1d7 100644
--- a/LICENSE
+++ b/LICENSE
@@ -21,8 +21,8 @@ THE SOFTWARE.
-Licenses of Bundled Third Pary Code
------------------------------------
+Licenses of Bundled Third Party Code
+------------------------------------
dateutil - Extensions to the standard python 2.3+ datetime module.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/getting_started/component.rst b/docs/getting_started/component.rst
new file mode 100644
index 00000000..ca9ec066
--- /dev/null
+++ b/docs/getting_started/component.rst
@@ -0,0 +1,2 @@
+Create and Run a Server Component
+=================================
diff --git a/docs/getting_started/echobot.rst b/docs/getting_started/echobot.rst
new file mode 100644
index 00000000..9defca6b
--- /dev/null
+++ b/docs/getting_started/echobot.rst
@@ -0,0 +1,512 @@
+===============================
+SleekXMPP 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 <http://groups.google.com/group/sleekxmpp-discussion>`_
+ or join the chat room at `sleek@conference.jabber.org
+ <xmpp:sleek@conference.jabber.org?join>`_.
+
+If you have not yet installed SleekXMPP, do so now by either checking out a version
+from `Github <http://github.com/fritzy/SleekXMPP>`_, or installing it using ``pip``
+or ``easy_install``.
+
+.. code-block:: sh
+
+ pip install sleekxmpp # Or: easy_install sleekxmpp
+
+
+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
+for enabling or disabling debug log outputs and setting the username and password
+for the bot.
+
+For the command line options processing, we will use the built-in ``optparse``
+module and the ``getpass`` module for reading in passwords.
+
+TL;DR Just Give Me the Code
+---------------------------
+As you wish: :ref:`the completed example <echobot_complete>`.
+
+Overview
+--------
+
+To get started, here is a brief outline of the structure that the final project will have:
+
+.. code-block:: python
+
+ #!/usr/bin/env python
+ # -*- coding: utf-8 -*-
+
+ import sys
+ import logging
+ import getpass
+ from optparse import OptionParser
+
+ import sleekxmpp
+
+ '''Here we will create out echo bot class'''
+
+ if __name__ == '__main__':
+ '''Here we will configure and read command line options'''
+
+ '''Here we will instantiate our echo bot'''
+
+ '''Finally, we connect the bot and start listening for messages'''
+
+Default Encoding
+----------------
+XMPP requires support for UTF-8 and so SleekXMPP 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):
+ reload(sys)
+ sys.setdefaultencoding('utf8')
+
+.. warning::
+
+ Until we are able to ensure that SleekXMPP will always use Unicode in Python2.6+, this
+ may cause issues embedding SleekXMPP into other applications which assume ASCII encoding.
+
+Creating the EchoBot Class
+--------------------------
+
+There are three main types of entities within XMPP — servers, components, and
+clients. Since our echo bot will only be responding to a few people, and won't need
+to remember thousands of users, we will use a client connection. A client connection
+is the same type that you use with your standard IM client such as Pidgin or Psi.
+
+SleekXMPP comes with a :class:`ClientXMPP <sleekxmpp.clientxmpp.ClientXMPP>` class
+which we can extend to add our message echoing feature. :class:`ClientXMPP <sleekxmpp.clientxmpp.ClientXMPP>`
+requires the parameters ``jid`` and ``password``, so we will let our ``EchoBot`` class accept those
+as well.
+
+.. code-block:: python
+
+ class EchoBot(sleekxmpp.ClientXMPP):
+
+ def __init__(self, jid, password):
+ super(EchoBot, self).__init__(jid, password)
+
+Handling Session Start
+~~~~~~~~~~~~~~~~~~~~~~
+The XMPP spec requires clients to broadcast its presence and retrieve its roster (buddy list) once
+it connects and establishes a session with the XMPP server. Until these two tasks are completed,
+some servers may not deliver or send messages or presence notifications to the client. So we now
+need to be sure that we retrieve our roster and send an initial presence once the session has
+started. To do that, we will register an event handler for the :term:`session_start` event.
+
+.. code-block:: python
+
+ def __init__(self, jid, password):
+ super(EchoBot, self).__init__(jid, password)
+
+ self.add_event_handler('session_start', self.start)
+
+
+Since we want the method ``self.start`` to execute when the :term:`session_start` event is triggered,
+we also need to define the ``self.start`` handler.
+
+.. code-block:: python
+
+ def start(self, event):
+ self.send_presence()
+ self.get_roster()
+
+.. warning::
+
+ Not sending an initial presence and retrieving the roster when using a client instance can
+ prevent your program from receiving presence notifications or messages depending on the
+ XMPP server you have chosen.
+
+Our event handler, like every event handler, accepts a single parameter which typically is the stanza
+that was received that caused the event. In this case, ``event`` will just be an empty dictionary since
+there is no associated data.
+
+Our first task of sending an initial presence is done using :meth:`send_presence <sleekxmpp.basexmpp.BaseXMPP.send_presence>`.
+Calling :meth:`send_presence <sleekxmpp.basexmpp.BaseXMPP.send_presence>` without any arguments will send the simplest
+stanza allowed in XMPP:
+
+.. code-block:: xml
+
+ <presence />
+
+
+The second requirement is fulfilled using :meth:`get_roster <sleekxmpp.clientxmpp.ClientXMPP.get_roster>`, which
+will send an IQ stanza requesting the roster to the server and then wait for the response. You may be wondering
+what :meth:`get_roster <sleekxmpp.clientxmpp.ClientXMPP.get_roster>` returns since we are not saving any return
+value. The roster data is saved by an internal handler to ``self.roster``, and in the case of a :class:`ClientXMPP
+<sleekxmpp.clientxmpp.ClientXMPP>` instance to ``self.client_roster``. (The difference between ``self.roster`` and
+``self.client_roster`` is that ``self.roster`` supports storing roster information for multiple JIDs, which is useful
+for components, whereas ``self.client_roster`` stores roster data for just the client's JID.)
+
+It is possible for a timeout to occur while waiting for the server to respond, which can happen if the
+network is excessively slow or the server is no longer responding. In that case, an :class:`IQTimeout
+<sleekxmpp.exceptions.IQTimeout>` is raised. Similarly, an :class:`IQError <sleekxmpp.exceptions.IQError>` exception can
+be raised if the request contained bad data or requested the roster for the wrong user. In either case, you can wrap the
+``get_roster()`` call in a ``try``/``except`` block to retry the roster retrieval process.
+
+The XMPP stanzas from the roster retrieval process could look like this:
+
+.. code-block:: xml
+
+ <iq type="get">
+ <query xmlns="jabber:iq:roster" />
+ </iq>
+
+ <iq type="result" to="echobot@example.com" from="example.com">
+ <query xmlns="jabber:iq:roster">
+ <item jid="friend@example.com" subscription="both" />
+ </query>
+ </iq>
+
+Responding to Messages
+~~~~~~~~~~~~~~~~~~~~~~
+Now that an ``EchoBot`` instance handles :term:`session_start`, we can begin receiving and
+responding to messages. Now we can register a handler for the :term:`message` event that is raised
+whenever a messsage is received.
+
+.. code-block:: python
+
+ def __init__(self, jid, password):
+ super(EchoBot, self).__init__(jid, password)
+
+ self.add_event_handler('session_start', self.start)
+ self.add_event_handler('message', self.message)
+
+
+The :term:`message` event is fired whenever a ``<message />`` stanza is received, including for
+group chat messages, errors, etc. Properly responding to messages thus requires checking the
+``'type'`` interface of the message :term:`stanza object`. For responding to only messages
+addressed to our bot (and not from a chat room), we check that the type is either ``normal``
+or ``chat``. (Other potential types are ``error``, ``headline``, and ``groupchat``.)
+
+.. code-block:: python
+
+ def message(self, msg):
+ if msg['type'] in ('normal', 'chat'):
+ msg.reply("Thanks for sending:\n%s" % msg['body']).send()
+
+Let's take a closer look at the ``.reply()`` method used above. For message stanzas,
+``.reply()`` accepts the parameter ``body`` (also as the first positional argument),
+which is then used as the value of the ``<body />`` element of the message.
+Setting the appropriate ``to`` JID is also handled by ``.reply()``.
+
+Another way to have sent the reply message would be to use :meth:`send_message <sleekxmpp.basexmpp.BaseXMPP.send_message>`,
+which is a convenience method for generating and sending a message based on the values passed to it. If we were to use
+this method, the above code would look as so:
+
+.. code-block:: python
+
+ def message(self, msg):
+ if msg['type'] in ('normal', 'chat'):
+ self.send_message(mto=msg['from'],
+ mbody='Thanks for sending:\n%s' % msg['body'])
+
+Whichever method you choose to use, the results in action will look like this:
+
+.. code-block:: xml
+
+ <message to="echobot@example.com" from="someuser@example.net" type="chat">
+ <body>Hej!</body>
+ </message>
+
+ <message to="someuser@example.net" type="chat">
+ <body>Thanks for sending:
+ Hej!</body>
+ </message>
+
+.. note::
+ XMPP does not require stanzas sent by a client to include a ``from`` attribute, and
+ leaves that responsibility to the XMPP server. However, if a sent stanza does
+ include a ``from`` attribute, it must match the full JID of the client or some
+ servers will reject it. SleekXMPP thus leaves out the ``from`` attribute when replying
+ using a client connection.
+
+Command Line Arguments and Logging
+----------------------------------
+
+While this isn't part of SleekXMPP itself, we do want our echo bot program to be able
+to accept a JID and password from the command line instead of hard coding them. We will
+use the ``optparse`` module for this, though there are several alternative methods, including
+the newer ``argparse`` module.
+
+We want to accept three parameters: the JID for the echo bot, its password, and a flag for
+displaying the debugging logs. We also want these to be optional parameters, since passing
+a password directly through the command line can be a security risk.
+
+.. code-block:: python
+
+ if __name__ == '__main__':
+ optp = OptionParser()
+
+ optp.add_option('-d', '--debug', help='set logging to DEBUG',
+ action='store_const', dest='loglevel',
+ const=logging.DEBUG, default=logging.INFO)
+ optp.add_option("-j", "--jid", dest="jid",
+ help="JID to use")
+ optp.add_option("-p", "--password", dest="password",
+ help="password to use")
+
+ opts, args = optp.parse_args()
+
+ if opts.jid is None:
+ opts.jid = raw_input("Username: ")
+ if opts.password is None:
+ opts.password = getpass.getpass("Password: ")
+
+Since we included a flag for enabling debugging logs, we need to configure the
+``logging`` module to behave accordingly.
+
+.. code-block:: python
+
+ if __name__ == '__main__':
+
+ # .. option parsing from above ..
+
+ logging.basicConfig(level=opts.loglevel,
+ format='%(levelname)-8s %(message)s')
+
+
+Connecting to the Server and Processing
+---------------------------------------
+There are three steps remaining until our echo bot is complete:
+ 1. We need to instantiate the bot.
+ 2. The bot needs to connect to an XMPP server.
+ 3. We have to instruct the bot to start running and processing messages.
+
+Creating the bot is straightforward, but we can also perform some configuration
+at this stage. For example, let's say we want our bot to support `service discovery
+<http://xmpp.org/extensions/xep-0030.html>`_ and `pings <http://xmpp.org/extensions/xep-0199.html>`_:
+
+.. code-block:: python
+
+ if __name__ == '__main__':
+
+ # .. option parsing and logging steps from above
+
+ xmpp = EchoBot(opts.jid, opts.password)
+ xmpp.register_plugin('xep_0030') # Service Discovery
+ xmpp.register_plugin('xep_0199') # Ping
+
+If the ``EchoBot`` class had a hard dependency on a plugin, we could register that plugin in
+the ``EchoBot.__init__`` method instead.
+
+.. note::
+
+ If you are using the OpenFire server, you will need to include an additional
+ configuration step. OpenFire supports a different version of SSL than what
+ most servers and SleekXMPP support.
+
+ .. code-block:: python
+
+ import ssl
+ 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:`sleekxmpp.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 SleekXMPP will attempt to
+connect to the hostname used by the JID, unless an address tuple is supplied
+to :meth:`sleekxmpp.clientxmpp.ClientXMPP`.
+
+.. code-block:: python
+
+ if __name__ == '__main__':
+
+ # .. option parsing & echo bot configuration
+
+ if xmpp.connect():
+ xmpp.process(block=True)
+ 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:`sleekxmpp.basexmpp.BaseXMPP.process`
+which will start the event handling, send queue, and XML reader threads. It will also call
+the :meth:`sleekxmpp.plugins.base.base_plugin.post_init` method on all registered plugins. By
+passing ``block=True`` to :meth:`sleekxmpp.basexmpp.BaseXMPP.process` we are running the
+main processing loop in the main thread of execution. The :meth:`sleekxmpp.basexmpp.BaseXMPP.process`
+call will not return until after SleekXMPP disconnects. If you need to run the client in the background
+for another program, use ``block=False`` to spawn the processing loop in its own thread.
+
+.. note::
+
+ Before 1.0, controlling the blocking behaviour of :meth:`sleekxmpp.basexmpp.BaseXMPP.process` was
+ done via the ``threaded`` argument. This arrangement was a source of confusion because some users
+ interpreted that as controlling whether or not SleekXMPP used threads at all, instead of how
+ the processing loop itself was spawned.
+
+ The statements ``xmpp.process(threaded=False)`` and ``xmpp.process(block=True)`` are equivalent.
+
+
+.. _echobot_complete:
+
+The Final Product
+-----------------
+
+Here then is what the final result should look like after working through the guide above. The code
+can also be found in the SleekXMPP `examples directory <http://github.com/fritzy/SleekXMPP/tree/master/examples>`_.
+
+.. compound::
+
+ You can run the code using:
+
+ .. code-block:: sh
+
+ python echobot.py -d -j echobot@example.com
+
+ which will prompt for the password and then begin echoing messages. To test, open
+ your regular IM client and start a chat with the echo bot. Messages you send to it should
+ be mirrored back to you. Be careful if you are using the same JID for the echo bot that
+ you also have logged in with another IM client. Messages could be routed to your IM client instead
+ of the bot.
+
+.. include:: ../../examples/echo_client.py
+ :literal:
+
+
+..
+.. #!/usr/bin/env python
+.. # -*- coding: utf-8 -*-
+.. import sys
+.. import logging
+.. import time
+.. import getpass
+.. from optparse import OptionParser
+..
+.. import sleekxmpp
+..
+..
+.. class EchoBot(sleekxmpp.ClientXMPP):
+..
+.. """
+.. A simple SleekXMPP bot that will echo messages it
+.. receives, along with a short thank you message.
+.. """
+..
+.. def __init__(self, jid, password):
+.. sleekxmpp.ClientXMPP.__init__(self, jid, password)
+..
+.. # The session_start event will be triggered when
+.. # the bot establishes its connection with the server
+.. # and the XML streams are ready for use. We want to
+.. # listen for this event so that we we can intialize
+.. # our roster.
+.. self.add_event_handler("session_start", self.start)
+..
+.. # The message event is triggered whenever a message
+.. # stanza is received. Be aware that that includes
+.. # MUC messages and error messages.
+.. self.add_event_handler("message", self.message)
+..
+.. def start(self, event):
+.. """
+.. Process the session_start event.
+..
+.. Typical actions for the session_start event are
+.. requesting the roster and broadcasting an intial
+.. presence stanza.
+..
+.. Arguments:
+.. event -- An empty dictionary. The session_start
+.. event does not provide any additional
+.. data.
+.. """
+.. self.send_presence()
+.. self.get_roster()
+..
+.. def message(self, msg):
+.. """
+.. Process incoming message stanzas. Be aware that this also
+.. includes MUC messages and error messages. It is usually
+.. a good idea to check the messages's type before processing
+.. or sending replies.
+..
+.. Arguments:
+.. msg -- The received message stanza. See the documentation
+.. for stanza objects and the Message stanza to see
+.. how it may be used.
+.. """
+.. if msg['type'] in ('normal', 'chat'):
+.. msg.reply("Thanks for sending\n%(body)s" % msg).send()
+..
+..
+.. if __name__ == '__main__':
+.. # Setup the command line arguments.
+.. optp = OptionParser()
+..
+.. # Output verbosity options.
+.. optp.add_option('-q', '--quiet', help='set logging to ERROR',
+.. action='store_const', dest='loglevel',
+.. const=logging.ERROR, default=logging.INFO)
+.. optp.add_option('-d', '--debug', help='set logging to DEBUG',
+.. action='store_const', dest='loglevel',
+.. const=logging.DEBUG, default=logging.INFO)
+.. optp.add_option('-v', '--verbose', help='set logging to COMM',
+.. action='store_const', dest='loglevel',
+.. const=5, default=logging.INFO)
+..
+.. # JID and password options.
+.. optp.add_option("-j", "--jid", dest="jid",
+.. help="JID to use")
+.. optp.add_option("-p", "--password", dest="password",
+.. help="password to use")
+..
+.. opts, args = optp.parse_args()
+..
+.. # Setup logging.
+.. logging.basicConfig(level=opts.loglevel,
+.. format='%(levelname)-8s %(message)s')
+..
+.. if opts.jid is None:
+.. opts.jid = raw_input("Username: ")
+.. if opts.password is None:
+.. opts.password = getpass.getpass("Password: ")
+..
+.. # Setup the EchoBot and register plugins. Note that while plugins may
+.. # have interdependencies, the order in which you register them does
+.. # not matter.
+.. xmpp = EchoBot(opts.jid, opts.password)
+.. xmpp.register_plugin('xep_0030') # Service Discovery
+.. xmpp.register_plugin('xep_0199') # XMPP Ping
+..
+.. # If you are working with an OpenFire server, you may need
+.. # to adjust the SSL version used:
+.. # xmpp.ssl_version = ssl.PROTOCOL_SSLv3
+..
+.. # Connect to the XMPP server and start processing XMPP stanzas.
+.. if xmpp.connect():
+.. # If you do not have the pydns library installed, you will need
+.. # to manually specify the name of the server if it does not match
+.. # the one in the JID. For example, to use Google Talk you would
+.. # need to use:
+.. #
+.. # if xmpp.connect(('talk.google.com', 5222)):
+.. # ...
+.. xmpp.process(threaded=False)
+.. print("Done")
+.. else:
+.. print("Unable to connect.")
diff --git a/docs/getting_started/iq.rst b/docs/getting_started/iq.rst
new file mode 100644
index 00000000..7ac1508c
--- /dev/null
+++ b/docs/getting_started/iq.rst
@@ -0,0 +1,2 @@
+Send/Receive IQ Stanzas
+=======================
diff --git a/docs/getting_started/muc.rst b/docs/getting_started/muc.rst
new file mode 100644
index 00000000..08f721f7
--- /dev/null
+++ b/docs/getting_started/muc.rst
@@ -0,0 +1,2 @@
+Mulit-User Chat (MUC) Bot
+=========================
diff --git a/docs/getting_started/presence.rst b/docs/getting_started/presence.rst
new file mode 100644
index 00000000..e070e812
--- /dev/null
+++ b/docs/getting_started/presence.rst
@@ -0,0 +1,2 @@
+Manage Presence Subscriptions
+=============================
diff --git a/docs/getting_started/proxy.rst b/docs/getting_started/proxy.rst
new file mode 100644
index 00000000..02ad10ae
--- /dev/null
+++ b/docs/getting_started/proxy.rst
@@ -0,0 +1,2 @@
+Enable HTTP Proxy Support
+=========================
diff --git a/docs/getting_started/scheduler.rst b/docs/getting_started/scheduler.rst
new file mode 100644
index 00000000..a9263a11
--- /dev/null
+++ b/docs/getting_started/scheduler.rst
@@ -0,0 +1,2 @@
+Send a Message Every 5 Minutes
+==============================
diff --git a/docs/getting_started/sendlogout.rst b/docs/getting_started/sendlogout.rst
new file mode 100644
index 00000000..2f9f1edf
--- /dev/null
+++ b/docs/getting_started/sendlogout.rst
@@ -0,0 +1,5 @@
+Login, Send a Message, and Disconnect
+=====================================
+
+A common use case for SleekXMPP is to send one-off messages from
+time to time.
diff --git a/docs/handlersmatchers.rst b/docs/handlersmatchers.rst
new file mode 100644
index 00000000..7ac750c0
--- /dev/null
+++ b/docs/handlersmatchers.rst
@@ -0,0 +1,2 @@
+Using Stream Handlers and Matchers
+==================================
diff --git a/docs/index.rst b/docs/index.rst
index 3b9e8298..95e49743 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -22,14 +22,13 @@ SleekXMPP
**Develop Releases**
- `Latest Develop Version <http://github.com/fritzy/SleekXMPP/zipball/develop>`_
- - `External Roster (Based on Develop Version) <http://github.com/fritzy/SleekXMPP/zipball/roster>`_
A mailing list and XMPP chat room are available for discussing and getting
help with SleekXMPP.
**Mailing List**
- http://groups.google.com/group/sleekxmpp-discussion
+ `SleekXMPP Discussion on Google Groups <http://groups.google.com/group/sleekxmpp-discussion>`_
**Chat**
`sleek@conference.jabber.org <xmpp:sleek@conference.jabber.org?join>`_
@@ -65,23 +64,45 @@ SleekXMPP's design goals and philosphy are:
sensible defaults and appropriate abstractions. XML can be ugly to work
with, but it doesn't have to be that way.
-SleekXMPP Architecture and Design
----------------------------------
+Getting Started (with Examples)
+-------------------------------
.. toctree::
:maxdepth: 2
+
+ getting_started/echobot
+ getting_started/sendlogout
+ getting_started/component
+ getting_started/presence
+ getting_started/muc
+ getting_started/proxy
+ getting_started/scheduler
+ getting_started/iq
- architecture.rst
Tutorials, FAQs, and How To Guides
----------------------------------
.. toctree::
:maxdepth: 2
-
- quickstart
+
+ xeps
xmpp_tdg
create_plugin
+ sasl
+ handlersmatchers
+
+Plugin Guides
+~~~~~~~~~~~~~
+.. toctree::
+ :maxdepth: 2
+
guide_xep_0030
+SleekXMPP Architecture and Design
+---------------------------------
+.. toctree::
+ :maxdepth: 2
+
+ architecture.rst
API Reference
-------------
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
deleted file mode 100644
index 5994052a..00000000
--- a/docs/quickstart.rst
+++ /dev/null
@@ -1,300 +0,0 @@
-====================
-SleekXMPP Quickstart
-====================
-
-.. 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 <http://groups.google.com/group/sleekxmpp-discussion>`_
- or join the chat room at `sleek@conference.jabber.org
- <xmpp:sleek@conference.jabber.org?join>`_.
-
-If you have not yet installed SleekXMPP, do so now by either checking out a version
-from `Github <http://github.com/fritzy/SleekXMPP>`_, or installing it using ``pip``
-or ``easy_install``.
-
-.. code-block:: sh
-
- pip install sleekxmpp # Or: easy_install sleekxmpp
-
-
-As a basic starting project, we will create an echo bot which will reply to any
-messages sent to it. We also go through adding some basic command line configuration
-for enabling or disabling debug log outputs and setting the username and password
-for the bot.
-
-For the command line options processing, we will use the built-in ``optparse``
-module and the ``getpass`` module for reading in passwords.
-
-TL;DR Just Give me the Boilerplate
-----------------------------------
-As you wish: :ref:`the completed example <echobot_complete>`.
-
-Overview
---------
-
-To get started, here is a brief outline of the structure that the final project will have:
-
-.. code-block:: python
-
- #!/usr/bin/env python
- # -*- coding: utf-8 -*-
-
- import sys
- import logging
- import getpass
- from optparse import OptionParser
-
- import sleekxmpp
-
- '''Here we will create out echo bot class'''
-
- if __name__ == '__main__':
- '''Here we will configure and read command line options'''
-
- '''Here we will instantiate our echo bot'''
-
- '''Finally, we connect the bot and start listening for messages'''
-
-Creating the EchoBot Class
---------------------------
-
-There are three main types of entities within XMPP — servers, components, and
-clients. Since our echo bot will only be responding to a few people, and won't need
-to remember thousands of users, we will use a client connection. A client connection
-is the same type that you use with your standard IM client such as Pidgin or Psi.
-
-SleekXMPP comes with a :class:`ClientXMPP <sleekxmpp.clientxmpp.ClientXMPP>` class
-which we can extend to add our message echoing feature. :class:`ClientXMPP <sleekxmpp.clientxmpp.ClientXMPP>`
-requires the parameters ``jid`` and ``password``, so we will let our ``EchoBot`` class accept those
-as well.
-
-.. code-block:: python
-
- class EchoBot(sleekxmpp.ClientXMPP):
-
- def __init__(self, jid, password):
- super(EchoBot, self).__init__(jid, password)
-
-Handling Session Start
-~~~~~~~~~~~~~~~~~~~~~~
-The XMPP spec requires clients to broadcast its presence and retrieve its roster (buddy list) once
-it connects and establishes a session with the XMPP server. Until these two tasks are completed,
-some servers may not deliver or send messages or presence notifications to the client. So we now
-need to be sure that we retrieve our roster and send an initial presence once the session has
-started. To do that, we will register an event handler for the :term:`session_start` event.
-
-.. code-block:: python
-
- def __init__(self, jid, password):
- super(EchoBot, self).__init__(jid, password)
-
- self.add_event_handler('session_start', self.start)
-
-
-Since we want the method ``self.start`` to execute when the :term:`session_start` event is triggered,
-we also need to define the ``self.start`` handler.
-
-.. code-block:: python
-
- def start(self, event):
- self.send_presence()
- self.get_roster()
-
-.. warning::
-
- Not sending an initial presence and retrieving the roster when using a client instance can
- prevent your program from receiving presence notifications or messages depending on the
- XMPP server you have chosen.
-
-Our event handler, like every event handler, accepts a single parameter which typically is the stanza
-that was received that caused the event. In this case, ``event`` will just be an empty dictionary since
-there is no associated data.
-
-Our first task of sending an initial presence is done using :meth:`send_presence <sleekxmpp.basexmpp.BaseXMPP.send_presence>`.
-Calling :meth:`send_presence <sleekxmpp.basexmpp.BaseXMPP.send_presence>` without any arguments will send the simplest
-stanza allowed in XMPP:
-
-.. code-block:: xml
-
- <presence />
-
-
-The second requirement is fulfilled using :meth:`get_roster <sleekxmpp.clientxmpp.ClientXMPP.get_roster>`, which
-will send an IQ stanza requesting the roster to the server and then wait for the response. You may be wondering
-what :meth:`get_roster <sleekxmpp.clientxmpp.ClientXMPP.get_roster>` returns since we are not saving any return
-value. The roster data is saved by an internal handler to ``self.roster``, and in the case of a :class:`ClientXMPP
-<sleekxmpp.clientxmpp.ClientXMPP>` instance to ``self.client_roster``. (The difference between ``self.roster`` and
-``self.client_roster`` is that ``self.roster`` supports storing roster information for multiple JIDs, which is useful
-for components, whereas ``self.client_roster`` stores roster data for just the client's JID.)
-
-It is possible for a timeout to occur while waiting for the server to respond, which can happen if the
-network is excessively slow or the server is no longer responding. In that case, an :class:`IQTimeout
-<sleekxmpp.exceptions.IQTimeout>` is raised. Similarly, an :class:`IQError <sleekxmpp.exceptions.IQError>` exception can
-be raised if the request contained bad data or requested the roster for the wrong user. In either case, you can wrap the
-``get_roster()`` call in a ``try``/``except`` block to retry the roster retrieval process.
-
-The XMPP stanzas from the roster retrieval process could look like this:
-
-.. code-block:: xml
-
- <iq type="get">
- <query xmlns="jabber:iq:roster" />
- </iq>
-
- <iq type="result" to="echobot@example.com" from="example.com">
- <query xmlns="jabber:iq:roster">
- <item jid="friend@example.com" subscription="both" />
- </query>
- </iq>
-
-Responding to Messages
-~~~~~~~~~~~~~~~~~~~~~~
-Now that an ``EchoBot`` instance handles :term:`session_start`, we can begin receiving and responding
-to messages. The :term:`message` event is fired whenever a ``<message />`` stanza is received, including
-for group chat messages, errors, etc. Properly responding to messages thus requires checking the ``'type'``
-interface of the message :term:`stanza object`.
-
-
-.. _echobot_complete:
-
-The Final Product
------------------
-Here then is the final result you should have after working through the guide above.
-
-.. code-block:: python
-
- #!/usr/bin/env python
- # -*- coding: utf-8 -*-
- import sys
- import logging
- import time
- import getpass
- from optparse import OptionParser
-
- import sleekxmpp
-
- # Python versions before 3.0 do not use UTF-8 encoding
- # by default. To ensure that Unicode is handled properly
- # throughout SleekXMPP, we will set the default encoding
- # ourselves to UTF-8.
- if sys.version_info < (3, 0):
- reload(sys)
- sys.setdefaultencoding('utf8')
-
-
- class EchoBot(sleekxmpp.ClientXMPP):
-
- """
- A simple SleekXMPP bot that will echo messages it
- receives, along with a short thank you message.
- """
-
- def __init__(self, jid, password):
- sleekxmpp.ClientXMPP.__init__(self, jid, password)
-
- # The session_start event will be triggered when
- # the bot establishes its connection with the server
- # and the XML streams are ready for use. We want to
- # listen for this event so that we we can intialize
- # our roster.
- self.add_event_handler("session_start", self.start)
-
- # The message event is triggered whenever a message
- # stanza is received. Be aware that that includes
- # MUC messages and error messages.
- self.add_event_handler("message", self.message)
-
- def start(self, event):
- """
- Process the session_start event.
-
- Typical actions for the session_start event are
- requesting the roster and broadcasting an intial
- presence stanza.
-
- Arguments:
- event -- An empty dictionary. The session_start
- event does not provide any additional
- data.
- """
- self.send_presence()
- self.get_roster()
-
- def message(self, msg):
- """
- Process incoming message stanzas. Be aware that this also
- includes MUC messages and error messages. It is usually
- a good idea to check the messages's type before processing
- or sending replies.
-
- Arguments:
- msg -- The received message stanza. See the documentation
- for stanza objects and the Message stanza to see
- how it may be used.
- """
- msg.reply("Thanks for sending\n%(body)s" % msg).send()
-
-
- if __name__ == '__main__':
- # Setup the command line arguments.
- optp = OptionParser()
-
- # Output verbosity options.
- optp.add_option('-q', '--quiet', help='set logging to ERROR',
- action='store_const', dest='loglevel',
- const=logging.ERROR, default=logging.INFO)
- optp.add_option('-d', '--debug', help='set logging to DEBUG',
- action='store_const', dest='loglevel',
- const=logging.DEBUG, default=logging.INFO)
- optp.add_option('-v', '--verbose', help='set logging to COMM',
- action='store_const', dest='loglevel',
- const=5, default=logging.INFO)
-
- # JID and password options.
- optp.add_option("-j", "--jid", dest="jid",
- help="JID to use")
- optp.add_option("-p", "--password", dest="password",
- help="password to use")
-
- opts, args = optp.parse_args()
-
- # Setup logging.
- logging.basicConfig(level=opts.loglevel,
- format='%(levelname)-8s %(message)s')
-
- if opts.jid is None:
- opts.jid = raw_input("Username: ")
- if opts.password is None:
- opts.password = getpass.getpass("Password: ")
-
- # Setup the EchoBot and register plugins. Note that while plugins may
- # have interdependencies, the order in which you register them does
- # not matter.
- xmpp = EchoBot(opts.jid, opts.password)
- xmpp.register_plugin('xep_0030') # Service Discovery
- xmpp.register_plugin('xep_0004') # Data Forms
- xmpp.register_plugin('xep_0060') # PubSub
- xmpp.register_plugin('xep_0199') # XMPP Ping
-
- # If you are working with an OpenFire server, you may need
- # to adjust the SSL version used:
- # xmpp.ssl_version = ssl.PROTOCOL_SSLv3
-
- # If you want to verify the SSL certificates offered by a server:
- # xmpp.ca_certs = "path/to/ca/cert"
-
- # Connect to the XMPP server and start processing XMPP stanzas.
- if xmpp.connect():
- # If you do not have the pydns library installed, you will need
- # to manually specify the name of the server if it does not match
- # the one in the JID. For example, to use Google Talk you would
- # need to use:
- #
- # if xmpp.connect(('talk.google.com', 5222)):
- # ...
- xmpp.process(threaded=False)
- print("Done")
- else:
- print("Unable to connect.")
diff --git a/docs/sasl.rst b/docs/sasl.rst
new file mode 100644
index 00000000..46c45c2a
--- /dev/null
+++ b/docs/sasl.rst
@@ -0,0 +1,2 @@
+How SASL Authentication Works
+=============================
diff --git a/docs/xeps.rst b/docs/xeps.rst
new file mode 100644
index 00000000..a541a586
--- /dev/null
+++ b/docs/xeps.rst
@@ -0,0 +1,2 @@
+Supported XEPS
+==============
diff --git a/examples/echo_client.py b/examples/echo_client.py
index dadf3b4e..cd1b1d02 100755
--- a/examples/echo_client.py
+++ b/examples/echo_client.py
@@ -76,7 +76,8 @@ class EchoBot(sleekxmpp.ClientXMPP):
for stanza objects and the Message stanza to see
how it may be used.
"""
- msg.reply("Thanks for sending\n%(body)s" % msg).send()
+ if msg['type'] in ('chat', 'normal'):
+ msg.reply("Thanks for sending\n%(body)s" % msg).send()
if __name__ == '__main__':
--
cgit v1.2.3