Protocol

Basically, a protocol performs the following tasks:

• extracts a function name and argument values from a request,
• extracts context data from the request,
• forms a response out of the result returned by the function,
• forms an error response in the case of an exception.

When a server asks a protocol to extract a function name the protocol may return either a function name or a callable object.

In the former case, the server will request argument values after determining the function and its arguments specification.

In the latter case, the callable object is directly called with three arguments: a server object, a request object and and a context. This is used for special cases, currently only for WSDL descrption generation.

Protocol implementation

A protocol must be an instance of pyws.protocols.base.Protocol and must implement methods get_function, get_arguments, get_response, get_error_response.

class pyws.protocols.base.Protocol(context_data_getter=None, common_context_data_getter=None)

Abstract protocol class. Implements basic constructor, context and error handling.

__init__(context_data_getter=None, common_context_data_getter=None)

Both arguments are callable objects that accept exactly one argument (namely a request) and return context data. context_data_getter is used to get context data for registered functions. common_context_data_getter is used for functions returned directly by a protocol. If you need to override this method don’t forget to call it from successors’ constructor.

get_arguments(request, arguments)

Extracts argument values from the request according to the arguments specification.

get_error(error)

A helper function, gets standard information from the error.

get_error_response(error)

Forms an error response from the error.

get_function(request)

Extracts a function name or a function from the request.

get_response(result, name, return_type)

Forms a response from the result returned by a function according to the return type specification. name is the of name the function.

Concerning SOAP protocol

SOAP can’t be thought of without WSDL, so to instantiate this protocol we need some information. Also for SOAP, the usual practice is to specify a context in SOAP envelope headers, so a simple context data getter is implemented for your convenience. The only thing you need to do to implement context data extraction from a request is to specify headers schema:

SoapProtocol.__init__(service_name, tns, location, headers_schema=None, *args, **kwargs)

service_name gives a name to the server, it is used to generate WSDL file. tns is a root namespace, where all the stuff lives, SOAP is based on XML, so no wonder we need it. location tells the server, where it lives. It is only a piece of information required by pyws to generate a proper WSDL file, it is not a real binding to an URL. headers_schema a schema used to retrive context data from request headers. Other arguments are passed to parent constructor.