
RSL - Remote Service Library
============================

This module provides a collection of interfaces and a "plugin" mechanism to
access remote services with different protocols and technology in a unified 
way.

The library has been developed as part of a "command line shell service 
integration". It has been separated into its own package to allow a modular 
installation and if may be useful for other projects too.

RSL is a pure client side library which allows easy access to web services. It
provides a full abstraction of service protocol and technology and tries to map
each remote service to Python methods. Hence, from a programmers point of view, 
there should be almost no difference (except some minimal boilerplate) between
a local method call and a remote call. Even the fact, whether SOAP, JSON or
whatever protocol in use, should be completely hidden (but not inaccessible).

One of the main goals of the library is, to make it easily possible to add more
web service and transport protocols, without changing all the other parts. This
allows to extend the library bit by bit and makes each package much more
maintainable. It also allows to keep the installation foot print at a minimum 
(just install only required modules).

Documentation
-------------

Documentation is currently in a very bad shape, but this will change soon, as 
the API stabilises. Furthermore, a growing user base which provides feedback,
will shorten this time frame further ;).

As mentioned above the core of this modules are the interface definitions, and
the discovery mechanism for "protocol-plugins" using Setuptools and Zope 
interfaces. In general the philosophy behind the given interfaces is, that
a web-service client can be split into various components.

    **Transport**: 
        Every remote access needs some kind of transport. Transport protocols
        are plug-able and can easily be replaced to allow easier integration 
        into other frameworks like Twisted.
    **Description**:
        As there are many different service description formats, which often
        support multiple service protocols, it is just logical to implement 
        service descriptions as separate components.
    **Proxy**:
        These kind of components have the knowledge to convert the information
        from a description and protocols standards into a usable Python object,
        which acts as proxy to invoke remote services.
    **De/Serialiser**:
        As different protocols allow different encoding formats, de/serialisers,
        are implemented as independent components, which allows to reuse them
        wherever appropriate.
    **Typesystem**:
        Often XML based encoding standards, feature an own type system (mostly
        expressed as XML-Schema). Such Typeystems, will also be used for JSON,
        and probably other future encoding standards will follow. A Typesystem,
        tries to map between Python data types and wire-representation, and 
        allows the actual user, to ignore the technical details.
 
All these components above are implemented as independent from each other as
possible, to allow easy replacement, high reusability, great extensibility 
and flexibility, and of course easy installation.

The following modules are developed along with this modules:

    * `rsl.wsdl <http://cheeseshop.python.org/pypi/rsl.wsdl>`_ : common WSDL module
    * `rsl.wsdl1 <http://cheeseshop.python.org/pypi/rsl.wsdl1>`_ : WSDL 1
    * `rsl.soap11 <http://cheeseshop.python.org/pypi/rsl.soap11>`_ : SOAP 1.1 + WSDL 1 SOAP 1.1 extension
    * `rsl.mime <http://cheeseshop.python.org/pypi/rsl.mime>`_ : WSDL 1 MIME extension
    * `rsl.http <http://cheeseshop.python.org/pypi/rsl.http>`_ : WSDL 1 HTTP extension
    * `rsl.rest <http://cheeseshop.python.org/pypi/rsl.rest>`_ : REST like services
    * `rsl.jsonrpc10 <http://cheeseshop.python.org/pypi/rsl.jsonrpc10>`_ : JSON-RPC 1.0 implementation
    * `rsl.smd01 <http://cheeseshop.python.org/pypi/rsl.smd01>`_ : SMD 0.1 implementation
    * `rsl.upnp <http://cheeseshop.python.org/pypi/rsl.upnp>`_ : UPnP description
    * `rsl.xmlrpc <http://cheeseshop.python.org/pypi/rsl.xmlrpc>`_ : XML-RPC
    * `rsl.xsd <http://cheeseshop.python.org/pypi/rsl.xsd>`_ : XML Schema type system
    

For examples on how to use the library, please see the additional modules,
and tests included there.

Status
------

The library works quite well for the command line service integration. 
The installation is quite effortless with Python eggs and easyinstall.
However, as the whole project grows quite huge, and it is in an early
development stage, there are many things, which are not solved that elegant,
and it is very likely, that some refactoring will be happen in the near future.
However, most of the refactoring will make the code base more conformant to
PEP-08. The high likeliness in API changes is also the reason why this
release is currently classified *alpha*.

An important to-do is, to remove as much inconveniences for the library 
as possible, which will also greatly improve the overall library design.

The type system component is a bit cumbersome, and currently there is only one
implementation (XML-Schema) available for it. I hope, that the situation here,
will improve, as at least a second type system implementation becomes available.


Comment
-------

As this library also supports SOAP, there may be the question: "Why another
SOAP library?". The simple answer is, that there is no working client side
SOAP library available. I tested all three (or four?) major SOAP libraries,
and not one of them worked with the web service I needed. Most of those
SOAP libraries are just too simple, for my use cases, and others have some
major interoperability problems. (So two reasons: extending an already
available library would be about the same effort, and fixing a full-featured
library, would be even more effort because of ugly code base.)
