diff --git a/docs/api/basexmpp.rst b/docs/api/basexmpp.rst new file mode 100644 index 00000000..841df3db --- /dev/null +++ b/docs/api/basexmpp.rst @@ -0,0 +1,8 @@ +======== +basexmpp +======== + +.. module:: sleekxmpp.basexmpp + +.. autoclass:: BaseXMPP + :members: diff --git a/docs/api/xmlstream.rst b/docs/api/xmlstream.rst new file mode 100644 index 00000000..7835bf57 --- /dev/null +++ b/docs/api/xmlstream.rst @@ -0,0 +1,8 @@ +========= +xmlstream +========= + +.. module:: sleekxmpp.xmlstream + +.. autoclass:: XMLStream + :members: diff --git a/docs/features.rst b/docs/features.rst new file mode 100644 index 00000000..4d93d5c3 --- /dev/null +++ b/docs/features.rst @@ -0,0 +1,2 @@ +How to Use Stream Features +========================== diff --git a/docs/getting_started/echobot.rst b/docs/getting_started/echobot.rst index 9defca6b..053a76f2 100644 --- a/docs/getting_started/echobot.rst +++ b/docs/getting_started/echobot.rst @@ -1,3 +1,5 @@ +.. _echobot: + =============================== SleekXMPP Quickstart - Echo Bot =============================== @@ -386,127 +388,3 @@ can also be found in the SleekXMPP `examples directory `_ + or join the chat room at `sleek@conference.jabber.org + `_. A common use case for SleekXMPP is to send one-off messages from -time to time. +time to time. For example, one use case could be sending out a notice when +a shell script finishes a task. + +We will create our one-shot bot based on the pattern explained in :ref:`echobot`. To +start, we create a client class based on :class:`ClientXMPP ` and +register a handler for the :term:`session_start` event. We will also accept parameters +for the JID that will receive our message, and the string content of the message. + +.. code-block:: python + + import sleekxmpp + + + class SendMsgBot(sleekxmpp.ClientXMPP): + + def __init__(self, jid, password, recipient, msg): + super(SendMsgBot, self).__init__(jid, password) + + self.recipient = recipient + self.msg = msg + + self.add_event_handler('session_start', self.start) + + def start(self, event): + self.send_presence() + self.get_roster() + +Note that as in :ref:`echobot`, we need to include send an initial presence and request +the roster. Next, we want to send our message, and to do that we will use :meth:`send_message `. + +.. code-block:: python + + def start(self, event): + self.send_presence() + self.get_roster() + + self.send_message(mto=self.recipient, mbody=self.msg) + +Finally, we need to disconnect the client using :meth:`disconnect `. +Now, sent stanzas are placed in a queue to pass them to the send thread. If we were to call +:meth:`disconnect ` without any parameters, then it is possible +for the client to disconnect before the send queue is processed and the message is actually +sent on the wire. To ensure that our message is processed, we use +:meth:`disconnect(wait=True) `. + +.. code-block:: python + + def start(self, event): + self.send_presence() + self.get_roster() + + self.send_message(mto=self.recipient, mbody=self.msg) + + self.disconnect(wait=True) + +.. warning:: + + If you happen to be adding stanzas to the send queue faster than the send thread + can process them, then :meth:`disconnect(wait=True) ` + will block and not disconnect. + +Final Product +------------- + +.. compound:: + + The final step is to create a small runner script for initialising our ``SendMsgBot`` class and adding some + basic configuration options. By following the basic boilerplate pattern in :ref:`echobot`, we arrive + at the code below. To experiment with this example, you can use: + + .. code-block:: sh + + python send_client.py -d -j oneshot@example.com -t someone@example.net -m "This is a message" + + which will prompt for the password and then log in, send your message, and then disconnect. To test, open + your regular IM client with the account you wish to send messages to. When you run the ``send_client.py`` + example and instruct it to send your IM client account a message, you should receive the message you + gave. If the two JIDs you use also have a mutual presence subscription (they're on each other's buddy lists) + then you will also see the ``SendMsgBot`` client come online and then go offline. + +.. include:: ../../examples/send_client.py + :literal: diff --git a/docs/index.rst b/docs/index.rst index 95e49743..5da389b9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -67,7 +67,7 @@ SleekXMPP's design goals and philosphy are: Getting Started (with Examples) ------------------------------- .. toctree:: - :maxdepth: 2 + :maxdepth: 1 getting_started/echobot getting_started/sendlogout @@ -82,27 +82,29 @@ Getting Started (with Examples) Tutorials, FAQs, and How To Guides ---------------------------------- .. toctree:: - :maxdepth: 2 + :maxdepth: 1 xeps xmpp_tdg create_plugin + features sasl handlersmatchers Plugin Guides ~~~~~~~~~~~~~ .. toctree:: - :maxdepth: 2 + :maxdepth: 1 guide_xep_0030 SleekXMPP Architecture and Design --------------------------------- .. toctree:: - :maxdepth: 2 + :maxdepth: 3 - architecture.rst + architecture + plugin_arch API Reference ------------- @@ -111,6 +113,8 @@ API Reference event_index api/clientxmpp + api/basexmpp + api/xmlstream Additional Info --------------- diff --git a/docs/plugin_arch.rst b/docs/plugin_arch.rst new file mode 100644 index 00000000..0141b793 --- /dev/null +++ b/docs/plugin_arch.rst @@ -0,0 +1,2 @@ +Plugin Architecture +=================== diff --git a/examples/send_client.py b/examples/send_client.py index fd99e8c9..b3673512 100755 --- a/examples/send_client.py +++ b/examples/send_client.py @@ -29,13 +29,18 @@ if sys.version_info < (3, 0): class SendMsgBot(sleekxmpp.ClientXMPP): """ - A simple SleekXMPP bot that will echo messages it - receives, along with a short thank you message. + A basic SleekXMPP bot that will log in, send a message, + and then log out. """ - def __init__(self, jid, password): + def __init__(self, jid, password, recipient, message): sleekxmpp.ClientXMPP.__init__(self, jid, password) + # The message we wish to send, and the JID that + # will receive it. + self.recipient = recipient + self.msg = message + # 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 @@ -43,11 +48,6 @@ class SendMsgBot(sleekxmpp.ClientXMPP): # 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. @@ -63,27 +63,14 @@ class SendMsgBot(sleekxmpp.ClientXMPP): """ self.send_presence() self.get_roster() - msg = self.Message() - msg['to'] = 'user@example.com' - msg['type'] = 'chat' - msg['body'] = "Hello there!" - msg.send() - self.disconnect() - 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. + self.send_message(mto=self.recipient, + mbody=self.msg, + mtype='chat') - 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() - print "Msg rceived from %(body)s: %(jid)s" % msg + # Using wait=True ensures that the send queue will be + # emptied before ending the session. + self.disconnect(wait=True) if __name__ == '__main__': @@ -106,6 +93,10 @@ if __name__ == '__main__': help="JID to use") optp.add_option("-p", "--password", dest="password", help="password to use") + optp.add_option("-t", "--to", dest="to", + help="JID to send the message to") + optp.add_option("-m", "--message", dest="message", + help="message to send") opts, args = optp.parse_args() @@ -117,14 +108,16 @@ if __name__ == '__main__': opts.jid = raw_input("Username: ") if opts.password is None: opts.password = getpass.getpass("Password: ") + if opts.to is None: + opts.to = raw_input("Send To: ") + if opts.message is None: + opts.message = raw_input("Message: ") # Setup the EchoBot and register plugins. Note that while plugins may # have interdependencies, the order in which you register them does # not matter. - xmpp = SendMsgBot(opts.jid, opts.password) + xmpp = SendMsgBot(opts.jid, opts.password, opts.to, opts.message) 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