ServerProxy Objects¶

AServerProxy instance has a method corresponding to each remoteprocedure call accepted by the XML-RPC server. Calling the method performs anRPC, dispatched by both name and argument signature (e.g. the same method namecan be overloaded with multiple argument signatures). The RPC finishes byreturning a value, which may be either returned data in a conformant type or aFault orProtocolError object indicating an error.

Servers that support the XML introspection API support some common methodsgrouped under the reservedsystem attribute:

ServerProxy.system.listMethods()¶

This method returns a list of strings, one for each (non-system) methodsupported by the XML-RPC server.

ServerProxy.system.methodSignature(name)¶

This method takes one parameter, the name of a method implemented by the XML-RPCserver. It returns an array of possible signatures for this method. A signatureis an array of types. The first of these types is the return type of the method,the rest are parameters.

Because multiple signatures (ie. overloading) is permitted, this method returnsa list of signatures rather than a singleton.

Signatures themselves are restricted to the top level parameters expected by amethod. For instance if a method expects one array of structs as a parameter,and it returns a string, its signature is simply “string, array”. If it expectsthree integers and returns a string, its signature is “string, int, int, int”.

If no signature is defined for the method, a non-array value is returned. InPython this means that the type of the returned value will be something otherthan list.

ServerProxy.system.methodHelp(name)¶

This method takes one parameter, the name of a method implemented by the XML-RPCserver. It returns a documentation string describing the use of that method. Ifno such string is available, an empty string is returned. The documentationstring may contain HTML markup.

A working example follows. The server code:

fromxmlrpc.serverimportSimpleXMLRPCServerdefis_even(n):returnn%2==0server=SimpleXMLRPCServer(("localhost",8000))print("Listening on port 8000...")server.register_function(is_even,"is_even")server.serve_forever()

The client code for the preceding server:

importxmlrpc.clientwithxmlrpc.client.ServerProxy("http://localhost:8000/")asproxy:print("3 is even:%s"%str(proxy.is_even(3)))print("100 is even:%s"%str(proxy.is_even(100)))

DateTime Objects¶

classxmlrpc.client.DateTime¶

This class may be initialized with seconds since the epoch, a timetuple, an ISO 8601 time/date string, or adatetime.datetimeinstance. It has the following methods, supported mainly for internaluse by the marshalling/unmarshalling code:

decode(string)¶

Accept a string as the instance’s new time value.

encode(out)¶

Write the XML-RPC encoding of thisDateTime item to theout streamobject.

It also supports certain of Python’s built-in operators throughrichcomparison and__repr__()methods.

A working example follows. The server code:

importdatetimefromxmlrpc.serverimportSimpleXMLRPCServerimportxmlrpc.clientdeftoday():today=datetime.datetime.today()returnxmlrpc.client.DateTime(today)server=SimpleXMLRPCServer(("localhost",8000))print("Listening on port 8000...")server.register_function(today,"today")server.serve_forever()

The client code for the preceding server:

importxmlrpc.clientimportdatetimeproxy=xmlrpc.client.ServerProxy("http://localhost:8000/")today=proxy.today()# convert the ISO8601 string to a datetime objectconverted=datetime.datetime.strptime(today.value,"%Y%m%dT%H:%M:%S")print("Today:%s"%converted.strftime("%d.%m.%Y, %H:%M"))

Binary Objects¶

classxmlrpc.client.Binary¶

This class may be initialized from bytes data (which may include NULs). Theprimary access to the content of aBinary object is provided by anattribute:

data¶

The binary data encapsulated by theBinary instance. The data isprovided as abytes object.

Binary objects have the following methods, supported mainly forinternal use by the marshalling/unmarshalling code:

decode(bytes)¶

Accept a base64bytes object and decode it as the instance’s new data.

encode(out)¶

Write the XML-RPC base 64 encoding of this binary item to theout stream object.

The encoded data will have newlines every 76 characters as perRFC 2045 section 6.8,which was the de facto standard base64 specification when theXML-RPC spec was written.

It also supports certain of Python’s built-in operators through__eq__() and__ne__() methods.

Example usage of the binary objects. We’re going to transfer an image overXMLRPC:

fromxmlrpc.serverimportSimpleXMLRPCServerimportxmlrpc.clientdefpython_logo():withopen("python_logo.jpg","rb")ashandle:returnxmlrpc.client.Binary(handle.read())server=SimpleXMLRPCServer(("localhost",8000))print("Listening on port 8000...")server.register_function(python_logo,'python_logo')server.serve_forever()

The client gets the image and saves it to a file:

importxmlrpc.clientproxy=xmlrpc.client.ServerProxy("http://localhost:8000/")withopen("fetched_python_logo.jpg","wb")ashandle:handle.write(proxy.python_logo().data)

Fault Objects¶

classxmlrpc.client.Fault¶

AFault object encapsulates the content of an XML-RPC fault tag. Faultobjects have the following attributes:

faultCode¶

An int indicating the fault type.

faultString¶

A string containing a diagnostic message associated with the fault.

In the following example we’re going to intentionally cause aFault byreturning a complex type object. The server code:

fromxmlrpc.serverimportSimpleXMLRPCServer# A marshalling error is going to occur because we're returning a# complex numberdefadd(x,y):returnx+y+0jserver=SimpleXMLRPCServer(("localhost",8000))print("Listening on port 8000...")server.register_function(add,'add')server.serve_forever()

