[Python-checkins] CVS: python/dist/src/Lib xmlrpclib.py,1.4,1.5

2001年9月04日 11:55:05 -0700

Update of /cvsroot/python/python/dist/src/Lib
In directory usw-pr-cvs1:/tmp/cvs-serv25002
Modified Files:
	xmlrpclib.py 
Log Message:
Added docstring by Neal Norwitz. This closes SF bug #450981.
Index: xmlrpclib.py
===================================================================
RCS file: /cvsroot/python/python/dist/src/Lib/xmlrpclib.py,v
retrieving revision 1.4
retrieving revision 1.5
diff -C2 -d -r1.4 -r1.5
*** xmlrpclib.py	2001年08月23日 20:13:08	1.4
--- xmlrpclib.py	2001年09月04日 18:55:03	1.5
***************
*** 3,17 ****
 # $Id$
 #
- # an XML-RPC client interface for Python.
- #
- # the marshalling and response parser code can also be used to
- # implement XML-RPC servers.
- #
- # Notes:
- # this version is designed to work with Python 1.5.2 or newer.
- # unicode encoding support requires at least Python 1.6.
- # experimental HTTPS requires Python 2.0 built with SSL sockets.
- # expat parser support requires Python 2.0 with pyexpat support.
- #
 # History:
 # 1999年01月14日 fl Created
--- 3,6 ----
***************
*** 88,91 ****
--- 77,135 ----
 # TODO: memo problem (see HP's mail)

+ """
+ An XML-RPC client interface for Python.
+ 
+ The marshalling and response parser code can also be used to
+ implement XML-RPC servers.
+ 
+ Notes:
+ This version is designed to work with Python 1.5.2 or newer.
+ Unicode encoding support requires at least Python 1.6.
+ Experimental HTTPS requires Python 2.0 built with SSL sockets.
+ Expat parser support requires Python 2.0 with pyexpat support.
+ 
+ Exported exceptions:
+ 
+ Error Base class for client errors
+ ProtocolError Indicates an HTTP protocol error
+ ResponseError Indicates a broken response package
+ Fault Indicates a XML-RPC fault package
+ 
+ Exported classes:
+ 
+ Boolean boolean wrapper to generate a "boolean" XML-RPC value
+ DateTime dateTime wrapper for an ISO 8601 string or time tuple or
+ localtime integer value to generate a "dateTime.iso8601"
+ XML-RPC value
+ Binary binary data wrapper
+ 
+ SlowParser Slow but safe standard parser
+ Marshaller Generate an XML-RPC params chunk from a Python data structure
+ Unmarshaller Unmarshal an XML-RPC response from incoming XML event message
+ 
+ Transport Handles an HTTP transaction to an XML-RPC server
+ SafeTransport Handles an HTTPS transaction to an XML-RPC server
+ ServerProxy Connect to a server through a proxy
+ Server Same as ServerProxy
+ 
+ Exported constants:
+ 
+ True
+ False
+ 
+ Exported functions:
+ 
+ boolean Convert any Python value to an XML-RPC boolean
+ datetime Convert value to an XML-RPC datetime
+ binary Convert value to an XML-RPC binary value
+ getparser Create instance of the fastest available parser & attach
+ to an unmarshalling object
+ dumps Convert an argument tuple or a Fault instance to an XML-RPC
+ request (or response, if the methodresponse option is used).
+ loads Convert an XML-RPC packet to unmarshalled data plus a method
+ name (None if not present).
+ 
+ """
+ 
 import re, string, time, operator
 import urllib, xmllib
***************
*** 121,129 ****

 class Error(Exception):
! # base class for client errors
 pass

 class ProtocolError(Error):
! # indicates an HTTP protocol error
 def __init__(self, url, errcode, errmsg, headers):
 self.url = url
--- 165,173 ----

 class Error(Exception):
! """Base class for client errors."""
 pass

 class ProtocolError(Error):
! """Indicates an HTTP protocol error."""
 def __init__(self, url, errcode, errmsg, headers):
 self.url = url
