Lib/xmlrpclib.py

   1 #
   2 # XML-RPC CLIENT LIBRARY
   3 # $Id$
   4 #
   5 # an XML-RPC client interface for Python.
   6 #
   7 # the marshalling and response parser code can also be used to
   8 # implement XML-RPC servers.
   9 #
  10 # Notes:
  11 # this version is designed to work with Python 1.5.2 or newer.
  12 # unicode encoding support requires at least Python 1.6.
  13 # experimental HTTPS requires Python 2.0 built with SSL sockets.
  14 # expat parser support requires Python 2.0 with pyexpat support.
  15 #
  16 # History:
  17 # 1999-01-14 fl  Created
  18 # 1999-01-15 fl  Changed dateTime to use localtime
  19 # 1999-01-16 fl  Added Binary/base64 element, default to RPC2 service
  20 # 1999-01-19 fl  Fixed array data element (from Skip Montanaro)
  21 # 1999-01-21 fl  Fixed dateTime constructor, etc.
  22 # 1999-02-02 fl  Added fault handling, handle empty sequences, etc.
  23 # 1999-02-10 fl  Fixed problem with empty responses (from Skip Montanaro)
  24 # 1999-06-20 fl  Speed improvements, pluggable parsers/transports (0.9.8)
  25 # 2000-11-28 fl  Changed boolean to check the truth value of its argument
  26 # 2001-02-24 fl  Added encoding/Unicode/SafeTransport patches
  27 # 2001-02-26 fl  Added compare support to wrappers (0.9.9/1.0b1)
  28 # 2001-03-28 fl  Make sure response tuple is a singleton
  29 # 2001-03-29 fl  Don't require empty params element (from Nicholas Riley)
  30 # 2001-06-10 fl  Folded in _xmlrpclib accelerator support (1.0b2)
  31 # 2001-08-20 fl  Base xmlrpclib.Error on built-in Exception (from Paul Prescod)
  32 # 2001-09-03 fl  Allow Transport subclass to override getparser
  33 # 2001-09-10 fl  Lazy import of urllib, cgi, xmllib (20x import speedup)
  34 # 2001-10-01 fl  Remove containers from memo cache when done with them
  35 # 2001-10-01 fl  Use faster escape method (80% dumps speedup)
  36 # 2001-10-02 fl  More dumps microtuning
  37 # 2001-10-04 fl  Make sure import expat gets a parser (from Guido van Rossum)
  38 # 2001-10-10 sm  Allow long ints to be passed as ints if they don't overflow
  39 # 2001-10-17 sm  Test for int and long overflow (allows use on 64-bit systems)
  40 # 2001-11-12 fl  Use repr() to marshal doubles (from Paul Felix)
  41 # 2002-03-17 fl  Avoid buffered read when possible (from James Rucker)
  42 # 2002-04-07 fl  Added pythondoc comments
  43 # 2002-04-16 fl  Added __str__ methods to datetime/binary wrappers
  44 # 2002-05-15 fl  Added error constants (from Andrew Kuchling)
  45 # 2002-06-27 fl  Merged with Python CVS version
  46 # 2002-10-22 fl  Added basic authentication (based on code from Phillip Eby)
  47 #
  48 # Copyright (c) 1999-2002 by Secret Labs AB.
  49 # Copyright (c) 1999-2002 by Fredrik Lundh.
  50 #
  51 # info@pythonware.com
  52 # http://www.pythonware.com
  53 #
  54 # --------------------------------------------------------------------
  55 # The XML-RPC client interface is
  56 #
  57 # Copyright (c) 1999-2002 by Secret Labs AB
  58 # Copyright (c) 1999-2002 by Fredrik Lundh
  59 #
  60 # By obtaining, using, and/or copying this software and/or its
  61 # associated documentation, you agree that you have read, understood,
  62 # and will comply with the following terms and conditions:
  63 #
  64 # Permission to use, copy, modify, and distribute this software and
  65 # its associated documentation for any purpose and without fee is
  66 # hereby granted, provided that the above copyright notice appears in
  67 # all copies, and that both that copyright notice and this permission
  68 # notice appear in supporting documentation, and that the name of
  69 # Secret Labs AB or the author not be used in advertising or publicity
  70 # pertaining to distribution of the software without specific, written
  71 # prior permission.
  72 #
  73 # SECRET LABS AB AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD
  74 # TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANT-
  75 # ABILITY AND FITNESS.  IN NO EVENT SHALL SECRET LABS AB OR THE AUTHOR
  76 # BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY
  77 # DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
  78 # WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
  79 # ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
  80 # OF THIS SOFTWARE.
  81 # --------------------------------------------------------------------
  82
  83 #
  84 # things to look into some day:
  85
  86 # TODO: sort out True/False/boolean issues for Python 2.3
  87
  88 """
  89 An XML-RPC client interface for Python.
  90
  91 The marshalling and response parser code can also be used to
  92 implement XML-RPC servers.
  93
  94 Exported exceptions:
  95
  96   Error          Base class for client errors
  97   ProtocolError  Indicates an HTTP protocol error
  98   ResponseError  Indicates a broken response package
  99   Fault          Indicates an XML-RPC fault package
 100
 101 Exported classes:
 102
 103   ServerProxy    Represents a logical connection to an XML-RPC server
 104
 105   Boolean        boolean wrapper to generate a "boolean" XML-RPC value
 106   DateTime       dateTime wrapper for an ISO 8601 string or time tuple or
 107                  localtime integer value to generate a "dateTime.iso8601"
 108                  XML-RPC value
 109   Binary         binary data wrapper
 110
 111   SlowParser     Slow but safe standard parser (based on xmllib)
 112   Marshaller     Generate an XML-RPC params chunk from a Python data structure
 113   Unmarshaller   Unmarshal an XML-RPC response from incoming XML event message
 114   Transport      Handles an HTTP transaction to an XML-RPC server
 115   SafeTransport  Handles an HTTPS transaction to an XML-RPC server
 116
 117 Exported constants:
 118
 119   True
 120   False
 121
 122 Exported functions:
 123
 124   boolean        Convert any Python value to an XML-RPC boolean
 125   getparser      Create instance of the fastest available parser & attach
 126                  to an unmarshalling object
 127   dumps          Convert an argument tuple or a Fault instance to an XML-RPC
 128                  request (or response, if the methodresponse option is used).
 129   loads          Convert an XML-RPC packet to unmarshalled data plus a method
 130                  name (None if not present).
 131 """
 132
 133 import re, string, time, operator
 134
 135 from types import *
 136
 137 # --------------------------------------------------------------------
 138 # Internal stuff
 139
 140 try:
 141     unicode
 142 except NameError:
 143     unicode = None # unicode support not available
 144
 145 try:
 146     _bool_is_builtin = False.__class__.__name__ == "bool"
 147 except NameError:
 148     _bool_is_builtin = 0
 149
 150 def _decode(data, encoding, is8bit=re.compile("[\x80-\xff]").search):
 151     # decode non-ascii string (if possible)
 152     if unicode and encoding and is8bit(data):
 153         data = unicode(data, encoding)
 154     return data
 155
 156 def escape(s, replace=string.replace):
 157     s = replace(s, "&", "&amp;")
 158     s = replace(s, "<", "&lt;")
 159     return replace(s, ">", "&gt;",)
 160
 161 if unicode:
 162     def _stringify(string):
 163         # convert to 7-bit ascii if possible
 164         try:
 165             return str(string)
 166         except UnicodeError:
 167             return string
 168 else:
 169     def _stringify(string):
 170         return string
 171
 172 __version__ = "1.0.1"
 173
 174 # xmlrpc integer limits
 175 MAXINT =  2L**31-1
 176 MININT = -2L**31
 177
 178 # --------------------------------------------------------------------
 179 # Error constants (from Dan Libby's specification at
 180 # http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php)
 181
 182 # Ranges of errors
 183 PARSE_ERROR       = -32700
 184 SERVER_ERROR      = -32600
 185 APPLICATION_ERROR = -32500
 186 SYSTEM_ERROR      = -32400
 187 TRANSPORT_ERROR   = -32300
 188
 189 # Specific errors
 190 NOT_WELLFORMED_ERROR  = -32700
 191 UNSUPPORTED_ENCODING  = -32701
 192 INVALID_ENCODING_CHAR = -32702
 193 INVALID_XMLRPC        = -32600
 194 METHOD_NOT_FOUND      = -32601
 195 INVALID_METHOD_PARAMS = -32602
 196 INTERNAL_ERROR        = -32603
 197
 198 # --------------------------------------------------------------------
 199 # Exceptions
 200
 201 ##
 202 # Base class for all kinds of client-side errors.
 203
 204 class Error(Exception):
 205     """Base class for client errors."""
 206     def __str__(self):
 207         return repr(self)
 208
 209 ##
 210 # Indicates an HTTP-level protocol error.  This is raised by the HTTP
 211 # transport layer, if the server returns an error code other than 200
 212 # (OK).
 213 #
 214 # @param url The target URL.
 215 # @param errcode The HTTP error code.
 216 # @param errmsg The HTTP error message.
 217 # @param headers The HTTP header dictionary.
 218
 219 class ProtocolError(Error):
 220     """Indicates an HTTP protocol error."""
 221     def __init__(self, url, errcode, errmsg, headers):
 222         Error.__init__(self)
 223         self.url = url
 224         self.errcode = errcode
 225         self.errmsg = errmsg
 226         self.headers = headers
 227     def __repr__(self):
 228         return (
 229             "<ProtocolError for %s: %s %s>" %
 230             (self.url, self.errcode, self.errmsg)
 231             )
 232
 233 ##
 234 # Indicates a broken XML-RPC response package.  This exception is
 235 # raised by the unmarshalling layer, if the XML-RPC response is
 236 # malformed.
 237
 238 class ResponseError(Error):
 239     """Indicates a broken response package."""
 240     pass
 241
 242 ##
 243 # Indicates an XML-RPC fault response package.  This exception is
 244 # raised by the unmarshalling layer, if the XML-RPC response contains
 245 # a fault string.  This exception can also used as a class, to
 246 # generate a fault XML-RPC message.
 247 #
 248 # @param faultCode The XML-RPC fault code.
 249 # @param faultString The XML-RPC fault string.
 250
 251 class Fault(Error):
 252     """Indicates an XML-RPC fault package."""
 253     def __init__(self, faultCode, faultString, **extra):
 254         Error.__init__(self)
 255         self.faultCode = faultCode
 256         self.faultString = faultString
 257     def __repr__(self):
 258         return (
 259             "<Fault %s: %s>" %
 260             (self.faultCode, repr(self.faultString))
 261             )
 262
 263 # --------------------------------------------------------------------
 264 # Special values
 265
 266 ##
 267 # Wrapper for XML-RPC boolean values.  Use the xmlrpclib.True and
 268 # xmlrpclib.False constants, or the xmlrpclib.boolean() function, to
 269 # generate boolean XML-RPC values.
 270 #
 271 # @param value A boolean value.  Any true value is interpreted as True,
 272 #              all other values are interpreted as False.
 273
 274 if _bool_is_builtin:
 275     boolean = Boolean = bool
 276     # to avoid breaking code which references xmlrpclib.{True,False}
 277     True, False = True, False
 278 else:
 279     class Boolean:
 280         """Boolean-value wrapper.
 281
 282         Use True or False to generate a "boolean" XML-RPC value.
 283         """
 284
 285         def __init__(self, value = 0):
 286             self.value = operator.truth(value)
 287
 288         def encode(self, out):
 289             out.write("<value><boolean>%d</boolean></value>\n" % self.value)
 290
 291         def __cmp__(self, other):
 292             if isinstance(other, Boolean):
 293                 other = other.value
 294             return cmp(self.value, other)
 295
 296         def __repr__(self):
 297             if self.value:
 298                 return "<Boolean True at %x>" % id(self)
 299             else:
 300                 return "<Boolean False at %x>" % id(self)
 301
 302         def __int__(self):
 303             return self.value
 304
 305         def __nonzero__(self):
 306             return self.value
 307
 308     True, False = Boolean(1), Boolean(0)
 309
 310     ##
 311     # Map true or false value to XML-RPC boolean values.
 312     #
 313     # @def boolean(value)
 314     # @param value A boolean value.  Any true value is mapped to True,
 315     #              all other values are mapped to False.
 316     # @return xmlrpclib.True or xmlrpclib.False.
 317     # @see Boolean
 318     # @see True
 319     # @see False
 320
 321     def boolean(value, _truefalse=(False, True)):
 322         """Convert any Python value to XML-RPC 'boolean'."""
 323         return _truefalse[operator.truth(value)]
 324
 325 ##
 326 # Wrapper for XML-RPC DateTime values.  This converts a time value to
 327 # the format used by XML-RPC.
 328 # <p>
 329 # The value can be given as a string in the format
 330 # "yyyymmddThh:mm:ss", as a 9-item time tuple (as returned by
 331 # time.localtime()), or an integer value (as returned by time.time()).
 332 # The wrapper uses time.localtime() to convert an integer to a time
 333 # tuple.
 334 #
 335 # @param value The time, given as an ISO 8601 string, a time
 336 #              tuple, or a integer time value.
 337
 338 class DateTime:
 339     """DateTime wrapper for an ISO 8601 string or time tuple or
 340     localtime integer value to generate 'dateTime.iso8601' XML-RPC
 341     value.
 342     """
 343
 344     def __init__(self, value=0):
 345         if not isinstance(value, StringType):
 346             if not isinstance(value, TupleType):
 347                 if value == 0:
 348                     value = time.time()
 349                 value = time.localtime(value)
 350             value = time.strftime("%Y%m%dT%H:%M:%S", value)
 351         self.value = value
 352
 353     def __cmp__(self, other):
 354         if isinstance(other, DateTime):
 355             other = other.value
 356         return cmp(self.value, other)
 357
 358     ##
 359     # Get date/time value.
 360     #
 361     # @return Date/time value, as an ISO 8601 string.
 362
 363     def __str__(self):
 364         return self.value
 365
 366     def __repr__(self):
 367         return "<DateTime %s at %x>" % (repr(self.value), id(self))
 368
 369     def decode(self, data):
 370         self.value = string.strip(data)
 371
 372     def encode(self, out):
 373         out.write("<value><dateTime.iso8601>")
 374         out.write(self.value)
 375         out.write("</dateTime.iso8601></value>\n")
 376
 377 def _datetime(data):
 378     # decode xml element contents into a DateTime structure.
 379     value = DateTime()
 380     value.decode(data)
 381     return value
 382
 383 ##
 384 # Wrapper for binary data.  This can be used to transport any kind
 385 # of binary data over XML-RPC, using BASE64 encoding.
 386 #
 387 # @param data An 8-bit string containing arbitrary data.
 388
 389 import base64
 390 try:
 391     import cStringIO as StringIO
 392 except ImportError:
 393     import StringIO
 394
 395 class Binary:
 396     """Wrapper for binary data."""
 397
 398     def __init__(self, data=None):
 399         self.data = data
 400
 401     ##
 402     # Get buffer contents.
 403     #
 404     # @return Buffer contents, as an 8-bit string.
 405
 406     def __str__(self):
 407         return self.data or ""
 408
 409     def __cmp__(self, other):
 410         if isinstance(other, Binary):
 411             other = other.data
 412         return cmp(self.data, other)
 413
 414     def decode(self, data):
 415         self.data = base64.decodestring(data)
 416
 417     def encode(self, out):
 418         out.write("<value><base64>\n")
 419         base64.encode(StringIO.StringIO(self.data), out)
 420         out.write("</base64></value>\n")
 421
 422 def _binary(data):
 423     # decode xml element contents into a Binary structure
 424     value = Binary()
 425     value.decode(data)
 426     return value
 427
 428 WRAPPERS = (DateTime, Binary)
 429 if not _bool_is_builtin:
 430     WRAPPERS = WRAPPERS + (Boolean,)
 431
 432 # --------------------------------------------------------------------
 433 # XML parsers
 434
 435 try:
 436     # optional xmlrpclib accelerator.  for more information on this
 437     # component, contact info@pythonware.com
 438     import _xmlrpclib
 439     FastParser = _xmlrpclib.Parser
 440     FastUnmarshaller = _xmlrpclib.Unmarshaller
 441 except (AttributeError, ImportError):
 442     FastParser = FastUnmarshaller = None
 443
 444 try:
 445     import _xmlrpclib
 446     FastMarshaller = _xmlrpclib.Marshaller
 447 except (AttributeError, ImportError):
 448     FastMarshaller = None
 449
 450 #
 451 # the SGMLOP parser is about 15x faster than Python's builtin
 452 # XML parser.  SGMLOP sources can be downloaded from:
 453 #
 454 #     http://www.pythonware.com/products/xml/sgmlop.htm
 455 #
 456
 457 try:
 458     import sgmlop
 459     if not hasattr(sgmlop, "XMLParser"):
 460         raise ImportError
 461 except ImportError:
 462     SgmlopParser = None # sgmlop accelerator not available
 463 else:
 464     class SgmlopParser:
 465         def __init__(self, target):
 466
 467             # setup callbacks
 468             self.finish_starttag = target.start
 469             self.finish_endtag = target.end
 470             self.handle_data = target.data
 471             self.handle_xml = target.xml
 472
 473             # activate parser
 474             self.parser = sgmlop.XMLParser()
 475             self.parser.register(self)
 476             self.feed = self.parser.feed
 477             self.entity = {
 478                 "amp": "&", "gt": ">", "lt": "<",
 479                 "apos": "'", "quot": '"'
 480                 }
 481
 482         def close(self):
 483             try:
 484                 self.parser.close()
 485             finally:
 486                 self.parser = self.feed = None # nuke circular reference
 487
 488         def handle_proc(self, tag, attr):
 489             m = re.search("encoding\s*=\s*['\"]([^\"']+)[\"']", attr)
 490             if m:
 491                 self.handle_xml(m.group(1), 1)
 492
 493         def handle_entityref(self, entity):
 494             # <string> entity
 495             try:
 496                 self.handle_data(self.entity[entity])
 497             except KeyError:
 498                 self.handle_data("&%s;" % entity)
 499
 500 try:
 501     from xml.parsers import expat
 502     if not hasattr(expat, "ParserCreate"):
 503         raise ImportError
 504 except ImportError:
 505     ExpatParser = None # expat not available
 506 else:
 507     class ExpatParser:
 508         # fast expat parser for Python 2.0 and later.  this is about
 509         # 50% slower than sgmlop, on roundtrip testing
 510         def __init__(self, target):
 511             self._parser = parser = expat.ParserCreate(None, None)
 512             self._target = target
 513             parser.StartElementHandler = target.start
 514             parser.EndElementHandler = target.end
 515             parser.CharacterDataHandler = target.data
 516             encoding = None
 517             if not parser.returns_unicode:
 518                 encoding = "utf-8"
 519             target.xml(encoding, None)
 520
 521         def feed(self, data):
 522             self._parser.Parse(data, 0)
 523
 524         def close(self):
 525             self._parser.Parse("", 1) # end of data
 526             del self._target, self._parser # get rid of circular references
 527
 528 class SlowParser:
 529     """Default XML parser (based on xmllib.XMLParser)."""
 530     # this is about 10 times slower than sgmlop, on roundtrip
 531     # testing.
 532     def __init__(self, target):
 533         import xmllib # lazy subclassing (!)
 534         if xmllib.XMLParser not in SlowParser.__bases__:
 535             SlowParser.__bases__ = (xmllib.XMLParser,)
 536         self.handle_xml = target.xml
 537         self.unknown_starttag = target.start
 538         self.handle_data = target.data
 539         self.handle_cdata = target.data
 540         self.unknown_endtag = target.end
 541         try:
 542             xmllib.XMLParser.__init__(self, accept_utf8=1)
 543         except TypeError:
 544             xmllib.XMLParser.__init__(self) # pre-2.0
 545
 546 # --------------------------------------------------------------------
 547 # XML-RPC marshalling and unmarshalling code
 548
 549 ##
 550 # XML-RPC marshaller.
 551 #
 552 # @param encoding Default encoding for 8-bit strings.  The default
 553 #     value is None (interpreted as UTF-8).
 554 # @see dumps
 555
 556 class Marshaller:
 557     """Generate an XML-RPC params chunk from a Python data structure.
 558
 559     Create a Marshaller instance for each set of parameters, and use
 560     the "dumps" method to convert your data (represented as a tuple)
 561     to an XML-RPC params chunk.  To write a fault response, pass a
 562     Fault instance instead.  You may prefer to use the "dumps" module
 563     function for this purpose.
 564     """
 565
 566     # by the way, if you don't understand what's going on in here,
 567     # that's perfectly ok.
 568
 569     def __init__(self, encoding=None, allow_none=0):
 570         self.memo = {}
 571         self.data = None
 572         self.encoding = encoding
 573         self.allow_none = allow_none
 574
 575     dispatch = {}
 576
 577     def dumps(self, values):
 578         out = []
 579         write = out.append
 580         dump = self.__dump
 581         if isinstance(values, Fault):
 582             # fault instance
 583             write("<fault>\n")
 584             dump(vars(values), write)
 585             write("</fault>\n")
 586         else:
 587             # parameter block
 588             # FIXME: the xml-rpc specification allows us to leave out
 589             # the entire <params> block if there are no parameters.
 590             # however, changing this may break older code (including
 591             # old versions of xmlrpclib.py), so this is better left as
 592             # is for now.  See @XMLRPC3 for more information. /F
 593             write("<params>\n")
 594             for v in values:
 595                 write("<param>\n")
 596                 dump(v, write)
 597                 write("</param>\n")
 598             write("</params>\n")
 599         result = string.join(out, "")
 600         return result
 601
 602     def __dump(self, value, write):
 603         try:
 604             f = self.dispatch[type(value)]
 605         except KeyError:
 606             raise TypeError, "cannot marshal %s objects" % type(value)
 607         else:
 608             f(self, value, write)
 609
 610     def dump_nil (self, value, write):
 611         if not self.allow_none:
 612             raise TypeError, "cannot marshal None unless allow_none is enabled"
 613         write("<value><nil/></value>")
 614     dispatch[NoneType] = dump_nil
 615
 616     def dump_int(self, value, write):
 617         # in case ints are > 32 bits
 618         if value > MAXINT or value < MININT:
 619             raise OverflowError, "int exceeds XML-RPC limits"
 620         write("<value><int>")
 621         write(str(value))
 622         write("</int></value>\n")
 623     dispatch[IntType] = dump_int
 624
 625     if _bool_is_builtin:
 626         def dump_bool(self, value, write):
 627             write("<value><boolean>")
 628             write(value and "1" or "0")
 629             write("</boolean></value>\n")
 630         dispatch[bool] = dump_bool
 631
 632     def dump_long(self, value, write):
 633         if value > MAXINT or value < MININT:
 634             raise OverflowError, "long int exceeds XML-RPC limits"
 635         write("<value><int>")
 636         write(str(int(value)))
 637         write("</int></value>\n")
 638     dispatch[LongType] = dump_long
 639
 640     def dump_double(self, value, write):
 641         write("<value><double>")
 642         write(repr(value))
 643         write("</double></value>\n")
 644     dispatch[FloatType] = dump_double
 645
 646     def dump_string(self, value, write, escape=escape):
 647         write("<value><string>")
 648         write(escape(value))
 649         write("</string></value>\n")
 650     dispatch[StringType] = dump_string
 651
 652     if unicode:
 653         def dump_unicode(self, value, write, escape=escape):
 654             value = value.encode(self.encoding)
 655             write("<value><string>")
 656             write(escape(value))
 657             write("</string></value>\n")
 658         dispatch[UnicodeType] = dump_unicode
 659
 660     def dump_array(self, value, write):
 661         i = id(value)
 662         if self.memo.has_key(i):
 663             raise TypeError, "cannot marshal recursive sequences"
 664         self.memo[i] = None
 665         dump = self.__dump
 666         write("<value><array><data>\n")
 667         for v in value:
 668             dump(v, write)
 669         write("</data></array></value>\n")
 670         del self.memo[i]
 671     dispatch[TupleType] = dump_array
 672     dispatch[ListType] = dump_array
 673
 674     def dump_struct(self, value, write, escape=escape):
 675         i = id(value)
 676         if self.memo.has_key(i):
 677             raise TypeError, "cannot marshal recursive dictionaries"
 678         self.memo[i] = None
 679         dump = self.__dump
 680         write("<value><struct>\n")
 681         for k in value.keys():
 682             write("<member>\n")
 683             if type(k) is not StringType:
 684                 raise TypeError, "dictionary key must be string"
 685             write("<name>%s</name>\n" % escape(k))
 686             dump(value[k], write)
 687             write("</member>\n")
 688         write("</struct></value>\n")
 689         del self.memo[i]
 690     dispatch[DictType] = dump_struct
 691
 692     def dump_instance(self, value, write):
 693         # check for special wrappers
 694         if value.__class__ in WRAPPERS:
 695             self.write = write
 696             value.encode(self)
 697             del self.write
 698         else:
 699             # store instance attributes as a struct (really?)
 700             self.dump_struct(value.__dict__, write)
 701     dispatch[InstanceType] = dump_instance
 702
 703 ##
 704 # XML-RPC unmarshaller.
 705 #
 706 # @see loads
 707
 708 class Unmarshaller:
 709     """Unmarshal an XML-RPC response, based on incoming XML event
 710     messages (start, data, end).  Call close() to get the resulting
 711     data structure.
 712
 713     Note that this reader is fairly tolerant, and gladly accepts bogus
 714     XML-RPC data without complaining (but not bogus XML).
 715     """
 716
 717     # and again, if you don't understand what's going on in here,
 718     # that's perfectly ok.
 719
 720     def __init__(self):
 721         self._type = None
 722         self._stack = []
 723         self._marks = []
 724         self._data = []
 725         self._methodname = None
 726         self._encoding = "utf-8"
 727         self.append = self._stack.append
 728
 729     def close(self):
 730         # return response tuple and target method
 731         if self._type is None or self._marks:
 732             raise ResponseError()
 733         if self._type == "fault":
 734             raise Fault(**self._stack[0])
 735         return tuple(self._stack)
 736
 737     def getmethodname(self):
 738         return self._methodname
 739
 740     #
 741     # event handlers
 742
 743     def xml(self, encoding, standalone):
 744         self._encoding = encoding
 745         # FIXME: assert standalone == 1 ???
 746
 747     def start(self, tag, attrs):
 748         # prepare to handle this element
 749         if tag == "array" or tag == "struct":
 750             self._marks.append(len(self._stack))
 751         self._data = []
 752         self._value = (tag == "value")
 753
 754     def data(self, text):
 755         self._data.append(text)
 756
 757     def end(self, tag, join=string.join):
 758         # call the appropriate end tag handler
 759         try:
 760             f = self.dispatch[tag]
 761         except KeyError:
 762             pass # unknown tag ?
 763         else:
 764             return f(self, join(self._data, ""))
 765
 766     #
 767     # accelerator support
 768
 769     def end_dispatch(self, tag, data):
 770         # dispatch data
 771         try:
 772             f = self.dispatch[tag]
 773         except KeyError:
 774             pass # unknown tag ?
 775         else:
 776             return f(self, data)
 777
 778     #
 779     # element decoders
 780
 781     dispatch = {}
 782
 783     def end_nil (self, data):
 784         self.append(None)
 785         self._value = 0
 786     dispatch["nil"] = end_nil
 787
 788     def end_boolean(self, data):
 789         if data == "0":
 790             self.append(False)
 791         elif data == "1":
 792             self.append(True)
 793         else:
 794             raise TypeError, "bad boolean value"
 795         self._value = 0
 796     dispatch["boolean"] = end_boolean
 797
 798     def end_int(self, data):
 799         self.append(int(data))
 800         self._value = 0
 801     dispatch["i4"] = end_int
 802     dispatch["int"] = end_int
 803
 804     def end_double(self, data):
 805         self.append(float(data))
 806         self._value = 0
 807     dispatch["double"] = end_double
 808
 809     def end_string(self, data):
 810         if self._encoding:
 811             data = _decode(data, self._encoding)
 812         self.append(_stringify(data))
 813         self._value = 0
 814     dispatch["string"] = end_string
 815     dispatch["name"] = end_string # struct keys are always strings
 816
 817     def end_array(self, data):
 818         mark = self._marks.pop()
 819         # map arrays to Python lists
 820         self._stack[mark:] = [self._stack[mark:]]
 821         self._value = 0
 822     dispatch["array"] = end_array
 823
 824     def end_struct(self, data):
 825         mark = self._marks.pop()
 826         # map structs to Python dictionaries
 827         dict = {}
 828         items = self._stack[mark:]
 829         for i in range(0, len(items), 2):
 830             dict[_stringify(items[i])] = items[i+1]
 831         self._stack[mark:] = [dict]
 832         self._value = 0
 833     dispatch["struct"] = end_struct
 834
 835     def end_base64(self, data):
 836         value = Binary()
 837         value.decode(data)
 838         self.append(value)
 839         self._value = 0
 840     dispatch["base64"] = end_base64
 841
 842     def end_dateTime(self, data):
 843         value = DateTime()
 844         value.decode(data)
 845         self.append(value)
 846     dispatch["dateTime.iso8601"] = end_dateTime
 847
 848     def end_value(self, data):
 849         # if we stumble upon a value element with no internal
 850         # elements, treat it as a string element
 851         if self._value:
 852             self.end_string(data)
 853     dispatch["value"] = end_value
 854
 855     def end_params(self, data):
 856         self._type = "params"
 857     dispatch["params"] = end_params
 858
 859     def end_fault(self, data):
 860         self._type = "fault"
 861     dispatch["fault"] = end_fault
 862
 863     def end_methodName(self, data):
 864         if self._encoding:
 865             data = _decode(data, self._encoding)
 866         self._methodname = data
 867         self._type = "methodName" # no params
 868     dispatch["methodName"] = end_methodName
 869
 870
 871 # --------------------------------------------------------------------
 872 # convenience functions
 873
 874 ##
 875 # Create a parser object, and connect it to an unmarshalling instance.
 876 # This function picks the fastest available XML parser.
 877 #
 878 # return A (parser, unmarshaller) tuple.
 879
 880 def getparser():
 881     """getparser() -> parser, unmarshaller
 882
 883     Create an instance of the fastest available parser, and attach it
 884     to an unmarshalling object.  Return both objects.
 885     """
 886     if FastParser and FastUnmarshaller:
 887         target = FastUnmarshaller(True, False, _binary, _datetime, Fault)
 888         parser = FastParser(target)
 889     else:
 890         target = Unmarshaller()
 891         if FastParser:
 892             parser = FastParser(target)
 893         elif SgmlopParser:
 894             parser = SgmlopParser(target)
 895         elif ExpatParser:
 896             parser = ExpatParser(target)
 897         else:
 898             parser = SlowParser(target)
 899     return parser, target
 900
 901 ##
 902 # Convert a Python tuple or a Fault instance to an XML-RPC packet.
 903 #
 904 # @def dumps(params, **options)
 905 # @param params A tuple or Fault instance.
 906 # @keyparam methodname If given, create a methodCall request for
 907 #     this method name.
 908 # @keyparam methodresponse If given, create a methodResponse packet.
 909 #     If used with a tuple, the tuple must be a singleton (that is,
 910 #     it must contain exactly one element).
 911 # @keyparam encoding The packet encoding.
 912 # @return A string containing marshalled data.
 913
 914 def dumps(params, methodname=None, methodresponse=None, encoding=None,
 915           allow_none=0):
 916     """data [,options] -> marshalled data
 917
 918     Convert an argument tuple or a Fault instance to an XML-RPC
 919     request (or response, if the methodresponse option is used).
 920
 921     In addition to the data object, the following options can be given
 922     as keyword arguments:
 923
 924         methodname: the method name for a methodCall packet
 925
 926         methodresponse: true to create a methodResponse packet.
 927         If this option is used with a tuple, the tuple must be
 928         a singleton (i.e. it can contain only one element).
 929
 930         encoding: the packet encoding (default is UTF-8)
 931
 932     All 8-bit strings in the data structure are assumed to use the
 933     packet encoding.  Unicode strings are automatically converted,
 934     where necessary.
 935     """
 936
 937     assert isinstance(params, TupleType) or isinstance(params, Fault),\
 938            "argument must be tuple or Fault instance"
 939
 940     if isinstance(params, Fault):
 941         methodresponse = 1
 942     elif methodresponse and isinstance(params, TupleType):
 943         assert len(params) == 1, "response tuple must be a singleton"
 944
 945     if not encoding:
 946         encoding = "utf-8"
 947
 948     if FastMarshaller:
 949         m = FastMarshaller(encoding)
 950     else:
 951         m = Marshaller(encoding, allow_none)
 952
 953     data = m.dumps(params)
 954
 955     if encoding != "utf-8":
 956         xmlheader = "<?xml version='1.0' encoding='%s'?>\n" % str(encoding)
 957     else:
 958         xmlheader = "<?xml version='1.0'?>\n" # utf-8 is default
 959
 960     # standard XML-RPC wrappings
 961     if methodname:
 962         # a method call
 963         if not isinstance(methodname, StringType):
 964             methodname = methodname.encode(encoding)
 965         data = (
 966             xmlheader,
 967             "<methodCall>\n"
 968             "<methodName>", methodname, "</methodName>\n",
 969             data,
 970             "</methodCall>\n"
 971             )
 972     elif methodresponse:
 973         # a method response, or a fault structure
 974         data = (
 975             xmlheader,
 976             "<methodResponse>\n",
 977             data,
 978             "</methodResponse>\n"
 979             )
 980     else:
 981         return data # return as is
 982     return string.join(data, "")
 983
 984 ##
 985 # Convert an XML-RPC packet to a Python object.  If the XML-RPC packet
 986 # represents a fault condition, this function raises a Fault exception.
 987 #
 988 # @param data An XML-RPC packet, given as an 8-bit string.
 989 # @return A tuple containing the the unpacked data, and the method name
 990 #     (None if not present).
 991 # @see Fault
 992
 993 def loads(data):
 994     """data -> unmarshalled data, method name
 995
 996     Convert an XML-RPC packet to unmarshalled data plus a method
 997     name (None if not present).
 998
 999     If the XML-RPC packet represents a fault condition, this function
1000     raises a Fault exception.
1001     """
1002     import sys
1003     p, u = getparser()
1004     p.feed(data)
1005     p.close()
1006     return u.close(), u.getmethodname()
1007
1008
1009 # --------------------------------------------------------------------
1010 # request dispatcher
1011
1012 class _Method:
1013     # some magic to bind an XML-RPC method to an RPC server.
1014     # supports "nested" methods (e.g. examples.getStateName)
1015     def __init__(self, send, name):
1016         self.__send = send
1017         self.__name = name
1018     def __getattr__(self, name):
1019         return _Method(self.__send, "%s.%s" % (self.__name, name))
1020     def __call__(self, *args):
1021         return self.__send(self.__name, args)
1022
1023 ##
1024 # Standard transport class for XML-RPC over HTTP.
1025 # <p>
1026 # You can create custom transports by subclassing this method, and
1027 # overriding selected methods.
1028
1029 class Transport:
1030     """Handles an HTTP transaction to an XML-RPC server."""
1031
1032     # client identifier (may be overridden)
1033     user_agent = "xmlrpclib.py/%s (by www.pythonware.com)" % __version__
1034
1035     ##
1036     # Send a complete request, and parse the response.
1037     #
1038     # @param host Target host.
1039     # @param handler Target PRC handler.
1040     # @param request_body XML-RPC request body.
1041     # @param verbose Debugging flag.
1042     # @return Parsed response.
1043
1044     def request(self, host, handler, request_body, verbose=0):
1045         # issue XML-RPC request
1046
1047         h = self.make_connection(host)
1048         if verbose:
1049             h.set_debuglevel(1)
1050
1051         self.send_request(h, handler, request_body)
1052         self.send_host(h, host)
1053         self.send_user_agent(h)
1054         self.send_content(h, request_body)
1055
1056         errcode, errmsg, headers = h.getreply()
1057
1058         if errcode != 200:
1059             raise ProtocolError(
1060                 host + handler,
1061                 errcode, errmsg,
1062                 headers
1063                 )
1064
1065         self.verbose = verbose
1066
1067         try:
1068             sock = h._conn.sock
1069         except AttributeError:
1070             sock = None
1071
1072         return self._parse_response(h.getfile(), sock)
1073
1074     ##
1075     # Create parser.
1076     #
1077     # @return A 2-tuple containing a parser and a unmarshaller.
1078
1079     def getparser(self):
1080         # get parser and unmarshaller
1081         return getparser()
1082
1083     ##
1084     # Get authorization info from host parameter
1085     # Host may be a string, or a (host, x509-dict) tuple; if a string,
1086     # it is checked for a "user:pw@host" format, and a "Basic
1087     # Authentication" header is added if appropriate.
1088     #
1089     # @param host Host descriptor (URL or (URL, x509 info) tuple).
1090     # @return A 3-tuple containing (actual host, extra headers,
1091     #     x509 info).  The header and x509 fields may be None.
1092
1093     def get_host_info(self, host):
1094
1095         x509 = {}
1096         if isinstance(host, TupleType):
1097             host, x509 = host
1098
1099         import urllib
1100         auth, host = urllib.splituser(host)
1101
1102         if auth:
1103             import base64
1104             auth = base64.encodestring(urllib.unquote(auth))
1105             auth = string.join(string.split(auth), "") # get rid of whitespace
1106             extra_headers = [
1107                 ("Authorization", "Basic " + auth)
1108                 ]
1109         else:
1110             extra_headers = None
1111
1112         return host, extra_headers, x509
1113
1114     ##
1115     # Connect to server.
1116     #
1117     # @param host Target host.
1118     # @return A connection handle.
1119
1120     def make_connection(self, host):
1121         # create a HTTP connection object from a host descriptor
1122         import httplib
1123         host, extra_headers, x509 = self.get_host_info(host)
1124         return httplib.HTTP(host)
1125
1126     ##
1127     # Send request header.
1128     #
1129     # @param connection Connection handle.
1130     # @param handler Target RPC handler.
1131     # @param request_body XML-RPC body.
1132
1133     def send_request(self, connection, handler, request_body):
1134         connection.putrequest("POST", handler)
1135
1136     ##
1137     # Send host name.
1138     #
1139     # @param connection Connection handle.
1140     # @param host Host name.
1141
1142     def send_host(self, connection, host):
1143         host, extra_headers, x509 = self.get_host_info(host)
1144         connection.putheader("Host", host)
1145         if extra_headers:
1146             if isinstance(extra_headers, DictType):
1147                 extra_headers = extra_headers.items()
1148             for key, value in extra_headers:
1149                 connection.putheader(key, value)
1150
1151     ##
1152     # Send user-agent identifier.
1153     #
1154     # @param connection Connection handle.
1155
1156     def send_user_agent(self, connection):
1157         connection.putheader("User-Agent", self.user_agent)
1158
1159     ##
1160     # Send request body.
1161     #
1162     # @param connection Connection handle.
1163     # @param request_body XML-RPC request body.
1164
1165     def send_content(self, connection, request_body):
1166         connection.putheader("Content-Type", "text/xml")
1167         connection.putheader("Content-Length", str(len(request_body)))
1168         connection.endheaders()
1169         if request_body:
1170             connection.send(request_body)
1171
1172     ##
1173     # Parse response.
1174     #
1175     # @param file Stream.
1176     # @return Response tuple and target method.
1177
1178     def parse_response(self, file):
1179         # compatibility interface
1180         return self._parse_response(file, None)
1181
1182     ##
1183     # Parse response (alternate interface).  This is similar to the
1184     # parse_response method, but also provides direct access to the
1185     # underlying socket object (where available).
1186     #
1187     # @param file Stream.
1188     # @param sock Socket handle (or None, if the socket object
1189     #    could not be accessed).
1190     # @return Response tuple and target method.
1191
1192     def _parse_response(self, file, sock):
1193         # read response from input file/socket, and parse it
1194
1195         p, u = self.getparser()
1196
1197         while 1:
1198             if sock:
1199                 response = sock.recv(1024)
1200             else:
1201                 response = file.read(1024)
1202             if not response:
1203                 break
1204             if self.verbose:
1205                 print "body:", repr(response)
1206             p.feed(response)
1207
1208         file.close()
1209         p.close()
1210
1211         return u.close()
1212
1213 ##
1214 # Standard transport class for XML-RPC over HTTPS.
1215
1216 class SafeTransport(Transport):
1217     """Handles an HTTPS transaction to an XML-RPC server."""
1218
1219     # FIXME: mostly untested
1220
1221     def make_connection(self, host):
1222         # create a HTTPS connection object from a host descriptor
1223         # host may be a string, or a (host, x509-dict) tuple
1224         import httplib
1225         host, extra_headers, x509 = self.get_host_info(host)
1226         try:
1227             HTTPS = httplib.HTTPS
1228         except AttributeError:
1229             raise NotImplementedError(
1230                 "your version of httplib doesn't support HTTPS"
1231                 )
1232         else:
1233             return HTTPS(host, None, **(x509 or {}))
1234
1235 ##
1236 # Standard server proxy.  This class establishes a virtual connection
1237 # to an XML-RPC server.
1238 # <p>
1239 # This class is available as ServerProxy and Server.  New code should
1240 # use ServerProxy, to avoid confusion.
1241 #
1242 # @def ServerProxy(uri, **options)
1243 # @param uri The connection point on the server.
1244 # @keyparam transport A transport factory, compatible with the
1245 #    standard transport class.
1246 # @keyparam encoding The default encoding used for 8-bit strings
1247 #    (default is UTF-8).
1248 # @keyparam verbose Use a true value to enable debugging output.
1249 #    (printed to standard output).
1250 # @see Transport
1251
1252 class ServerProxy:
1253     """uri [,options] -> a logical connection to an XML-RPC server
1254
1255     uri is the connection point on the server, given as
1256     scheme://host/target.
1257
1258     The standard implementation always supports the "http" scheme.  If
1259     SSL socket support is available (Python 2.0), it also supports
1260     "https".
1261
1262     If the target part and the slash preceding it are both omitted,
1263     "/RPC2" is assumed.
1264
1265     The following options can be given as keyword arguments:
1266
1267         transport: a transport factory
1268         encoding: the request encoding (default is UTF-8)
1269
1270     All 8-bit strings passed to the server proxy are assumed to use
1271     the given encoding.
1272     """
1273
1274     def __init__(self, uri, transport=None, encoding=None, verbose=0,
1275                  allow_none=0):
1276         # establish a "logical" server connection
1277
1278         # get the url
1279         import urllib
1280         type, uri = urllib.splittype(uri)
1281         if type not in ("http", "https"):
1282             raise IOError, "unsupported XML-RPC protocol"
1283         self.__host, self.__handler = urllib.splithost(uri)
1284         if not self.__handler:
1285             self.__handler = "/RPC2"
1286
1287         if transport is None:
1288             if type == "https":
1289                 transport = SafeTransport()
1290             else:
1291                 transport = Transport()
1292         self.__transport = transport
1293
1294         self.__encoding = encoding
1295         self.__verbose = verbose
1296         self.__allow_none = allow_none
1297
1298     def __request(self, methodname, params):
1299         # call a method on the remote server
1300
1301         request = dumps(params, methodname, encoding=self.__encoding,
1302                         allow_none=self.__allow_none)
1303
1304         response = self.__transport.request(
1305             self.__host,
1306             self.__handler,
1307             request,
1308             verbose=self.__verbose
1309             )
1310
1311         if len(response) == 1:
1312             response = response[0]
1313
1314         return response
1315
1316     def __repr__(self):
1317         return (
1318             "<ServerProxy for %s%s>" %
1319             (self.__host, self.__handler)
1320             )
1321
1322     __str__ = __repr__
1323
1324     def __getattr__(self, name):
1325         # magic method dispatcher
1326         return _Method(self.__request, name)
1327
1328     # note: to call a remote object with an non-standard name, use
1329     # result getattr(server, "strange-python-name")(args)
1330
1331 # compatibility
1332
1333 Server = ServerProxy
1334
1335 # --------------------------------------------------------------------
1336 # test code
1337
1338 if __name__ == "__main__":
1339
1340     # simple test program (from the XML-RPC specification)
1341
1342     # server = ServerProxy("http://localhost:8000") # local server
1343     server = ServerProxy("http://betty.userland.com")
1344
1345     print server
1346
1347     try:
1348         print server.examples.getStateName(41)
1349     except Error, v:
1350         print "ERROR", v