diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/getting_started/component.rst | 2 | ||||
| -rw-r--r-- | docs/getting_started/echobot.rst | 512 | ||||
| -rw-r--r-- | docs/getting_started/iq.rst | 2 | ||||
| -rw-r--r-- | docs/getting_started/muc.rst | 2 | ||||
| -rw-r--r-- | docs/getting_started/presence.rst | 2 | ||||
| -rw-r--r-- | docs/getting_started/proxy.rst | 2 | ||||
| -rw-r--r-- | docs/getting_started/scheduler.rst | 2 | ||||
| -rw-r--r-- | docs/getting_started/sendlogout.rst | 5 | ||||
| -rw-r--r-- | docs/handlersmatchers.rst | 2 | ||||
| -rw-r--r-- | docs/index.rst | 35 | ||||
| -rw-r--r-- | docs/quickstart.rst | 300 | ||||
| -rw-r--r-- | docs/sasl.rst | 2 | ||||
| -rw-r--r-- | docs/xeps.rst | 2 |
13 files changed, 563 insertions, 307 deletions
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 +============== |