diff -r ed6345cb08ab Doc/library/xmlrpc.client.rst --- a/Doc/library/xmlrpc.client.rst Fri Apr 29 11:31:52 2016 +0300 +++ b/Doc/library/xmlrpc.client.rst Sat Apr 30 00:36:46 2016 +0300 @@ -30,7 +30,7 @@ between conformable Python objects and X .. versionchanged:: 3.5 For https URIs, :mod:`xmlrpc.client` now performs all the necessary - certificate and hostname checks by default + certificate and hostname checks by default. .. class:: ServerProxy(uri, transport=None, encoding=None, verbose=False, \ allow_none=False, use_datetime=False, \ @@ -46,6 +46,7 @@ between conformable Python objects and X :class:`SafeTransport` instance for https: URLs and an internal HTTP :class:`Transport` instance otherwise. The optional third argument is an encoding, by default UTF-8. The optional fourth argument is a debugging flag. + If *allow_none* is true, the Python constant ``None`` will be translated into XML; the default behaviour is for ``None`` to raise a :exc:`TypeError`. This is a commonly-used extension to the XML-RPC specification, but isn't supported by @@ -53,8 +54,8 @@ between conformable Python objects and X description. The *use_builtin_types* flag can be used to cause date/time values to be presented as :class:`datetime.datetime` objects and binary data to be presented as :class:`bytes` objects; this flag is false by default. - :class:`datetime.datetime` and :class:`bytes` objects may be passed to calls. - + :class:`datetime.datetime`, :class:`bytes` and :class:`bytearray` objects + may be passed to calls. The obsolete *use_datetime* flag is similar to *use_builtin_types* but it applies only to date/time values. @@ -73,42 +74,43 @@ between conformable Python objects and X methods it supports (service discovery) and fetch other server-associated metadata. - :class:`ServerProxy` instance methods take Python basic types and objects as - arguments and return Python basic types and classes. Types that are conformable - (e.g. that can be marshalled through XML), include the following (and except - where noted, they are unmarshalled as the same Python type): + Types that are conformable (e.g. that can be marshalled through XML), + include the following (and except where noted, they are unmarshalled + as the same Python type): .. tabularcolumns:: |l|L| - +---------------------------------+---------------------------------------------+ - | Name | Meaning | - +=================================+=============================================+ - | :const:`boolean` | The :const:`True` and :const:`False` | - | | constants | - +---------------------------------+---------------------------------------------+ - | :const:`integers` | Pass in directly | - +---------------------------------+---------------------------------------------+ - | :const:`floating-point numbers` | Pass in directly | - +---------------------------------+---------------------------------------------+ - | :const:`strings` | Pass in directly | - +---------------------------------+---------------------------------------------+ - | :const:`arrays` | Any Python sequence type containing | - | | conformable elements. Arrays are returned | - | | as lists | - +---------------------------------+---------------------------------------------+ - | :const:`structures` | A Python dictionary. Keys must be strings, | - | | values may be any conformable type. Objects | - | | of user-defined classes can be passed in; | - | | only their *__dict__* attribute is | - | | transmitted. | - +---------------------------------+---------------------------------------------+ - | :const:`dates` | In seconds since the epoch. Pass in an | - | | instance of the :class:`DateTime` class or | - | | a :class:`datetime.datetime` instance. | - +---------------------------------+---------------------------------------------+ - | :const:`binary data` | Pass in an instance of the :class:`Binary` | - | | wrapper class or a :class:`bytes` instance. | - +---------------------------------+---------------------------------------------+ + +----------------------+-------------------------------------------------------+ + | Name | Meaning | + +======================+=======================================================+ + | ``boolean`` | :class:`bool` | + +----------------------+-------------------------------------------------------+ + | ``int`` or ``i4`` | :class:`int` in range from -2147483648 to 2147483647. | + +----------------------+-------------------------------------------------------+ + | ``double`` | :class:`float` | + +----------------------+-------------------------------------------------------+ + | ``string`` | :class:`str` | + +----------------------+-------------------------------------------------------+ + | ``array`` | :class:`list` or :class:`tuple` containing | + | | conformable elements. Arrays are returned as | + | | :class:`list`\ s. | + +----------------------+-------------------------------------------------------+ + | ``struct`` | :class:`dict`. Keys must be strings, values may be | + | | any conformable type. Objects of user-defined | + | | classes can be passed in; only their :attr:`__dict__` | + | | attribute is transmitted. | + +----------------------+-------------------------------------------------------+ + | ``dateTime.iso8601`` | :class:`DateTime` or :class:`datetime.datetime`. | + | | Returned type depends on values of | + | | *use_builtin_types* and *use_datetime* flags. | + +----------------------+-------------------------------------------------------+ + | ``base64`` | :class:`Binary`, :class:`bytes` or | + | | :class:`bytearray`. Returned type depends on the | + | | value of the *use_builtin_types* flag. | + +----------------------+-------------------------------------------------------+ + | ``nil`` | The ``None`` constant. Passing is allowed only if | + | | *allow_none* is true. | + +----------------------+-------------------------------------------------------+ This is the full set of data types supported by XML-RPC. Method calls may also raise a special :exc:`Fault` instance, used to signal XML-RPC server errors, or @@ -123,8 +125,8 @@ between conformable Python objects and X the control characters with ASCII values between 0 and 31 (except, of course, tab, newline and carriage return); failing to do this will result in an XML-RPC request that isn't well-formed XML. If you have to pass arbitrary bytes - via XML-RPC, use the :class:`bytes` class or the class:`Binary` wrapper class - described below. + via XML-RPC, use :class:`bytes` or :class:`bytearray` classes or the + :class:`Binary` wrapper class described below. :class:`Server` is retained as an alias for :class:`ServerProxy` for backwards compatibility. New code should use :class:`ServerProxy`. @@ -231,24 +233,26 @@ The client code for the preceding server DateTime Objects ---------------- -This class may be initialized with seconds since the epoch, a time -tuple, an ISO 8601 time/date string, or a :class:`datetime.datetime` -instance. It has the following methods, supported mainly for internal -use by the marshalling/unmarshalling code: +.. class:: DateTime + This class may be initialized with seconds since the epoch, a time + tuple, an ISO 8601 time/date string, or a :class:`datetime.datetime` + instance. It has the following methods, supported mainly for internal + use by the marshalling/unmarshalling code: -.. method:: DateTime.decode(string) - Accept a string as the instance's new time value. + .. method:: decode(string) + Accept a string as the instance's new time value. -.. method:: DateTime.encode(out) - Write the XML-RPC encoding of this :class:`DateTime` item to the *out* stream - object. + .. method:: encode(out) -It also supports certain of Python's built-in operators through rich comparison -and :meth:`__repr__` methods. + Write the XML-RPC encoding of this :class:`DateTime` item to the *out* stream + object. + + It also supports certain of Python's built-in operators through rich comparison + and :meth:`__repr__` methods. A working example follows. The server code:: @@ -282,36 +286,38 @@ The client code for the preceding server Binary Objects -------------- -This class may be initialized from bytes data (which may include NULs). The -primary access to the content of a :class:`Binary` object is provided by an -attribute: +.. class:: Binary + This class may be initialized from bytes data (which may include NULs). The + primary access to the content of a :class:`Binary` object is provided by an + attribute: -.. attribute:: Binary.data - The binary data encapsulated by the :class:`Binary` instance. The data is - provided as a :class:`bytes` object. + .. attribute:: data -:class:`Binary` objects have the following methods, supported mainly for -internal use by the marshalling/unmarshalling code: + The binary data encapsulated by the :class:`Binary` instance. The data is + provided as a :class:`bytes` object. + :class:`Binary` objects have the following methods, supported mainly for + internal use by the marshalling/unmarshalling code: -.. method:: Binary.decode(bytes) - Accept a base64 :class:`bytes` object and decode it as the instance's new data. + .. method:: decode(bytes) + Accept a base64 :class:`bytes` object and decode it as the instance's new data. -.. method:: Binary.encode(out) - Write the XML-RPC base 64 encoding of this binary item to the out stream object. + .. method:: encode(out) - The encoded data will have newlines every 76 characters as per - `RFC 2045 section 6.8 `_, - which was the de facto standard base64 specification when the - XML-RPC spec was written. + Write the XML-RPC base 64 encoding of this binary item to the *out* stream object. -It also supports certain of Python's built-in operators through :meth:`__eq__` -and :meth:`__ne__` methods. + The encoded data will have newlines every 76 characters as per + `RFC 2045 section 6.8 `_, + which was the de facto standard base64 specification when the + XML-RPC spec was written. + + It also supports certain of Python's built-in operators through :meth:`__eq__` + and :meth:`__ne__` methods. Example usage of the binary objects. We're going to transfer an image over XMLRPC:: @@ -342,18 +348,20 @@ The client gets the image and saves it t Fault Objects ------------- -A :class:`Fault` object encapsulates the content of an XML-RPC fault tag. Fault -objects have the following attributes: +.. class:: Fault + A :class:`Fault` object encapsulates the content of an XML-RPC fault tag. Fault + objects have the following attributes: -.. attribute:: Fault.faultCode - A string indicating the fault type. + .. attribute:: faultCode + A string indicating the fault type. -.. attribute:: Fault.faultString - A string containing a diagnostic message associated with the fault. + .. attribute:: faultString + + A string containing a diagnostic message associated with the fault. In the following example we're going to intentionally cause a :exc:`Fault` by returning a complex type object. The server code:: @@ -390,30 +398,32 @@ The client code for the preceding server ProtocolError Objects --------------------- -A :class:`ProtocolError` object describes a protocol error in the underlying -transport layer (such as a 404 'not found' error if the server named by the URI -does not exist). It has the following attributes: +.. class:: ProtocolError + A :class:`ProtocolError` object describes a protocol error in the underlying + transport layer (such as a 404 'not found' error if the server named by the URI + does not exist). It has the following attributes: -.. attribute:: ProtocolError.url - The URI or URL that triggered the error. + .. attribute:: url + The URI or URL that triggered the error. -.. attribute:: ProtocolError.errcode - The error code. + .. attribute:: errcode + The error code. -.. attribute:: ProtocolError.errmsg - The error message or diagnostic string. + .. attribute:: errmsg + The error message or diagnostic string. -.. attribute:: ProtocolError.headers - A dict containing the headers of the HTTP/HTTPS request that triggered the - error. + .. attribute:: headers + + A dict containing the headers of the HTTP/HTTPS request that triggered the + error. In the following example we're going to intentionally cause a :exc:`ProtocolError` by providing an invalid URI::