e3
--

e3 is a module that provides a common interface for multiple IM libraries.

It started as an API for e3.msn but it grew to support multiple implementations.

The main components in e3 are:

Events

        An event is a data structure that contains information about an event that
        happened in the protocol, for example a contact went online or a contact
        sent us a message.

        An event has a type, that identifies what kind of event it is for example
        Event.LOGIN_SUCCEED and zero or more parameters depending on the event type.

        Events are generated in the handlers that implement the e3 API and should be
        handled by the GUI code to inform the user about the events.

Actions

        An action is a data structure that contains information about an action
        that the protocol implementation should execute, for example to send a 
        message or change the status.

        An action has a type, that identifies what kind of action the
        implementation should execute, for example Action.ACTION_LOGIN and zero
        or more parameters depending on the action type.

        Actions are generated in the GUI and sent to the protocol handler to trigger
        an action.

        Actions and Events are pretty similar but in opposite directions, Actions are
        generated by the user and sent to the protocol handler and Events are generated
        by the protocol handler and sent to the user. Both have a type and zero or more
        parameters.

Worker

        The Worker is the main class that a protocol implementation should subclass to
        implement a specific protocol, base.Worker has all the common code and empty
        methods that should be implemented by the protocol implementation.

        A dummy implementation is provided to see how a really basic protocol should be
        implemented and to be used for testing in emesene. This implementation is almost
        an echo implementation where some dummy users are added to the user list and all
        messages sent are responded back by some random contact.

        Worker is a class that inherits from threading.Thread and has one input Queue
        that receives Actions and one output Queue that sends Events.

        Using Queues provides an easy way to synchronize between threads and allow
        to run lengthy operations in the thread without blocking the GUI.

        The main method of Worker is run that loops until e3.Action.ACTION_QUIT is found.
        The function blocks waiting for an item in the input Queue, when an item arrives
        (an Action object) then the handler for the Action type is obtained and the 
        handler is called passing the parameters from the Action object to the handler.

        The handler can generate zero or more events by adding Event objects to the events
        Queue.

        Worker shouldn't interact with other parts of the code other than using the events
        Queue to avoid race conditions and synchronization issues.

        This architecture is implemented to allow using threads but avoid the need for locks
        which are a pain to code and maintain.

Session

        The Session class is the class that exposes the functionality to the end user.

        It contains all the information about a given session and exposes the Worker API
        in a more programmer friendly fashion by encapsulation the actions behind methods.

        This is the class you should interact with from the emesene GUI.

base
~~~~

The base module contains all the base classes that are common to the protocols
and may be extended.

If a class should be used or extended by all protocols then it should be here.

cache
~~~~~

This module contains classes to deal with caching things for all the protocols.

common
~~~~~~

This module contains common code that could be used by any implementation.

If you have some functionality that is common to many protocols such as config,
xml etc it should go here.

dummy
~~~~~

A dummy implementation of a protocol, it works as an example for people that
want to implement a new protocol with the e3 API and as a dummy protocol to be
used by developers to test emesene without reconnecting multiple times.

jabber
~~~~~~

A wrapper around the xmpppy module to work with the e3 API to support the jabber
protocol (Gtalk, Jabber, Facebook chat etc).

msn
~~~

The first implementation of the MSN protocol for e3, this version is a little
behind papyon but is useful as a fall-back and also as a reference
implementation for e3 since it doesn't wrap any other library, it's the only
pure e3 based real protocol implementation.

papylib
~~~~~~~

A wrapper around the papyon module to work with the e3 API to support the MSN
protocol.
