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, "&", "&")

   169     s = replace(s, "<", "&lt;")

   170     return replace(s, ">", ">",)

   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 # --------------------------------------------------------------------