 |  |  | Python Library Reference |  |  |  |
| | | Python Library Reference | | | |
New in version 2.2.
XML-RPC is a Remote Procedure Call method that uses XML passed viaHTTP as a transport. With it, a client can call methods withparameters on a remote server (the server is named by a URI) and get backstructured data. This module supports writing XML-RPC client code; ithandles all the details of translating between conformable Pythonobjects and XML on the wire.
| uri[, transport[, encoding[, verbose[, allow_none[, use_datetime]]]]]) |
None will be translated into XML; thedefault behaviour is forNone to raise aTypeError.This is a commonly-used extension to the XML-RPC specification, but isn'tsupported by all clients and servers; seehttp://ontosys.com/xml-rpc/extensions.php for a description. Theuse_datetime flag can be used to cause date/time values to bepresented asdatetime.datetime objects; this is falseby default.datetime.datetime,datetime.date anddatetime.timeobjects may be passed to calls.datetime.date objectsare converted with a time of ``00:00:00''.datetime.time objects are converted using today's date.Both the HTTP and HTTPS transports support the URL syntax extension forHTTP Basic Authentication:http://user:pass@host:port/path. Theuser:pass portion will be base64-encoded as an HTTP `Authorization'header, and sent to the remote server as part of the connection processwhen invoking an XML-RPC method. You only need to use this if theremote server requires a Basic Authentication user and password.
The returned instance is a proxy object with methods that can be usedto invoke corresponding RPC calls on the remote server. If the remoteserver supports the introspection API, the proxy can also be used to querythe remote server for the methods it supports (service discovery) andfetch other server-associated metadata.
ServerProxy instance methods take Python basic types and objects as arguments and return Python basic types and classes. Types that areconformable (e.g. that can be marshalled through XML), include thefollowing (and except where noted, they are unmarshalled as the samePython type):
| Name | Meaning |
|---|---|
| boolean | TheTrue andFalse constants |
| integers | Pass in directly |
| floating-point numbers | Pass in directly |
| strings | Pass in directly |
| arrays | Any Python sequence type containing conformable elements. Arrays are returned as lists |
| structures | A Python dictionary. Keys must be strings, values may be any conformable type. |
| dates | in seconds since the epoch (pass in an instance of theDateTime class) or adatetime.datetime,datetime.date ordatetime.time instance |
| binary data | pass in an instance of theBinary wrapper class |
This is the full set of data types supported by XML-RPC. Method callsmay also raise a specialFault instance, used to signalXML-RPC server errors, orProtocolError used to signal anerror in the HTTP/HTTPS transport layer. BothFault andProtocolError derive from a base class calledError. Note that even though starting with Python 2.2 youcan subclass builtin types, the xmlrpclib module currently does notmarshal instances of such subclasses.
When passing strings, characters special to XML such as "<",">", and "&" will be automatically escaped. However, it'sthe caller's responsibility to ensure that the string is free ofcharacters that aren't allowed in XML, such as the control characterswith ASCII values between 0 and 31 (except, of course, tab, newline andcarriage return); failing to do this will result inan XML-RPC request that isn't well-formed XML. If you have to passarbitrary strings via XML-RPC, use theBinary wrapper classdescribed below.
Server is retained as an alias forServerProxy for backwardscompatibility. New code should useServerProxy.
Changed in version 2.5:Theuse_datetime flag was added.
See Also:
| | | Python Library Reference | | | |