The Remote Service Library

This module contains classes that are useful for building remote services that conform to a standard request and response model. To conform to this model, a service must be like the following class:

# Each service instance only handles a single request and is then discarded.
# Make these objects light weight.
class Service(object):

    # It must be possible to construct service objects without any parameters.
    # If your constructor needs extra information you should provide a
    # no-argument factory function to create service instances.
    def __init__(self):
        ...

    # Each remote method must use the 'remote' decorator, passing the request
    # and response message types.  The remote method itself must take a single
    # parameter which is an instance of RequestMessage and return an instance
    # of ResponseMessage.
    @method(RequestMessage, ResponseMessage)
    def remote_method(self, request):
        # Return an instance of ResponseMessage.

    # A service object may optionally implement a 'initialize_request_state'
    # method that takes as a parameter a single instance of a RequestState.  If
    # a service does not implement this method it will not receive the request
    # state.
    def initialize_request_state(self, state):
        ...

The Service class is a convenient base class that provides the above functionality. It implements all required and optional methods for a service. It also has convenience methods for creating factory functions that can pass persistent global state to a new service instance.

The remote decorator is used to declare which methods of a class are meant to service RPCs. While this decorator is not responsible for handing sockets and various underlying RPC protocols. The decorator ensures that you are using the correct request type, but it does not check for initialization.

When the remote decorator is used on a method, the wrapper method will have a 'remote' property associated with it. This property contains the request_type and response_type expected by the method's implementation.

On its own, the remote decorator does not provide any support for subclassing remote methods. In order to extend a service, use the subclass methods to redecorate. For example:

class MyService(Service):

    @method(DoSomethingRequest, DoSomethingResponse)
    def do_something(self, request):
        ... implement do-something ...

class MyBetterService(MyService):

    @method(DoSomethingRequest, DoSomethingResponse)
    def do_something(self, request):
        response = super(MyBetterService, self).do_something.remote.method(request)
        ... do something with response ...
        return response