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