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 from xml
.parsers
import expat
531 if not hasattr(expat
, "ParserCreate"):
534 ExpatParser
= None # expat not available
537 # fast expat parser for Python 2.0 and later.
538 def __init__(self
, target
):
539 self
._parser
= parser
= expat
.ParserCreate(None, None)
540 self
._target
= target
541 parser
.StartElementHandler
= target
.start
542 parser
.EndElementHandler
= target
.end
543 parser
.CharacterDataHandler
= target
.data
545 if not parser
.returns_unicode
:
547 target
.xml(encoding
, None)
549 def feed(self
, data
):
550 self
._parser
.Parse(data
, 0)
553 self
._parser
.Parse("", 1) # end of data
554 del self
._target
, self
._parser
# get rid of circular references
557 """Default XML parser (based on xmllib.XMLParser)."""
558 # this is the slowest parser.
559 def __init__(self
, target
):
560 import xmllib
# lazy subclassing (!)
561 if xmllib
.XMLParser
not in SlowParser
.__bases
__:
562 SlowParser
.__bases
__ = (xmllib
.XMLParser
,)
563 self
.handle_xml
= target
.xml
564 self
.unknown_starttag
= target
.start
565 self
.handle_data
= target
.data
566 self
.handle_cdata
= target
.data
567 self
.unknown_endtag
= target
.end
569 xmllib
.XMLParser
.__init
__(self
, accept_utf8
=1)
571 xmllib
.XMLParser
.__init
__(self
) # pre-2.0
573 # --------------------------------------------------------------------
574 # XML-RPC marshalling and unmarshalling code
577 # XML-RPC marshaller.
579 # @param encoding Default encoding for 8-bit strings. The default
580 # value is None (interpreted as UTF-8).
584 """Generate an XML-RPC params chunk from a Python data structure.
586 Create a Marshaller instance for each set of parameters, and use
587 the "dumps" method to convert your data (represented as a tuple)
588 to an XML-RPC params chunk. To write a fault response, pass a
589 Fault instance instead. You may prefer to use the "dumps" module
590 function for this purpose.
593 # by the way, if you don't understand what's going on in here,
594 # that's perfectly ok.
596 def __init__(self
, encoding
=None, allow_none
=0):
599 self
.encoding
= encoding
600 self
.allow_none
= allow_none
604 def dumps(self
, values
):
608 if isinstance(values
, Fault
):
611 dump({'faultCode': values
.faultCode
,
612 'faultString': values
.faultString
},
617 # FIXME: the xml-rpc specification allows us to leave out
618 # the entire <params> block if there are no parameters.
619 # however, changing this may break older code (including
620 # old versions of xmlrpclib.py), so this is better left as
621 # is for now. See @XMLRPC3 for more information. /F
628 result
= string
.join(out
, "")
631 def __dump(self
, value
, write
):
633 f
= self
.dispatch
[type(value
)]
635 # check if this object can be marshalled as a structure
639 raise TypeError, "cannot marshal %s objects" % type(value
)
640 # check if this class is a sub-class of a basic type,
641 # because we don't know how to marshal these types
642 # (e.g. a string sub-class)
643 for type_
in type(value
).__mro
__:
644 if type_
in self
.dispatch
.keys():
645 raise TypeError, "cannot marshal %s objects" % type(value
)
646 f
= self
.dispatch
[InstanceType
]
647 f(self
, value
, write
)
649 def dump_nil (self
, value
, write
):
650 if not self
.allow_none
:
651 raise TypeError, "cannot marshal None unless allow_none is enabled"
652 write("<value><nil/></value>")
653 dispatch
[NoneType
] = dump_nil
655 def dump_int(self
, value
, write
):
656 # in case ints are > 32 bits
657 if value
> MAXINT
or value
< MININT
:
658 raise OverflowError, "int exceeds XML-RPC limits"
659 write("<value><int>")
661 write("</int></value>\n")
662 dispatch
[IntType
] = dump_int
665 def dump_bool(self
, value
, write
):
666 write("<value><boolean>")
667 write(value
and "1" or "0")
668 write("</boolean></value>\n")
669 dispatch
[bool] = dump_bool
671 def dump_long(self
, value
, write
):
672 if value
> MAXINT
or value
< MININT
:
673 raise OverflowError, "long int exceeds XML-RPC limits"
674 write("<value><int>")
675 write(str(int(value
)))
676 write("</int></value>\n")
677 dispatch
[LongType
] = dump_long
679 def dump_double(self
, value
, write
):
680 write("<value><double>")
682 write("</double></value>\n")
683 dispatch
[FloatType
] = dump_double
685 def dump_string(self
, value
, write
, escape
=escape
):
686 write("<value><string>")
688 write("</string></value>\n")
689 dispatch
[StringType
] = dump_string
692 def dump_unicode(self
, value
, write
, escape
=escape
):
693 value
= value
.encode(self
.encoding
)
694 write("<value><string>")
696 write("</string></value>\n")
697 dispatch
[UnicodeType
] = dump_unicode
699 def dump_array(self
, value
, write
):
702 raise TypeError, "cannot marshal recursive sequences"
705 write("<value><array><data>\n")
708 write("</data></array></value>\n")
710 dispatch
[TupleType
] = dump_array
711 dispatch
[ListType
] = dump_array
713 def dump_struct(self
, value
, write
, escape
=escape
):
716 raise TypeError, "cannot marshal recursive dictionaries"
719 write("<value><struct>\n")
720 for k
, v
in value
.items():
722 if type(k
) is not StringType
:
723 if unicode and type(k
) is UnicodeType
:
724 k
= k
.encode(self
.encoding
)
726 raise TypeError, "dictionary key must be string"
727 write("<name>%s</name>\n" % escape(k
))
730 write("</struct></value>\n")
732 dispatch
[DictType
] = dump_struct
735 def dump_datetime(self
, value
, write
):
736 write("<value><dateTime.iso8601>")
737 write(_strftime(value
))
738 write("</dateTime.iso8601></value>\n")
739 dispatch
[datetime
.datetime
] = dump_datetime
741 def dump_instance(self
, value
, write
):
742 # check for special wrappers
743 if value
.__class
__ in WRAPPERS
:
748 # store instance attributes as a struct (really?)
749 self
.dump_struct(value
.__dict
__, write
)
750 dispatch
[InstanceType
] = dump_instance
753 # XML-RPC unmarshaller.
758 """Unmarshal an XML-RPC response, based on incoming XML event
759 messages (start, data, end). Call close() to get the resulting
762 Note that this reader is fairly tolerant, and gladly accepts bogus
763 XML-RPC data without complaining (but not bogus XML).
766 # and again, if you don't understand what's going on in here,
767 # that's perfectly ok.
769 def __init__(self
, use_datetime
=0):
774 self
._methodname
= None
775 self
._encoding
= "utf-8"
776 self
.append
= self
._stack
.append
777 self
._use
_datetime
= use_datetime
778 if use_datetime
and not datetime
:
779 raise ValueError, "the datetime module is not available"
782 # return response tuple and target method
783 if self
._type
is None or self
._marks
:
784 raise ResponseError()
785 if self
._type
== "fault":
786 raise Fault(**self
._stack
[0])
787 return tuple(self
._stack
)
789 def getmethodname(self
):
790 return self
._methodname
795 def xml(self
, encoding
, standalone
):
796 self
._encoding
= encoding
797 # FIXME: assert standalone == 1 ???
799 def start(self
, tag
, attrs
):
800 # prepare to handle this element
801 if tag
== "array" or tag
== "struct":
802 self
._marks
.append(len(self
._stack
))
804 self
._value
= (tag
== "value")
806 def data(self
, text
):
807 self
._data
.append(text
)
809 def end(self
, tag
, join
=string
.join
):
810 # call the appropriate end tag handler
812 f
= self
.dispatch
[tag
]
816 return f(self
, join(self
._data
, ""))
819 # accelerator support
821 def end_dispatch(self
, tag
, data
):
824 f
= self
.dispatch
[tag
]
835 def end_nil (self
, data
):
838 dispatch
["nil"] = end_nil
840 def end_boolean(self
, data
):
846 raise TypeError, "bad boolean value"
848 dispatch
["boolean"] = end_boolean
850 def end_int(self
, data
):
851 self
.append(int(data
))
853 dispatch
["i4"] = end_int
854 dispatch
["i8"] = end_int
855 dispatch
["int"] = end_int
857 def end_double(self
, data
):
858 self
.append(float(data
))
860 dispatch
["double"] = end_double
862 def end_string(self
, data
):
864 data
= _decode(data
, self
._encoding
)
865 self
.append(_stringify(data
))
867 dispatch
["string"] = end_string
868 dispatch
["name"] = end_string
# struct keys are always strings
870 def end_array(self
, data
):
871 mark
= self
._marks
.pop()
872 # map arrays to Python lists
873 self
._stack
[mark
:] = [self
._stack
[mark
:]]
875 dispatch
["array"] = end_array
877 def end_struct(self
, data
):
878 mark
= self
._marks
.pop()
879 # map structs to Python dictionaries
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]
886 dispatch
["struct"] = end_struct
888 def end_base64(self
, data
):
893 dispatch
["base64"] = end_base64
895 def end_dateTime(self
, data
):
898 if self
._use
_datetime
:
899 value
= _datetime_type(data
)
901 dispatch
["dateTime.iso8601"] = end_dateTime
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
907 self
.end_string(data
)
908 dispatch
["value"] = end_value
910 def end_params(self
, data
):
911 self
._type
= "params"
912 dispatch
["params"] = end_params
914 def end_fault(self
, data
):
916 dispatch
["fault"] = end_fault
918 def end_methodName(self
, data
):
920 data
= _decode(data
, self
._encoding
)
921 self
._methodname
= data
922 self
._type
= "methodName" # no params
923 dispatch
["methodName"] = end_methodName
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
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
))
939 class MultiCallIterator
:
940 """Iterates over the results of a multicall. Exceptions are
941 thrown in response to xmlrpc faults."""
943 def __init__(self
, results
):
944 self
.results
= results
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([]):
954 "unexpected type in multicall result"
957 """server -> a object used to boxcar method calls
959 server should be a ServerProxy object.
961 Methods can be added to the MultiCall using normal
962 method call syntax e.g.:
964 multicall = MultiCall(server_proxy)
966 multicall.get_address("Guido")
968 To execute the multicall, call the MultiCall object e.g.:
970 add_result, address = multicall()
973 def __init__(self
, server
):
974 self
.__server
= server
975 self
.__call
_list
= []
978 return "<MultiCall at %x>" % id(self
)
982 def __getattr__(self
, name
):
983 return _MultiCallMethod(self
.__call
_list
, name
)
987 for name
, args
in self
.__call
_list
:
988 marshalled_list
.append({'methodName' : name
, 'params' : args
})
990 return MultiCallIterator(self
.__server
.system
.multicall(marshalled_list
))
992 # --------------------------------------------------------------------
993 # convenience functions
996 # Create a parser object, and connect it to an unmarshalling instance.
997 # This function picks the fastest available XML parser.
999 # return A (parser, unmarshaller) tuple.
1001 def getparser(use_datetime
=0):
1002 """getparser() -> parser, unmarshaller
1004 Create an instance of the fastest available parser, and attach it
1005 to an unmarshalling object. Return both objects.
1007 if use_datetime
and not datetime
:
1008 raise ValueError, "the datetime module is not available"
1009 if FastParser
and FastUnmarshaller
:
1011 mkdatetime
= _datetime_type
1013 mkdatetime
= _datetime
1014 target
= FastUnmarshaller(True, False, _binary
, mkdatetime
, Fault
)
1015 parser
= FastParser(target
)
1017 target
= Unmarshaller(use_datetime
=use_datetime
)
1019 parser
= FastParser(target
)
1021 parser
= ExpatParser(target
)
1023 parser
= SlowParser(target
)
1024 return parser
, target
1027 # Convert a Python tuple or a Fault instance to an XML-RPC packet.
1029 # @def dumps(params, **options)
1030 # @param params A tuple or Fault instance.
1031 # @keyparam methodname If given, create a methodCall request for
1033 # @keyparam methodresponse If given, create a methodResponse packet.
1034 # If used with a tuple, the tuple must be a singleton (that is,
1035 # it must contain exactly one element).
1036 # @keyparam encoding The packet encoding.
1037 # @return A string containing marshalled data.
1039 def dumps(params
, methodname
=None, methodresponse
=None, encoding
=None,
1041 """data [,options] -> marshalled data
1043 Convert an argument tuple or a Fault instance to an XML-RPC
1044 request (or response, if the methodresponse option is used).
1046 In addition to the data object, the following options can be given
1047 as keyword arguments:
1049 methodname: the method name for a methodCall packet
1051 methodresponse: true to create a methodResponse packet.
1052 If this option is used with a tuple, the tuple must be
1053 a singleton (i.e. it can contain only one element).
1055 encoding: the packet encoding (default is UTF-8)
1057 All 8-bit strings in the data structure are assumed to use the
1058 packet encoding. Unicode strings are automatically converted,
1062 assert isinstance(params
, TupleType
) or isinstance(params
, Fault
),\
1063 "argument must be tuple or Fault instance"
1065 if isinstance(params
, Fault
):
1067 elif methodresponse
and isinstance(params
, TupleType
):
1068 assert len(params
) == 1, "response tuple must be a singleton"
1074 m
= FastMarshaller(encoding
)
1076 m
= Marshaller(encoding
, allow_none
)
1078 data
= m
.dumps(params
)
1080 if encoding
!= "utf-8":
1081 xmlheader
= "<?xml version='1.0' encoding='%s'?>\n" % str(encoding
)
1083 xmlheader
= "<?xml version='1.0'?>\n" # utf-8 is default
1085 # standard XML-RPC wrappings
1088 if not isinstance(methodname
, StringType
):
1089 methodname
= methodname
.encode(encoding
)
1093 "<methodName>", methodname
, "</methodName>\n",
1097 elif methodresponse
:
1098 # a method response, or a fault structure
1101 "<methodResponse>\n",
1103 "</methodResponse>\n"
1106 return data
# return as is
1107 return string
.join(data
, "")
1110 # Convert an XML-RPC packet to a Python object. If the XML-RPC packet
1111 # represents a fault condition, this function raises a Fault exception.
1113 # @param data An XML-RPC packet, given as an 8-bit string.
1114 # @return A tuple containing the unpacked data, and the method name
1115 # (None if not present).
1118 def loads(data
, use_datetime
=0):
1119 """data -> unmarshalled data, method name
1121 Convert an XML-RPC packet to unmarshalled data plus a method
1122 name (None if not present).
1124 If the XML-RPC packet represents a fault condition, this function
1125 raises a Fault exception.
1127 p
, u
= getparser(use_datetime
=use_datetime
)
1130 return u
.close(), u
.getmethodname()
1133 # --------------------------------------------------------------------
1134 # request dispatcher
1137 # some magic to bind an XML-RPC method to an RPC server.
1138 # supports "nested" methods (e.g. examples.getStateName)
1139 def __init__(self
, send
, name
):
1142 def __getattr__(self
, name
):
1143 return _Method(self
.__send
, "%s.%s" % (self
.__name
, name
))
1144 def __call__(self
, *args
):
1145 return self
.__send
(self
.__name
, args
)
1148 # Standard transport class for XML-RPC over HTTP.
1150 # You can create custom transports by subclassing this method, and
1151 # overriding selected methods.
1154 """Handles an HTTP transaction to an XML-RPC server."""
1156 # client identifier (may be overridden)
1157 user_agent
= "xmlrpclib.py/%s (by www.pythonware.com)" % __version__
1159 def __init__(self
, use_datetime
=0):
1160 self
._use
_datetime
= use_datetime
1163 # Send a complete request, and parse the response.
1165 # @param host Target host.
1166 # @param handler Target PRC handler.
1167 # @param request_body XML-RPC request body.
1168 # @param verbose Debugging flag.
1169 # @return Parsed response.
1171 def request(self
, host
, handler
, request_body
, verbose
=0):
1172 # issue XML-RPC request
1174 h
= self
.make_connection(host
)
1178 self
.send_request(h
, handler
, request_body
)
1179 self
.send_host(h
, host
)
1180 self
.send_user_agent(h
)
1181 self
.send_content(h
, request_body
)
1183 errcode
, errmsg
, headers
= h
.getreply(buffering
=True)
1186 raise ProtocolError(
1192 self
.verbose
= verbose
1194 return self
.parse_response(h
.getfile())
1199 # @return A 2-tuple containing a parser and a unmarshaller.
1201 def getparser(self
):
1202 # get parser and unmarshaller
1203 return getparser(use_datetime
=self
._use
_datetime
)
1206 # Get authorization info from host parameter
1207 # Host may be a string, or a (host, x509-dict) tuple; if a string,
1208 # it is checked for a "user:pw@host" format, and a "Basic
1209 # Authentication" header is added if appropriate.
1211 # @param host Host descriptor (URL or (URL, x509 info) tuple).
1212 # @return A 3-tuple containing (actual host, extra headers,
1213 # x509 info). The header and x509 fields may be None.
1215 def get_host_info(self
, host
):
1218 if isinstance(host
, TupleType
):
1222 auth
, host
= urllib
.splituser(host
)
1226 auth
= base64
.encodestring(urllib
.unquote(auth
))
1227 auth
= string
.join(string
.split(auth
), "") # get rid of whitespace
1229 ("Authorization", "Basic " + auth
)
1232 extra_headers
= None
1234 return host
, extra_headers
, x509
1237 # Connect to server.
1239 # @param host Target host.
1240 # @return A connection handle.
1242 def make_connection(self
, host
):
1243 # create a HTTP connection object from a host descriptor
1245 host
, extra_headers
, x509
= self
.get_host_info(host
)
1246 return httplib
.HTTP(host
)
1249 # Send request header.
1251 # @param connection Connection handle.
1252 # @param handler Target RPC handler.
1253 # @param request_body XML-RPC body.
1255 def send_request(self
, connection
, handler
, request_body
):
1256 connection
.putrequest("POST", handler
)
1261 # @param connection Connection handle.
1262 # @param host Host name.
1264 def send_host(self
, connection
, host
):
1265 host
, extra_headers
, x509
= self
.get_host_info(host
)
1266 connection
.putheader("Host", host
)
1268 if isinstance(extra_headers
, DictType
):
1269 extra_headers
= extra_headers
.items()
1270 for key
, value
in extra_headers
:
1271 connection
.putheader(key
, value
)
1274 # Send user-agent identifier.
1276 # @param connection Connection handle.
1278 def send_user_agent(self
, connection
):
1279 connection
.putheader("User-Agent", self
.user_agent
)
1282 # Send request body.
1284 # @param connection Connection handle.
1285 # @param request_body XML-RPC request body.
1287 def send_content(self
, connection
, request_body
):
1288 connection
.putheader("Content-Type", "text/xml")
1289 connection
.putheader("Content-Length", str(len(request_body
)))
1290 connection
.endheaders(request_body
)
1295 # @param file Stream.
1296 # @return Response tuple and target method.
1298 def parse_response(self
, file):
1299 # read response from input file/socket, and parse it
1301 p
, u
= self
.getparser()
1304 response
= file.read(1024)
1308 print "body:", repr(response
)
1317 # Standard transport class for XML-RPC over HTTPS.
1319 class SafeTransport(Transport
):
1320 """Handles an HTTPS transaction to an XML-RPC server."""
1322 # FIXME: mostly untested
1324 def make_connection(self
, host
):
1325 # create a HTTPS connection object from a host descriptor
1326 # host may be a string, or a (host, x509-dict) tuple
1328 host
, extra_headers
, x509
= self
.get_host_info(host
)
1330 HTTPS
= httplib
.HTTPS
1331 except AttributeError:
1332 raise NotImplementedError(
1333 "your version of httplib doesn't support HTTPS"
1336 return HTTPS(host
, None, **(x509
or {}))
1339 # Standard server proxy. This class establishes a virtual connection
1340 # to an XML-RPC server.
1342 # This class is available as ServerProxy and Server. New code should
1343 # use ServerProxy, to avoid confusion.
1345 # @def ServerProxy(uri, **options)
1346 # @param uri The connection point on the server.
1347 # @keyparam transport A transport factory, compatible with the
1348 # standard transport class.
1349 # @keyparam encoding The default encoding used for 8-bit strings
1350 # (default is UTF-8).
1351 # @keyparam verbose Use a true value to enable debugging output.
1352 # (printed to standard output).
1356 """uri [,options] -> a logical connection to an XML-RPC server
1358 uri is the connection point on the server, given as
1359 scheme://host/target.
1361 The standard implementation always supports the "http" scheme. If
1362 SSL socket support is available (Python 2.0), it also supports
1365 If the target part and the slash preceding it are both omitted,
1368 The following options can be given as keyword arguments:
1370 transport: a transport factory
1371 encoding: the request encoding (default is UTF-8)
1373 All 8-bit strings passed to the server proxy are assumed to use
1377 def __init__(self
, uri
, transport
=None, encoding
=None, verbose
=0,
1378 allow_none
=0, use_datetime
=0):
1379 # establish a "logical" server connection
1383 type, uri
= urllib
.splittype(uri
)
1384 if type not in ("http", "https"):
1385 raise IOError, "unsupported XML-RPC protocol"
1386 self
.__host
, self
.__handler
= urllib
.splithost(uri
)
1387 if not self
.__handler
:
1388 self
.__handler
= "/RPC2"
1390 if transport
is None:
1392 transport
= SafeTransport(use_datetime
=use_datetime
)
1394 transport
= Transport(use_datetime
=use_datetime
)
1395 self
.__transport
= transport
1397 self
.__encoding
= encoding
1398 self
.__verbose
= verbose
1399 self
.__allow
_none
= allow_none
1401 def __request(self
, methodname
, params
):
1402 # call a method on the remote server
1404 request
= dumps(params
, methodname
, encoding
=self
.__encoding
,
1405 allow_none
=self
.__allow
_none
)
1407 response
= self
.__transport
.request(
1411 verbose
=self
.__verbose
1414 if len(response
) == 1:
1415 response
= response
[0]
1421 "<ServerProxy for %s%s>" %
1422 (self
.__host
, self
.__handler
)
1427 def __getattr__(self
, name
):
1428 # magic method dispatcher
1429 return _Method(self
.__request
, name
)
1431 # note: to call a remote object with an non-standard name, use
1432 # result getattr(server, "strange-python-name")(args)
1436 Server
= ServerProxy
1438 # --------------------------------------------------------------------
1441 if __name__
== "__main__":
1443 # simple test program (from the XML-RPC specification)
1445 # server = ServerProxy("http://localhost:8000") # local server
1446 server
= ServerProxy("http://time.xmlrpc.com/RPC2")
1451 print server
.currentTime
.getCurrentTime()
1455 multi
= MultiCall(server
)
1456 multi
.currentTime
.getCurrentTime()
1457 multi
.currentTime
.getCurrentTime()
1459 for response
in multi():