PickleRPC¶
PickleRPC.py
PickleRPC provides a Server object for connection to Pickle-RPC servers for the purpose of making requests and receiving the responses.
>>> from MiscUtils.PickleRPC import Server
>>> server = Server('http://localhost:8080/Examples/PickleRPCExample')
>>> server.multiply(10,20)
200
>>> server.add(10,20)
30
See also: Server, PickleRPCServlet, Examples.PickleRPCExample
UNDER THE HOOD
Requests look like this:
{
'version': 1, # default
'action': 'call', # default
'methodName': 'NAME',
'args': (A, B, ...), # default = (,)
'keywords': {'A': A, 'B': B, ...} # default = {}
}
Only ‘methodName’ is required since that is the only key without a default value.
Responses look like this:
{
'timeReceived': N,
'timeReponded': M,
'value': V,
'exception': E,
'requestError': E,
}
‘timeReceived’ is the time the initial request was received.
‘timeResponded’ is the time at which the response was finished, as
close to transmission as possible. The times are expressed as
number of seconds since the Epoch, e.g., time.time()
.
Value is whatever the method happened to return.
Exception may be ‘occurred’ to indicate that an exception occurred, the specific exception, such as “KeyError: foo” or the entire traceback (as a string), at the discretion of the server. It will always be a non-empty string if it is present.
RequestError is an exception such as “Missing method in request.” (with no traceback) that indicates a problem with the actual request received by the Pickle-RPC server.
Value, exception and requestError are all exclusive to each other.
SECURITY
Pickle RPC uses the SafeUnpickler class (in this module) to prevent unpickling of unauthorized classes. By default, it doesn’t allow _any_ classes to be unpickled. You can override allowedGlobals() or findGlobal() in a subclass as needed to allow specific class instances to be unpickled.
Note that both Transport in this package and PickleRPCServlet in the Webware main package are derived from SafeUnpickler.
CREDIT
The implementation of this module was taken directly from Python’s xmlrpclib and then transformed from XML-orientation to Pickle-orientation.
The zlib compression was adapted from code by Skip Montanaro that I found here: http://manatee.mojam.com/~skip/python/
- exception MiscUtils.PickleRPC.Error¶
Bases:
Exception
The abstract exception/error class for all PickleRPC errors.
- __init__(*args, **kwargs)¶
- add_note()¶
Exception.add_note(note) – add a note to the exception
- args¶
- with_traceback()¶
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception MiscUtils.PickleRPC.InvalidContentTypeError(headers, content)¶
Bases:
ResponseError
Invalid content type error.
- __init__(headers, content)¶
- add_note()¶
Exception.add_note(note) – add a note to the exception
- args¶
- with_traceback()¶
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception MiscUtils.PickleRPC.ProtocolError(url, errcode, errmsg, headers)¶
Bases:
ResponseError
,ProtocolError
RPC protocol error.
- __init__(url, errcode, errmsg, headers)¶
- add_note()¶
Exception.add_note(note) – add a note to the exception
- args¶
- with_traceback()¶
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception MiscUtils.PickleRPC.RequestError¶
Bases:
Error
Errors originally raised by the server caused by malformed requests.
- __init__(*args, **kwargs)¶
- add_note()¶
Exception.add_note(note) – add a note to the exception
- args¶
- with_traceback()¶
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception MiscUtils.PickleRPC.ResponseError¶
Bases:
Error
Unhandled exceptions raised when the server was computing a response.
- These will indicate errors such as:
exception in the actual target method on the server
malformed responses
non “200 OK” status code responses
- __init__(*args, **kwargs)¶
- add_note()¶
Exception.add_note(note) – add a note to the exception
- args¶
- with_traceback()¶
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- class MiscUtils.PickleRPC.SafeTransport¶
Bases:
Transport
Handle an HTTPS transaction to a Pickle-RPC server.
- allowedGlobals()¶
Allowed class names.
Must return a list of (moduleName, klassName) tuples for all classes that you want to allow to be unpickled.
Example:
return [('datetime', 'date')]
Allows datetime.date instances to be unpickled.
- findGlobal(module, klass)¶
Find class name.
- load(file)¶
Unpickle a file.
- loads(s)¶
Unpickle a string.
- make_connection(host, port=None, key_file=None, cert_file=None)¶
Create an HTTPS connection object from a host descriptor.
- parse_response(f)¶
Read response from input file and parse it.
- parse_response_gzip(f)¶
Read response from input file, decompress it, and parse it.
- request(host, handler, request_body, verbose=False, binary=False, compressed=False, acceptCompressedResponse=False)¶
Issue a Pickle-RPC request.
- send_content(connection, request_body, binary=False, compressed=False, acceptCompressedResponse=False)¶
Send content.
- send_host(connection, host)¶
Send host header.
- send_request(connection, handler, request_body)¶
Send request.
- send_user_agent(connection)¶
Send user-agent header.
- user_agent = 'PickleRPC/1 (Webware for Python)'¶
- class MiscUtils.PickleRPC.SafeUnpickler¶
Bases:
object
Safe unpickler.
For security reasons, we don’t want to allow just anyone to unpickle anything. That can cause arbitrary code to be executed. So this SafeUnpickler base class is used to control what can be unpickled. By default it doesn’t let you unpickle any class instances at all, but you can create subclass that overrides allowedGlobals().
Note that the PickleRPCServlet class in the Webware package is derived from this class and uses its load() and loads() methods to do all unpickling.
- allowedGlobals()¶
Allowed class names.
Must return a list of (moduleName, klassName) tuples for all classes that you want to allow to be unpickled.
Example:
return [('datetime', 'date')]
Allows datetime.date instances to be unpickled.
- findGlobal(module, klass)¶
Find class name.
- load(file)¶
Unpickle a file.
- loads(s)¶
Unpickle a string.
- class MiscUtils.PickleRPC.Server(uri, transport=None, verbose=False, binary=True, compressRequest=True, acceptCompressedResponse=True)¶
Bases:
object
uri [,options] -> a logical connection to an XML-RPC server
uri is the connection point on the server, given as scheme://host/target.
The standard implementation always supports the “http” scheme. If SSL socket support is available, it also supports “https”.
If the target part and the slash preceding it are both omitted, “/PickleRPC” is assumed.
See the module doc string for more information.
- __init__(uri, transport=None, verbose=False, binary=True, compressRequest=True, acceptCompressedResponse=True)¶
Establish a “logical” server connection.
- class MiscUtils.PickleRPC.Transport¶
Bases:
SafeUnpickler
Handle an HTTP transaction to a Pickle-RPC server.
- allowedGlobals()¶
Allowed class names.
Must return a list of (moduleName, klassName) tuples for all classes that you want to allow to be unpickled.
Example:
return [('datetime', 'date')]
Allows datetime.date instances to be unpickled.
- findGlobal(module, klass)¶
Find class name.
- load(file)¶
Unpickle a file.
- loads(s)¶
Unpickle a string.
- make_connection(host, port=None)¶
Create an HTTP connection object from a host descriptor.
- parse_response(f)¶
Read response from input file and parse it.
- parse_response_gzip(f)¶
Read response from input file, decompress it, and parse it.
- request(host, handler, request_body, verbose=False, binary=False, compressed=False, acceptCompressedResponse=False)¶
Issue a Pickle-RPC request.
- send_content(connection, request_body, binary=False, compressed=False, acceptCompressedResponse=False)¶
Send content.
- send_host(connection, host)¶
Send host header.
- send_request(connection, handler, request_body)¶
Send request.
- send_user_agent(connection)¶
Send user-agent header.
- user_agent = 'PickleRPC/1 (Webware for Python)'¶