2 # XML-RPC CLIENT LIBRARY
5 # an XML-RPC client interface for Python.
7 # the marshalling and response parser code can also be used to
8 # implement XML-RPC servers.
11 # this version is designed to work with Python 2.1 or newer.
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
53 # Copyright (c) 1999-2002 by Secret Labs AB.
54 # Copyright (c) 1999-2002 by Fredrik Lundh.
57 # http://www.pythonware.com
59 # --------------------------------------------------------------------
60 # The XML-RPC client interface is
62 # Copyright (c) 1999-2002 by Secret Labs AB
63 # Copyright (c) 1999-2002 by Fredrik Lundh
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:
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
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
86 # --------------------------------------------------------------------
89 # things to look into some day:
91 # TODO: sort out True/False/boolean issues for Python 2.3
94 An XML-RPC client interface for Python.
96 The marshalling and response parser code can also be used to
97 implement XML-RPC servers.
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
108 ServerProxy Represents a logical connection to an XML-RPC server
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"
115 Binary binary data wrapper
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
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).
139 import re
, string
, time
, operator
143 # --------------------------------------------------------------------
149 unicode = None # unicode support not available
157 _bool_is_builtin
= False.__class
__.__name
__ == "bool"
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
)
167 def escape(s
, replace
=string
.replace
):
168 s
= replace(s
, "&", "&")
169 s
= replace(s
, "<", "<")
170 return replace(s
, ">", ">",)
173 def _stringify(string
):
174 # convert to 7-bit ascii if possible
176 return string
.encode("ascii")
180 def _stringify(string
):
183 __version__
= "1.0.1"
185 # xmlrpc integer limits
189 # --------------------------------------------------------------------
190 # Error constants (from Dan Libby's specification at
191 # http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php)
195 SERVER_ERROR
= -32600
196 APPLICATION_ERROR
= -32500
197 SYSTEM_ERROR
= -32400
198 TRANSPORT_ERROR
= -32300
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
209 # --------------------------------------------------------------------
213 # Base class for all kinds of client-side errors.
215 class Error(Exception):
216 """Base class for client errors."""
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
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.
230 class ProtocolError(Error
):
231 """Indicates an HTTP protocol error."""
232 def __init__(self
, url
, errcode
, errmsg
, headers
):
235 self
.errcode
= errcode
237 self
.headers
= headers
240 "<ProtocolError for %s: %s %s>" %
241 (self
.url
, self
.errcode
, self
.errmsg
)
245 # Indicates a broken XML-RPC response package. This exception is
246 # raised by the unmarshalling layer, if the XML-RPC response is
249 class ResponseError(Error
):
250 """Indicates a broken response package."""
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.
259 # @param faultCode The XML-RPC fault code.
260 # @param faultString The XML-RPC fault string.
263 """Indicates an XML-RPC fault package."""
264 def __init__(self
, faultCode
, faultString
, **extra
):
266 self
.faultCode
= faultCode
267 self
.faultString
= faultString
271 (self
.faultCode
, repr(self
.faultString
))
274 # --------------------------------------------------------------------
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.
282 # @param value A boolean value. Any true value is interpreted as True,
283 # all other values are interpreted as False.
285 from sys
import modules
286 mod_dict
= modules
[__name__
].__dict
__
288 boolean
= Boolean
= bool
289 # to avoid breaking code which references xmlrpclib.{True,False}
290 mod_dict
['True'] = True
291 mod_dict
['False'] = False
294 """Boolean-value wrapper.
296 Use True or False to generate a "boolean" XML-RPC value.
299 def __init__(self
, value
= 0):
300 self
.value
= operator
.truth(value
)
302 def encode(self
, out
):
303 out
.write("<value><boolean>%d</boolean></value>\n" % self
.value
)
305 def __cmp__(self
, other
):
306 if isinstance(other
, Boolean
):
308 return cmp(self
.value
, other
)
312 return "<Boolean True at %x>" % id(self
)
314 return "<Boolean False at %x>" % id(self
)
319 def __nonzero__(self
):
322 mod_dict
['True'] = Boolean(1)
323 mod_dict
['False'] = Boolean(0)
326 # Map true or false value to XML-RPC boolean values.
328 # @def boolean(value)
329 # @param value A boolean value. Any true value is mapped to True,
330 # all other values are mapped to False.
331 # @return xmlrpclib.True or xmlrpclib.False.
336 def boolean(value
, _truefalse
=(False, True)):
337 """Convert any Python value to XML-RPC 'boolean'."""
338 return _truefalse
[operator
.truth(value
)]
340 del modules
, mod_dict
343 # Wrapper for XML-RPC DateTime values. This converts a time value to
344 # the format used by XML-RPC.
346 # The value can be given as a string in the format
347 # "yyyymmddThh:mm:ss", as a 9-item time tuple (as returned by
348 # time.localtime()), or an integer value (as returned by time.time()).
349 # The wrapper uses time.localtime() to convert an integer to a time
352 # @param value The time, given as an ISO 8601 string, a time
353 # tuple, or a integer time value.
355 def _strftime(value
):
357 if isinstance(value
, datetime
.datetime
):
358 return "%04d%02d%02dT%02d:%02d:%02d" % (
359 value
.year
, value
.month
, value
.day
,
360 value
.hour
, value
.minute
, value
.second
)
362 if not isinstance(value
, (TupleType
, time
.struct_time
)):
365 value
= time
.localtime(value
)
367 return "%04d%02d%02dT%02d:%02d:%02d" % value
[:6]
370 """DateTime wrapper for an ISO 8601 string or time tuple or
371 localtime integer value to generate 'dateTime.iso8601' XML-RPC
375 def __init__(self
, value
=0):
376 if isinstance(value
, StringType
):
379 self
.value
= _strftime(value
)
381 def make_comparable(self
, other
):
382 if isinstance(other
, DateTime
):
385 elif datetime
and isinstance(other
, datetime
.datetime
):
387 o
= other
.strftime("%Y%m%dT%H:%M:%S")
388 elif isinstance(other
, (str, unicode)):
391 elif hasattr(other
, "timetuple"):
393 o
= other
.timetuple()
395 otype
= (hasattr(other
, "__class__")
396 and other
.__class
__.__name
__
398 raise TypeError("Can't compare %s and %s" %
399 (self
.__class
__.__name
__, otype
))
402 def __lt__(self
, other
):
403 s
, o
= self
.make_comparable(other
)
406 def __le__(self
, other
):
407 s
, o
= self
.make_comparable(other
)
410 def __gt__(self
, other
):
411 s
, o
= self
.make_comparable(other
)
414 def __ge__(self
, other
):
415 s
, o
= self
.make_comparable(other
)
418 def __eq__(self
, other
):
419 s
, o
= self
.make_comparable(other
)
422 def __ne__(self
, other
):
423 s
, o
= self
.make_comparable(other
)
427 return time
.strptime(self
.value
, "%Y%m%dT%H:%M:%S")
429 def __cmp__(self
, other
):
430 s
, o
= self
.make_comparable(other
)
434 # Get date/time value.
436 # @return Date/time value, as an ISO 8601 string.
442 return "<DateTime %s at %x>" % (repr(self
.value
), id(self
))
444 def decode(self
, data
):
446 self
.value
= string
.strip(data
)
448 def encode(self
, out
):
449 out
.write("<value><dateTime.iso8601>")
450 out
.write(self
.value
)
451 out
.write("</dateTime.iso8601></value>\n")
454 # decode xml element contents into a DateTime structure.
459 def _datetime_type(data
):
460 t
= time
.strptime(data
, "%Y%m%dT%H:%M:%S")
461 return datetime
.datetime(*tuple(t
)[:6])
464 # Wrapper for binary data. This can be used to transport any kind
465 # of binary data over XML-RPC, using BASE64 encoding.
467 # @param data An 8-bit string containing arbitrary data.
471 import cStringIO
as StringIO
476 """Wrapper for binary data."""
478 def __init__(self
, data
=None):
482 # Get buffer contents.
484 # @return Buffer contents, as an 8-bit string.
487 return self
.data
or ""
489 def __cmp__(self
, other
):
490 if isinstance(other
, Binary
):
492 return cmp(self
.data
, other
)
494 def decode(self
, data
):
495 self
.data
= base64
.decodestring(data
)
497 def encode(self
, out
):
498 out
.write("<value><base64>\n")
499 base64
.encode(StringIO
.StringIO(self
.data
), out
)
500 out
.write("</base64></value>\n")
503 # decode xml element contents into a Binary structure
508 WRAPPERS
= (DateTime
, Binary
)
509 if not _bool_is_builtin
:
510 WRAPPERS
= WRAPPERS
+ (Boolean
,)
512 # --------------------------------------------------------------------
516 # optional xmlrpclib accelerator
518 FastParser
= _xmlrpclib
.Parser
519 FastUnmarshaller
= _xmlrpclib
.Unmarshaller
520 except (AttributeError, ImportError):
521 FastParser
= FastUnmarshaller
= None
525 FastMarshaller
= _xmlrpclib
.Marshaller
526 except (AttributeError, ImportError):
527 FastMarshaller
= None
530 # the SGMLOP parser is about 15x faster than Python's builtin
531 # XML parser. SGMLOP sources can be downloaded from:
533 # http://www.pythonware.com/products/xml/sgmlop.htm
538 if not hasattr(sgmlop
, "XMLParser"):
541 SgmlopParser
= None # sgmlop accelerator not available
544 def __init__(self
, target
):
547 self
.finish_starttag
= target
.start
548 self
.finish_endtag
= target
.end
549 self
.handle_data
= target
.data
550 self
.handle_xml
= target
.xml
553 self
.parser
= sgmlop
.XMLParser()
554 self
.parser
.register(self
)
555 self
.feed
= self
.parser
.feed
557 "amp": "&", "gt": ">", "lt": "<",
558 "apos": "'", "quot": '"'
565 self
.parser
= self
.feed
= None # nuke circular reference
567 def handle_proc(self
, tag
, attr
):
568 m
= re
.search("encoding\s*=\s*['\"]([^\"']+)[\"']", attr
)
570 self
.handle_xml(m
.group(1), 1)
572 def handle_entityref(self
, entity
):
575 self
.handle_data(self
.entity
[entity
])
577 self
.handle_data("&%s;" % entity
)
580 from xml
.parsers
import expat
581 if not hasattr(expat
, "ParserCreate"):
584 ExpatParser
= None # expat not available
587 # fast expat parser for Python 2.0 and later. this is about
588 # 50% slower than sgmlop, on roundtrip testing
589 def __init__(self
, target
):
590 self
._parser
= parser
= expat
.ParserCreate(None, None)
591 self
._target
= target
592 parser
.StartElementHandler
= target
.start
593 parser
.EndElementHandler
= target
.end
594 parser
.CharacterDataHandler
= target
.data
596 if not parser
.returns_unicode
:
598 target
.xml(encoding
, None)
600 def feed(self
, data
):
601 self
._parser
.Parse(data
, 0)
604 self
._parser
.Parse("", 1) # end of data
605 del self
._target
, self
._parser
# get rid of circular references
608 """Default XML parser (based on xmllib.XMLParser)."""
609 # this is about 10 times slower than sgmlop, on roundtrip
611 def __init__(self
, target
):
612 import xmllib
# lazy subclassing (!)
613 if xmllib
.XMLParser
not in SlowParser
.__bases
__:
614 SlowParser
.__bases
__ = (xmllib
.XMLParser
,)
615 self
.handle_xml
= target
.xml
616 self
.unknown_starttag
= target
.start
617 self
.handle_data
= target
.data
618 self
.handle_cdata
= target
.data
619 self
.unknown_endtag
= target
.end
621 xmllib
.XMLParser
.__init
__(self
, accept_utf8
=1)
623 xmllib
.XMLParser
.__init
__(self
) # pre-2.0
625 # --------------------------------------------------------------------
626 # XML-RPC marshalling and unmarshalling code
629 # XML-RPC marshaller.
631 # @param encoding Default encoding for 8-bit strings. The default
632 # value is None (interpreted as UTF-8).
636 """Generate an XML-RPC params chunk from a Python data structure.
638 Create a Marshaller instance for each set of parameters, and use
639 the "dumps" method to convert your data (represented as a tuple)
640 to an XML-RPC params chunk. To write a fault response, pass a
641 Fault instance instead. You may prefer to use the "dumps" module
642 function for this purpose.
645 # by the way, if you don't understand what's going on in here,
646 # that's perfectly ok.
648 def __init__(self
, encoding
=None, allow_none
=0):
651 self
.encoding
= encoding
652 self
.allow_none
= allow_none
656 def dumps(self
, values
):
660 if isinstance(values
, Fault
):
663 dump({'faultCode': values
.faultCode
,
664 'faultString': values
.faultString
},
669 # FIXME: the xml-rpc specification allows us to leave out
670 # the entire <params> block if there are no parameters.
671 # however, changing this may break older code (including
672 # old versions of xmlrpclib.py), so this is better left as
673 # is for now. See @XMLRPC3 for more information. /F
680 result
= string
.join(out
, "")
683 def __dump(self
, value
, write
):
685 f
= self
.dispatch
[type(value
)]
687 # check if this object can be marshalled as a structure
691 raise TypeError, "cannot marshal %s objects" % type(value
)
692 # check if this class is a sub-class of a basic type,
693 # because we don't know how to marshal these types
694 # (e.g. a string sub-class)
695 for type_
in type(value
).__mro
__:
696 if type_
in self
.dispatch
.keys():
697 raise TypeError, "cannot marshal %s objects" % type(value
)
698 f
= self
.dispatch
[InstanceType
]
699 f(self
, value
, write
)
701 def dump_nil (self
, value
, write
):
702 if not self
.allow_none
:
703 raise TypeError, "cannot marshal None unless allow_none is enabled"
704 write("<value><nil/></value>")
705 dispatch
[NoneType
] = dump_nil
707 def dump_int(self
, value
, write
):
708 # in case ints are > 32 bits
709 if value
> MAXINT
or value
< MININT
:
710 raise OverflowError, "int exceeds XML-RPC limits"
711 write("<value><int>")
713 write("</int></value>\n")
714 dispatch
[IntType
] = dump_int
717 def dump_bool(self
, value
, write
):
718 write("<value><boolean>")
719 write(value
and "1" or "0")
720 write("</boolean></value>\n")
721 dispatch
[bool] = dump_bool
723 def dump_long(self
, value
, write
):
724 if value
> MAXINT
or value
< MININT
:
725 raise OverflowError, "long int exceeds XML-RPC limits"
726 write("<value><int>")
727 write(str(int(value
)))
728 write("</int></value>\n")
729 dispatch
[LongType
] = dump_long
731 def dump_double(self
, value
, write
):
732 write("<value><double>")
734 write("</double></value>\n")
735 dispatch
[FloatType
] = dump_double
737 def dump_string(self
, value
, write
, escape
=escape
):
738 write("<value><string>")
740 write("</string></value>\n")
741 dispatch
[StringType
] = dump_string
744 def dump_unicode(self
, value
, write
, escape
=escape
):
745 value
= value
.encode(self
.encoding
)
746 write("<value><string>")
748 write("</string></value>\n")
749 dispatch
[UnicodeType
] = dump_unicode
751 def dump_array(self
, value
, write
):
754 raise TypeError, "cannot marshal recursive sequences"
757 write("<value><array><data>\n")
760 write("</data></array></value>\n")
762 dispatch
[TupleType
] = dump_array
763 dispatch
[ListType
] = dump_array
765 def dump_struct(self
, value
, write
, escape
=escape
):
768 raise TypeError, "cannot marshal recursive dictionaries"
771 write("<value><struct>\n")
772 for k
, v
in value
.items():
774 if type(k
) is not StringType
:
775 if unicode and type(k
) is UnicodeType
:
776 k
= k
.encode(self
.encoding
)
778 raise TypeError, "dictionary key must be string"
779 write("<name>%s</name>\n" % escape(k
))
782 write("</struct></value>\n")
784 dispatch
[DictType
] = dump_struct
787 def dump_datetime(self
, value
, write
):
788 write("<value><dateTime.iso8601>")
789 write(_strftime(value
))
790 write("</dateTime.iso8601></value>\n")
791 dispatch
[datetime
.datetime
] = dump_datetime
793 def dump_instance(self
, value
, write
):
794 # check for special wrappers
795 if value
.__class
__ in WRAPPERS
:
800 # store instance attributes as a struct (really?)
801 self
.dump_struct(value
.__dict
__, write
)
802 dispatch
[InstanceType
] = dump_instance
805 # XML-RPC unmarshaller.
810 """Unmarshal an XML-RPC response, based on incoming XML event
811 messages (start, data, end). Call close() to get the resulting
814 Note that this reader is fairly tolerant, and gladly accepts bogus
815 XML-RPC data without complaining (but not bogus XML).
818 # and again, if you don't understand what's going on in here,
819 # that's perfectly ok.
821 def __init__(self
, use_datetime
=0):
826 self
._methodname
= None
827 self
._encoding
= "utf-8"
828 self
.append
= self
._stack
.append
829 self
._use
_datetime
= use_datetime
830 if use_datetime
and not datetime
:
831 raise ValueError, "the datetime module is not available"
834 # return response tuple and target method
835 if self
._type
is None or self
._marks
:
836 raise ResponseError()
837 if self
._type
== "fault":
838 raise Fault(**self
._stack
[0])
839 return tuple(self
._stack
)
841 def getmethodname(self
):
842 return self
._methodname
847 def xml(self
, encoding
, standalone
):
848 self
._encoding
= encoding
849 # FIXME: assert standalone == 1 ???
851 def start(self
, tag
, attrs
):
852 # prepare to handle this element
853 if tag
== "array" or tag
== "struct":
854 self
._marks
.append(len(self
._stack
))
856 self
._value
= (tag
== "value")
858 def data(self
, text
):
859 self
._data
.append(text
)
861 def end(self
, tag
, join
=string
.join
):
862 # call the appropriate end tag handler
864 f
= self
.dispatch
[tag
]
868 return f(self
, join(self
._data
, ""))
871 # accelerator support
873 def end_dispatch(self
, tag
, data
):
876 f
= self
.dispatch
[tag
]
887 def end_nil (self
, data
):
890 dispatch
["nil"] = end_nil
892 def end_boolean(self
, data
):
898 raise TypeError, "bad boolean value"
900 dispatch
["boolean"] = end_boolean
902 def end_int(self
, data
):
903 self
.append(int(data
))
905 dispatch
["i4"] = end_int
906 dispatch
["i8"] = end_int
907 dispatch
["int"] = end_int
909 def end_double(self
, data
):
910 self
.append(float(data
))
912 dispatch
["double"] = end_double
914 def end_string(self
, data
):
916 data
= _decode(data
, self
._encoding
)
917 self
.append(_stringify(data
))
919 dispatch
["string"] = end_string
920 dispatch
["name"] = end_string
# struct keys are always strings
922 def end_array(self
, data
):
923 mark
= self
._marks
.pop()
924 # map arrays to Python lists
925 self
._stack
[mark
:] = [self
._stack
[mark
:]]
927 dispatch
["array"] = end_array
929 def end_struct(self
, data
):
930 mark
= self
._marks
.pop()
931 # map structs to Python dictionaries
933 items
= self
._stack
[mark
:]
934 for i
in range(0, len(items
), 2):
935 dict[_stringify(items
[i
])] = items
[i
+1]
936 self
._stack
[mark
:] = [dict]
938 dispatch
["struct"] = end_struct
940 def end_base64(self
, data
):
945 dispatch
["base64"] = end_base64
947 def end_dateTime(self
, data
):
950 if self
._use
_datetime
:
951 value
= _datetime_type(data
)
953 dispatch
["dateTime.iso8601"] = end_dateTime
955 def end_value(self
, data
):
956 # if we stumble upon a value element with no internal
957 # elements, treat it as a string element
959 self
.end_string(data
)
960 dispatch
["value"] = end_value
962 def end_params(self
, data
):
963 self
._type
= "params"
964 dispatch
["params"] = end_params
966 def end_fault(self
, data
):
968 dispatch
["fault"] = end_fault
970 def end_methodName(self
, data
):
972 data
= _decode(data
, self
._encoding
)
973 self
._methodname
= data
974 self
._type
= "methodName" # no params
975 dispatch
["methodName"] = end_methodName
980 class _MultiCallMethod
:
981 # some lesser magic to store calls made to a MultiCall object
982 # for batch execution
983 def __init__(self
, call_list
, name
):
984 self
.__call
_list
= call_list
986 def __getattr__(self
, name
):
987 return _MultiCallMethod(self
.__call
_list
, "%s.%s" % (self
.__name
, name
))
988 def __call__(self
, *args
):
989 self
.__call
_list
.append((self
.__name
, args
))
991 class MultiCallIterator
:
992 """Iterates over the results of a multicall. Exceptions are
993 thrown in response to xmlrpc faults."""
995 def __init__(self
, results
):
996 self
.results
= results
998 def __getitem__(self
, i
):
999 item
= self
.results
[i
]
1000 if type(item
) == type({}):
1001 raise Fault(item
['faultCode'], item
['faultString'])
1002 elif type(item
) == type([]):
1006 "unexpected type in multicall result"
1009 """server -> a object used to boxcar method calls
1011 server should be a ServerProxy object.
1013 Methods can be added to the MultiCall using normal
1014 method call syntax e.g.:
1016 multicall = MultiCall(server_proxy)
1018 multicall.get_address("Guido")
1020 To execute the multicall, call the MultiCall object e.g.:
1022 add_result, address = multicall()
1025 def __init__(self
, server
):
1026 self
.__server
= server
1027 self
.__call
_list
= []
1030 return "<MultiCall at %x>" % id(self
)
1034 def __getattr__(self
, name
):
1035 return _MultiCallMethod(self
.__call
_list
, name
)
1038 marshalled_list
= []
1039 for name
, args
in self
.__call
_list
:
1040 marshalled_list
.append({'methodName' : name
, 'params' : args
})
1042 return MultiCallIterator(self
.__server
.system
.multicall(marshalled_list
))
1044 # --------------------------------------------------------------------
1045 # convenience functions
1048 # Create a parser object, and connect it to an unmarshalling instance.
1049 # This function picks the fastest available XML parser.
1051 # return A (parser, unmarshaller) tuple.
1053 def getparser(use_datetime
=0):
1054 """getparser() -> parser, unmarshaller
1056 Create an instance of the fastest available parser, and attach it
1057 to an unmarshalling object. Return both objects.
1059 if use_datetime
and not datetime
:
1060 raise ValueError, "the datetime module is not available"
1061 if FastParser
and FastUnmarshaller
:
1063 mkdatetime
= _datetime_type
1065 mkdatetime
= _datetime
1066 target
= FastUnmarshaller(True, False, _binary
, mkdatetime
, Fault
)
1067 parser
= FastParser(target
)
1069 target
= Unmarshaller(use_datetime
=use_datetime
)
1071 parser
= FastParser(target
)
1073 parser
= SgmlopParser(target
)
1075 parser
= ExpatParser(target
)
1077 parser
= SlowParser(target
)
1078 return parser
, target
1081 # Convert a Python tuple or a Fault instance to an XML-RPC packet.
1083 # @def dumps(params, **options)
1084 # @param params A tuple or Fault instance.
1085 # @keyparam methodname If given, create a methodCall request for
1087 # @keyparam methodresponse If given, create a methodResponse packet.
1088 # If used with a tuple, the tuple must be a singleton (that is,
1089 # it must contain exactly one element).
1090 # @keyparam encoding The packet encoding.
1091 # @return A string containing marshalled data.
1093 def dumps(params
, methodname
=None, methodresponse
=None, encoding
=None,
1095 """data [,options] -> marshalled data
1097 Convert an argument tuple or a Fault instance to an XML-RPC
1098 request (or response, if the methodresponse option is used).
1100 In addition to the data object, the following options can be given
1101 as keyword arguments:
1103 methodname: the method name for a methodCall packet
1105 methodresponse: true to create a methodResponse packet.
1106 If this option is used with a tuple, the tuple must be
1107 a singleton (i.e. it can contain only one element).
1109 encoding: the packet encoding (default is UTF-8)
1111 All 8-bit strings in the data structure are assumed to use the
1112 packet encoding. Unicode strings are automatically converted,
1116 assert isinstance(params
, TupleType
) or isinstance(params
, Fault
),\
1117 "argument must be tuple or Fault instance"
1119 if isinstance(params
, Fault
):
1121 elif methodresponse
and isinstance(params
, TupleType
):
1122 assert len(params
) == 1, "response tuple must be a singleton"
1128 m
= FastMarshaller(encoding
)
1130 m
= Marshaller(encoding
, allow_none
)
1132 data
= m
.dumps(params
)
1134 if encoding
!= "utf-8":
1135 xmlheader
= "<?xml version='1.0' encoding='%s'?>\n" % str(encoding
)
1137 xmlheader
= "<?xml version='1.0'?>\n" # utf-8 is default
1139 # standard XML-RPC wrappings
1142 if not isinstance(methodname
, StringType
):
1143 methodname
= methodname
.encode(encoding
)
1147 "<methodName>", methodname
, "</methodName>\n",
1151 elif methodresponse
:
1152 # a method response, or a fault structure
1155 "<methodResponse>\n",
1157 "</methodResponse>\n"
1160 return data
# return as is
1161 return string
.join(data
, "")
1164 # Convert an XML-RPC packet to a Python object. If the XML-RPC packet
1165 # represents a fault condition, this function raises a Fault exception.
1167 # @param data An XML-RPC packet, given as an 8-bit string.
1168 # @return A tuple containing the unpacked data, and the method name
1169 # (None if not present).
1172 def loads(data
, use_datetime
=0):
1173 """data -> unmarshalled data, method name
1175 Convert an XML-RPC packet to unmarshalled data plus a method
1176 name (None if not present).
1178 If the XML-RPC packet represents a fault condition, this function
1179 raises a Fault exception.
1181 p
, u
= getparser(use_datetime
=use_datetime
)
1184 return u
.close(), u
.getmethodname()
1187 # --------------------------------------------------------------------
1188 # request dispatcher
1191 # some magic to bind an XML-RPC method to an RPC server.
1192 # supports "nested" methods (e.g. examples.getStateName)
1193 def __init__(self
, send
, name
):
1196 def __getattr__(self
, name
):
1197 return _Method(self
.__send
, "%s.%s" % (self
.__name
, name
))
1198 def __call__(self
, *args
):
1199 return self
.__send
(self
.__name
, args
)
1202 # Standard transport class for XML-RPC over HTTP.
1204 # You can create custom transports by subclassing this method, and
1205 # overriding selected methods.
1208 """Handles an HTTP transaction to an XML-RPC server."""
1210 # client identifier (may be overridden)
1211 user_agent
= "xmlrpclib.py/%s (by www.pythonware.com)" % __version__
1213 def __init__(self
, use_datetime
=0):
1214 self
._use
_datetime
= use_datetime
1217 # Send a complete request, and parse the response.
1219 # @param host Target host.
1220 # @param handler Target PRC handler.
1221 # @param request_body XML-RPC request body.
1222 # @param verbose Debugging flag.
1223 # @return Parsed response.
1225 def request(self
, host
, handler
, request_body
, verbose
=0):
1226 # issue XML-RPC request
1228 h
= self
.make_connection(host
)
1232 self
.send_request(h
, handler
, request_body
)
1233 self
.send_host(h
, host
)
1234 self
.send_user_agent(h
)
1235 self
.send_content(h
, request_body
)
1237 errcode
, errmsg
, headers
= h
.getreply(buffering
=True)
1240 raise ProtocolError(
1246 self
.verbose
= verbose
1248 return self
.parse_response(h
.getfile())
1253 # @return A 2-tuple containing a parser and a unmarshaller.
1255 def getparser(self
):
1256 # get parser and unmarshaller
1257 return getparser(use_datetime
=self
._use
_datetime
)
1260 # Get authorization info from host parameter
1261 # Host may be a string, or a (host, x509-dict) tuple; if a string,
1262 # it is checked for a "user:pw@host" format, and a "Basic
1263 # Authentication" header is added if appropriate.
1265 # @param host Host descriptor (URL or (URL, x509 info) tuple).
1266 # @return A 3-tuple containing (actual host, extra headers,
1267 # x509 info). The header and x509 fields may be None.
1269 def get_host_info(self
, host
):
1272 if isinstance(host
, TupleType
):
1276 auth
, host
= urllib
.splituser(host
)
1280 auth
= base64
.encodestring(urllib
.unquote(auth
))
1281 auth
= string
.join(string
.split(auth
), "") # get rid of whitespace
1283 ("Authorization", "Basic " + auth
)
1286 extra_headers
= None
1288 return host
, extra_headers
, x509
1291 # Connect to server.
1293 # @param host Target host.
1294 # @return A connection handle.
1296 def make_connection(self
, host
):
1297 # create a HTTP connection object from a host descriptor
1299 host
, extra_headers
, x509
= self
.get_host_info(host
)
1300 return httplib
.HTTP(host
)
1303 # Send request header.
1305 # @param connection Connection handle.
1306 # @param handler Target RPC handler.
1307 # @param request_body XML-RPC body.
1309 def send_request(self
, connection
, handler
, request_body
):
1310 connection
.putrequest("POST", handler
)
1315 # @param connection Connection handle.
1316 # @param host Host name.
1318 def send_host(self
, connection
, host
):
1319 host
, extra_headers
, x509
= self
.get_host_info(host
)
1320 connection
.putheader("Host", host
)
1322 if isinstance(extra_headers
, DictType
):
1323 extra_headers
= extra_headers
.items()
1324 for key
, value
in extra_headers
:
1325 connection
.putheader(key
, value
)
1328 # Send user-agent identifier.
1330 # @param connection Connection handle.
1332 def send_user_agent(self
, connection
):
1333 connection
.putheader("User-Agent", self
.user_agent
)
1336 # Send request body.
1338 # @param connection Connection handle.
1339 # @param request_body XML-RPC request body.
1341 def send_content(self
, connection
, request_body
):
1342 connection
.putheader("Content-Type", "text/xml")
1343 connection
.putheader("Content-Length", str(len(request_body
)))
1344 connection
.endheaders(request_body
)
1349 # @param file Stream.
1350 # @return Response tuple and target method.
1352 def parse_response(self
, file):
1353 # read response from input file/socket, and parse it
1355 p
, u
= self
.getparser()
1358 response
= file.read(1024)
1362 print "body:", repr(response
)
1371 # Standard transport class for XML-RPC over HTTPS.
1373 class SafeTransport(Transport
):
1374 """Handles an HTTPS transaction to an XML-RPC server."""
1376 # FIXME: mostly untested
1378 def make_connection(self
, host
):
1379 # create a HTTPS connection object from a host descriptor
1380 # host may be a string, or a (host, x509-dict) tuple
1382 host
, extra_headers
, x509
= self
.get_host_info(host
)
1384 HTTPS
= httplib
.HTTPS
1385 except AttributeError:
1386 raise NotImplementedError(
1387 "your version of httplib doesn't support HTTPS"
1390 return HTTPS(host
, None, **(x509
or {}))
1393 # Standard server proxy. This class establishes a virtual connection
1394 # to an XML-RPC server.
1396 # This class is available as ServerProxy and Server. New code should
1397 # use ServerProxy, to avoid confusion.
1399 # @def ServerProxy(uri, **options)
1400 # @param uri The connection point on the server.
1401 # @keyparam transport A transport factory, compatible with the
1402 # standard transport class.
1403 # @keyparam encoding The default encoding used for 8-bit strings
1404 # (default is UTF-8).
1405 # @keyparam verbose Use a true value to enable debugging output.
1406 # (printed to standard output).
1410 """uri [,options] -> a logical connection to an XML-RPC server
1412 uri is the connection point on the server, given as
1413 scheme://host/target.
1415 The standard implementation always supports the "http" scheme. If
1416 SSL socket support is available (Python 2.0), it also supports
1419 If the target part and the slash preceding it are both omitted,
1422 The following options can be given as keyword arguments:
1424 transport: a transport factory
1425 encoding: the request encoding (default is UTF-8)
1427 All 8-bit strings passed to the server proxy are assumed to use
1431 def __init__(self
, uri
, transport
=None, encoding
=None, verbose
=0,
1432 allow_none
=0, use_datetime
=0):
1433 # establish a "logical" server connection
1437 type, uri
= urllib
.splittype(uri
)
1438 if type not in ("http", "https"):
1439 raise IOError, "unsupported XML-RPC protocol"
1440 self
.__host
, self
.__handler
= urllib
.splithost(uri
)
1441 if not self
.__handler
:
1442 self
.__handler
= "/RPC2"
1444 if transport
is None:
1446 transport
= SafeTransport(use_datetime
=use_datetime
)
1448 transport
= Transport(use_datetime
=use_datetime
)
1449 self
.__transport
= transport
1451 self
.__encoding
= encoding
1452 self
.__verbose
= verbose
1453 self
.__allow
_none
= allow_none
1455 def __request(self
, methodname
, params
):
1456 # call a method on the remote server
1458 request
= dumps(params
, methodname
, encoding
=self
.__encoding
,
1459 allow_none
=self
.__allow
_none
)
1461 response
= self
.__transport
.request(
1465 verbose
=self
.__verbose
1468 if len(response
) == 1:
1469 response
= response
[0]
1475 "<ServerProxy for %s%s>" %
1476 (self
.__host
, self
.__handler
)
1481 def __getattr__(self
, name
):
1482 # magic method dispatcher
1483 return _Method(self
.__request
, name
)
1485 # note: to call a remote object with an non-standard name, use
1486 # result getattr(server, "strange-python-name")(args)
1490 Server
= ServerProxy
1492 # --------------------------------------------------------------------
1495 if __name__
== "__main__":
1497 # simple test program (from the XML-RPC specification)
1499 # server = ServerProxy("http://localhost:8000") # local server
1500 server
= ServerProxy("http://time.xmlrpc.com/RPC2")
1505 print server
.currentTime
.getCurrentTime()
1509 multi
= MultiCall(server
)
1510 multi
.currentTime
.getCurrentTime()
1511 multi
.currentTime
.getCurrentTime()
1513 for response
in multi():