slixmpp/docs/index.rst

Slixmpp
#########

.. sidebar:: Get the Code

    The latest source code for Slixmpp may be found on the `Git repo
    <http://git.poez.io/slixmpp>`_. ::

        git clone git://git.poez.io/slixmpp

    An XMPP chat room is available for discussing and getting help with slixmpp.

    **Chat**
        `slixmpp@muc.poez.io <xmpp:slixmpp@muc.poez.io?join>`_

    **Reporting bugs**
        You can report bugs at http://dev.louiz.org/projects/slixmpp/issues.

.. note::
    slixmpp is a friendly fork of `SleekXMPP <https://github.com/fritzy/SleekXMPP>`_
    which goal is to use asyncio instead of threads to handle networking. See
    :ref:`differences`.

Slixmpp is an :ref:`MIT licensed <license>` XMPP library for Python 3.4+,

Slixmpp's design goals and philosphy are:

**Low number of dependencies**
    Installing and using Slixmpp should be as simple as possible, without
    having to deal with long dependency chains.

    As part of reducing the number of dependencies, some third party
    modules are included with Slixmpp in the ``thirdparty`` directory.
    Imports from this module first try to import an existing installed
    version before loading the packaged version, when possible.

**Every XEP as a plugin**
    Following Python's "batteries included" approach, the goal is to
    provide support for all currently active XEPs (final and draft). Since
    adding XEP support is done through easy to create plugins, the hope is
    to also provide a solid base for implementing and creating experimental
    XEPs.

**Rewarding to work with**
    As much as possible, Slixmpp should allow things to "just work" using
    sensible defaults and appropriate abstractions. XML can be ugly to work
    with, but it doesn't have to be that way.


Here's your first Slixmpp Bot:
--------------------------------

.. code-block:: python

    import asyncio
    import logging

    from slixmpp import ClientXMPP
    from slixmpp.exceptions import IqError, IqTimeout


    class EchoBot(ClientXMPP):

        def __init__(self, jid, password):
            ClientXMPP.__init__(self, jid, password)

            self.add_event_handler("session_start", self.session_start)
            self.add_event_handler("message", self.message)

            # If you wanted more functionality, here's how to register plugins:
            # self.register_plugin('xep_0030') # Service Discovery
            # self.register_plugin('xep_0199') # XMPP Ping

            # Here's how to access plugins once you've registered them:
            # self['xep_0030'].add_feature('echo_demo')

        def session_start(self, event):
            self.send_presence()
            self.get_roster()

            # Most get_*/set_* methods from plugins use Iq stanzas, which
            # are sent asynchronously. You can almost always provide a
            # callback that will be executed when the reply is received.

        def message(self, msg):
            if msg['type'] in ('chat', 'normal'):
                msg.reply("Thanks for sending\n%(body)s" % msg).send()


    if __name__ == '__main__':
        # Ideally use optparse or argparse to get JID,
        # password, and log level.

        logging.basicConfig(level=logging.DEBUG,
                            format='%(levelname)-8s %(message)s')

        xmpp = EchoBot('somejid@example.com', 'use_getpass')
        xmpp.connect()
        xmpp.process()


To read if you come from SleekXMPP
----------------------------------

.. 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

    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

Core Stanzas
~~~~~~~~~~~~
.. toctree::
    :maxdepth: 2

    api/stanza/rootstanza
    api/stanza/message
    api/stanza/presence
    api/stanza/iq

Plugins
~~~~~~~
.. toctree::
    :maxdepth: 2


Additional Info
---------------
.. toctree::
    :hidden:

    glossary
    license

* :ref:`license`
* :ref:`glossary`
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

SleekXMPP Credits
-----------------

.. 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
    them for their work.


**Main Author:** `Nathan Fritz <http://andyet.net/team/fritzy>`_
     `fritzy@netflint.net <xmpp:fritzy@netflint.net?message>`_,
     `@fritzy <http://twitter.com/fritzy>`_

     Nathan is also the author of XMPPHP and `Seesmic-AS3-XMPP
     <http://code.google.com/p/seesmic-as3-xmpp/>`_, and a former member of the XMPP
     Council.

**Co-Author:** `Lance Stout <http://andyet.net/team/lance>`_
     `lancestout@gmail.com <xmpp:lancestout@gmail.com?message>`_,
     `@lancestout <http://twitter.com/lancestout>`_

Both Fritzy and Lance work for `&yet <http://andyet.net>`_, which specializes in
realtime web and XMPP applications.

    - `contact@andyet.net <mailto:contact@andyet.net>`_
    - `XMPP Consulting <http://xmppconsulting.com>`_

**Contributors:**
    - Brian Beggs (`macdiesel <http://github.com/macdiesel>`_)
    - Dann Martens (`dannmartens <http://github.com/dannmartens>`_)
    - Florent Le Coz (`louiz <http://github.com/louiz>`_)
    - Kevin Smith (`Kev <http://github.com/Kev>`_, http://kismith.co.uk)
    - Remko Tronçon (`remko <http://github.com/remko>`_, http://el-tramo.be)
    - Te-jé Rogers (`te-je <http://github.com/te-je>`_)
    - Thom Nichols (`tomstrummer <http://github.com/tomstrummer>`_)