***************
*** 138,146 ****

 class ResponseError(Error):
! # indicates a broken response package
 pass

 class Fault(Error):
! # indicates a XML-RPC fault package
 def __init__(self, faultCode, faultString, **extra):
 self.faultCode = faultCode
--- 182,190 ----

 class ResponseError(Error):
! """Indicates a broken response package"""
 pass

 class Fault(Error):
! """indicates a XML-RPC fault package"""
 def __init__(self, faultCode, faultString, **extra):
 self.faultCode = faultCode
***************
*** 155,162 ****
 # Special values

- # boolean wrapper
- # use True or False to generate a "boolean" XML-RPC value

 class Boolean:

 def __init__(self, value = 0):
--- 199,208 ----
 # Special values

 class Boolean:
+ """Boolean-value wrapper.
+ 
+ Use True or False to generate a "boolean" XML-RPC value.
+ """

 def __init__(self, value = 0):
***************
*** 186,190 ****

 def boolean(value, truefalse=(False, True)):
! # convert any Python value to XML-RPC boolean
 return truefalse[operator.truth(value)]

--- 232,236 ----

 def boolean(value, truefalse=(False, True)):
! """Convert any Python value to XML-RPC boolean."""
 return truefalse[operator.truth(value)]

***************
*** 195,198 ****
--- 241,247 ----

 class DateTime:
+ """DataTime wrapper for an ISO 8601 string or time tuple or
+ localtime integer value to generate a 'dateTime.iso8601' XML-RPC
+ value."""

 def __init__(self, value=0):
***************
*** 226,233 ****
 return value

- #
- # binary data wrapper

 class Binary:

 def __init__(self, data=None):
--- 275,281 ----
 return value

 class Binary:
+ """Wrapper for binary data."""

 def __init__(self, data=None):
***************
*** 345,351 ****

 class SlowParser(xmllib.XMLParser):
! # slow but safe standard parser, based on the XML parser in
! # Python's standard library. this is about 10 times slower
! # than sgmlop, on roundtrip testing.
 def __init__(self, target):
 self.handle_xml = target.xml
--- 393,401 ----

 class SlowParser(xmllib.XMLParser):
! """XML parser using xmllib.XMLParser.
! 
! This is about 10 times slower than sgmlop on roundtrip testing.
! """
! 
 def __init__(self, target):
 self.handle_xml = target.xml
***************
*** 360,370 ****

 class Marshaller:
! """Generate an XML-RPC params chunk from a Python data structure"""

! # USAGE: create a marshaller instance for each set of parameters,
! # and use "dumps" to convert your data (represented as a tuple) to
! # a XML-RPC params chunk. to write a fault response, pass a Fault
! # instance instead. you may prefer to use the "dumps" convenience
! # function for this purpose (see below).

 # by the way, if you don't understand what's going on in here,
--- 410,421 ----

 class Marshaller:
! """Generate an XML-RPC params chunk from a Python data structure.

! Create a marshaller instance for each set of parameters, and use
! "dumps" method to convert your data (represented as a tuple) to a
! XML-RPC params chunk. to write a fault response, pass a Fault
! instance instead. You may prefer to use the "dumps" convenience
! function for this purpose (see below).
! """

 # by the way, if you don't understand what's going on in here,
***************
*** 470,480 ****

 class Unmarshaller:
! 
! # unmarshal an XML-RPC response, based on incoming XML event
! # messages (start, data, end). call close to get the resulting
! # data structure

! # note that this reader is fairly tolerant, and gladly accepts
! # bogus XML-RPC data without complaining (but not bogus XML).

 # and again, if you don't understand what's going on in here,
--- 521,531 ----

 class Unmarshaller:
! """Unmarshal an XML-RPC response, based on incoming XML event
! messages (start, data, end). Call close() to get the resulting
! data structure.

! Note that this reader is fairly tolerant, and gladly accepts
! bogus XML-RPC data without complaining (but not bogus XML).
! """

 # and again, if you don't understand what's going on in here,