Source code:Lib/xmlrpc/client.py
XML-RPC is a Remote Procedure Call method that uses XML passed via HTTP as atransport. With it, a client can call methods with parameters on a remoteserver (the server is named by a URI) and get back structured data. This modulesupports writing XML-RPC client code; it handles all the details of translatingbetween conformable Python objects and XML on the wire.
Warning
Thexmlrpc.client module is not secure against maliciouslyconstructed data. If you need to parse untrusted or unauthenticated data seeXML vulnerabilities.
Warning
In the case of https URIs,xmlrpc.client does not do any verificationof the server’s certificate.
Changed in version 3.3:Theuse_builtin_types flag was added.
AServerProxy instance is an object that manages communication with aremote XML-RPC server. The required first argument is a URI (Uniform ResourceIndicator), and will normally be the URL of the server. The optional secondargument is a transport factory instance; by default it is an internalSafeTransport instance for https: URLs and an internal HTTPTransport instance otherwise. The optional third argument is anencoding, by default UTF-8. The optional fourth argument is a debugging flag.Ifallow_none is true, the Python constantNone will be translated intoXML; the default behaviour is forNone to raise aTypeError. This isa commonly-used extension to the XML-RPC specification, but isn’t supported byall clients and servers; seehttp://ontosys.com/xml-rpc/extensions.php for adescription. Theuse_builtin_types flag can be used to cause date/time valuesto be presented asdatetime.datetime objects and binary data to bepresented asbytes objects; this flag is false by default.datetime.datetime andbytes objects may be passed to calls.
The obsoleteuse_datetime flag is similar touse_builtin_types but itapplies only to date/time values.
Both the HTTP and HTTPS transports support the URL syntax extension for HTTPBasic Authentication:http://user:pass@host:port/path. Theuser:passportion will be base64-encoded as an HTTP ‘Authorization’ header, and sent tothe remote server as part of the connection process when invoking an XML-RPCmethod. You only need to use this if the remote server requires a BasicAuthentication user and password.
The returned instance is a proxy object with methods that can be used to invokecorresponding RPC calls on the remote server. If the remote server supports theintrospection API, the proxy can also be used to query the remote server for themethods it supports (service discovery) and fetch other server-associatedmetadata.
ServerProxy instance methods take Python basic types and objects asarguments and return Python basic types and classes. Types that are conformable(e.g. that can be marshalled through XML), include the following (and exceptwhere noted, they are unmarshalled as the same Python type):
| Name | Meaning |
|---|---|
| boolean | TheTrue andFalseconstants |
| integers | Pass in directly |
| floating-pointnumbers | Pass in directly |
| strings | Pass in directly |
| arrays | Any Python sequence type containingconformable elements. Arrays are returnedas lists |
| structures | A Python dictionary. Keys must be strings,values may be any conformable type. Objectsof user-defined classes can be passed in;only their__dict__ attribute istransmitted. |
| dates | In seconds since the epoch. Pass in aninstance of theDateTime class oradatetime.datetime instance. |
| binarydata | Pass in an instance of theBinarywrapper class or abytes instance. |
This is the full set of data types supported by XML-RPC. Method calls may alsoraise a specialFault instance, used to signal XML-RPC server errors, orProtocolError used to signal an error in the HTTP/HTTPS transport layer.BothFault andProtocolError derive from a base class calledError. Note that the xmlrpc client module currently does not marshalinstances of subclasses of built-in types.
When passing strings, characters special to XML such as<,>, and&will be automatically escaped. However, it’s the caller’s responsibility toensure that the string is free of characters that aren’t allowed in XML, such asthe control characters with ASCII values between 0 and 31 (except, of course,tab, newline and carriage return); failing to do this will result in an XML-RPCrequest that isn’t well-formed XML. If you have to pass arbitrary bytesvia XML-RPC, use thebytes class or the class:Binary wrapper classdescribed below.
Server is retained as an alias forServerProxy for backwardscompatibility. New code should useServerProxy.
See also
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:
This method returns a list of strings, one for each (non-system) methodsupported by the XML-RPC server.
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.
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.clientproxy=xmlrpc.client.ServerProxy("http://localhost:8000/")print("3 is even: %s"%str(proxy.is_even(3)))print("100 is even: %s"%str(proxy.is_even(100)))
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:
Accept a string as the instance’s new time value.
Write the XML-RPC encoding of thisDateTime item to theout streamobject.
It also supports certain of Python’s built-in operators through rich comparisonand__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"))
This class may be initialized from bytes data (which may include NULs). Theprimary access to the content of aBinary object is provided by anattribute:
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:
Write the XML-RPC base 64 encoding of this binary item to the out 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)
AFault object encapsulates the content of an XML-RPC fault tag. Faultobjects have the following attributes:
A string indicating the fault type.
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)
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:
The URI or URL that triggered the error.
The error code.
The error message or diagnostic string.
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 an 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)
TheMultiCall object provides a way to encapsulate multiple calls to aremote server into a single request[1].
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))
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.
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.
# simple test program (from the XML-RPC specification)fromxmlrpc.clientimportServerProxy,Error# server = ServerProxy("http://localhost:8000") # local serverserver=ServerProxy("http://betty.userland.com")print(server)try:print(server.examples.getStateName(41))exceptErrorasv:print("ERROR",v)
To access an XML-RPC server through a proxy, you need to define a customtransport. The following example shows how:
importxmlrpc.client,http.clientclassProxiedTransport(xmlrpc.client.Transport):defset_proxy(self,proxy):self.proxy=proxydefmake_connection(self,host):self.realhost=hosth=http.client.HTTP(self.proxy)returnhdefsend_request(self,connection,handler,request_body):connection.putrequest("POST",'http://%s%s'%(self.realhost,handler))defsend_host(self,connection,host):connection.putheader('Host',self.realhost)p=ProxiedTransport()p.set_proxy('proxy-server:8080')server=xmlrpc.client.Server('http://time.xmlrpc.com/RPC2',transport=p)print(server.currentTime.getCurrentTime())
SeeSimpleXMLRPCServer Example.
Footnotes
| [1] | This approach has been first presented ina discussion on xmlrpc.com. |
21.25.xmlrpc — XMLRPC server and client modules
21.27.xmlrpc.server — Basic XML-RPC servers
Enter search terms or a module, class or function name.
