Module xmlrpclib
[hide private]
[frames] | no frames]

Source Code for Module xmlrpclib

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