The client code for the preceding server:

importxmlrpc.clientproxy=xmlrpc.client.ServerProxy("http://localhost:8000/")try:proxy.add(2,5)exceptxmlrpc.client.Faultaserr:print("A fault occurred")print("Fault code:%d"%err.faultCode)print("Fault string:%s"%err.faultString)

ProtocolError Objects¶

classxmlrpc.client.ProtocolError¶

AProtocolError object describes a protocol error in the underlyingtransport layer (such as a 404 ‘not found’ error if the server named by the URIdoes not exist). It has the following attributes:

url¶

The URI or URL that triggered the error.

errcode¶

The error code.

errmsg¶

The error message or diagnostic string.

headers¶

A dict containing the headers of the HTTP/HTTPS request that triggered theerror.

In the following example we’re going to intentionally cause aProtocolErrorby providing an invalid URI:

importxmlrpc.client# create a ServerProxy with a URI that doesn't respond to XMLRPC requestsproxy=xmlrpc.client.ServerProxy("http://google.com/")try:proxy.some_method()exceptxmlrpc.client.ProtocolErroraserr:print("A protocol error occurred")print("URL:%s"%err.url)print("HTTP/HTTPS headers:%s"%err.headers)print("Error code:%d"%err.errcode)print("Error message:%s"%err.errmsg)

MultiCall Objects¶

TheMultiCall object provides a way to encapsulate multiple calls to aremote server into a single request[1].

classxmlrpc.client.MultiCall(server)¶

Create an object used to boxcar method calls.server is the eventual target ofthe call. Calls can be made to the result object, but they will immediatelyreturnNone, and only store the call name and parameters in theMultiCall object. Calling the object itself causes all stored calls tobe transmitted as a singlesystem.multicall request. The result of this callis agenerator; iterating over this generator yields the individualresults.

A usage example of this class follows. The server code:

fromxmlrpc.serverimportSimpleXMLRPCServerdefadd(x,y):returnx+ydefsubtract(x,y):returnx-ydefmultiply(x,y):returnx*ydefdivide(x,y):returnx//y# A simple server with simple arithmetic functionsserver=SimpleXMLRPCServer(("localhost",8000))print("Listening on port 8000...")server.register_multicall_functions()server.register_function(add,'add')server.register_function(subtract,'subtract')server.register_function(multiply,'multiply')server.register_function(divide,'divide')server.serve_forever()

The client code for the preceding server:

importxmlrpc.clientproxy=xmlrpc.client.ServerProxy("http://localhost:8000/")multicall=xmlrpc.client.MultiCall(proxy)multicall.add(7,3)multicall.subtract(7,3)multicall.multiply(7,3)multicall.divide(7,3)result=multicall()print("7+3=%d, 7-3=%d, 7*3=%d, 7//3=%d"%tuple(result))

Convenience Functions¶

xmlrpc.client.dumps(params,methodname=None,methodresponse=None,encoding=None,allow_none=False)¶

Convertparams into an XML-RPC request, or into a response ifmethodresponseis true.params can be either a tuple of arguments or an instance of theFault exception class. Ifmethodresponse is true, only a single valuecan be returned, meaning thatparams must be of length 1.encoding, ifsupplied, is the encoding to use in the generated XML; the default is UTF-8.Python’sNone value cannot be used in standard XML-RPC; to allow usingit via an extension, provide a true value forallow_none.

xmlrpc.client.loads(data,use_datetime=False,use_builtin_types=False)¶

Convert an XML-RPC request or response into Python objects, a(params,methodname).params is a tuple of argument;methodname is a string, orNone if no method name is present in the packet. If the XML-RPC packetrepresents a fault condition, this function will raise aFault exception.Theuse_builtin_types flag can be used to cause date/time values to bepresented asdatetime.datetime objects and binary data to bepresented asbytes objects; this flag is false by default.

The obsoleteuse_datetime flag is similar touse_builtin_types but itapplies only to date/time values.

Changed in version 3.3:Theuse_builtin_types flag was added.

Example of Client Usage¶

# simple test program (from the XML-RPC specification)fromxmlrpc.clientimportServerProxy,Error# server = ServerProxy("http://localhost:8000") # local serverwithServerProxy("http://betty.userland.com")asproxy:print(proxy)try:print(proxy.examples.getStateName(41))exceptErrorasv:print("ERROR",v)

To access an XML-RPC server through a HTTP proxy, you need to define a customtransport. The following example shows how:

importhttp.clientimportxmlrpc.clientclassProxiedTransport(xmlrpc.client.Transport):defset_proxy(self,host,port=None,headers=None):self.proxy=host,portself.proxy_headers=headersdefmake_connection(self,host):connection=http.client.HTTPConnection(*self.proxy)connection.set_tunnel(host,headers=self.proxy_headers)self._connection=host,connectionreturnconnectiontransport=ProxiedTransport()transport.set_proxy('proxy-server',8080)server=xmlrpc.client.ServerProxy('http://betty.userland.com',transport=transport)print(server.examples.getStateName(41))

Example of Client and Server Usage¶

SeeSimpleXMLRPCServer Example.

Footnotes

This approach has been first presented ina discussion on xmlrpc.com.