From da7880ad95adfcc0e87e2fdf5721d68b30db52ba Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Sat, 7 May 2016 08:44:15 +0300 Subject: [PATCH] Issue #26889: Tweaked xmlrpc.client documentation. --- Doc/library/xmlrpc.client.rst | 191 ++++++++++++++++++---------------- 1 file changed, 102 insertions(+), 89 deletions(-) diff --git a/Doc/library/xmlrpc.client.rst b/Doc/library/xmlrpc.client.rst index 980516873c6..b6e3fc30b54 100644 --- a/Doc/library/xmlrpc.client.rst +++ b/Doc/library/xmlrpc.client.rst @@ -14,7 +14,7 @@ -------------- -XML-RPC is a Remote Procedure Call method that uses XML passed via HTTP as a +XML-RPC is a Remote Procedure Call method that uses XML passed via HTTP(S) as a transport. With it, a client can call methods with parameters on a remote server (the server is named by a URI) and get back structured data. This module supports writing XML-RPC client code; it handles all the details of translating @@ -30,7 +30,7 @@ between conformable Python objects and XML on the wire. .. 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,15 +46,19 @@ between conformable Python objects and XML on the wire. :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. + + The following parameters govern the use of the returned proxy instance. 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 - all clients and servers; see http://ontosys.com/xml-rpc/extensions.php for a - description. The *use_builtin_types* flag can be used to cause date/time values + all clients and servers; see `http://ontosys.com/xml-rpc/extensions.php + ` + for a 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 +77,43 @@ between conformable Python objects and XML on the wire. 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. | - +---------------------------------+---------------------------------------------+ + +----------------------+-------------------------------------------------------+ + | XML-RPC type | Python type | + +======================+=======================================================+ + | ``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 +128,8 @@ between conformable Python objects and XML on the wire. 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`. @@ -164,7 +169,7 @@ returning a value, which may be either returned data in a conformant type or a :class:`Fault` or :class:`ProtocolError` object indicating an error. Servers that support the XML introspection API support some common methods -grouped under the reserved :attr:`system` attribute: +grouped under the reserved :attr:`~ServerProxy.system` attribute: .. method:: ServerProxy.system.listMethods() @@ -231,24 +236,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) + .. method:: decode(string) - Accept a string as the instance's new time value. + Accept a string as the instance's new time value. -.. method:: DateTime.encode(out) + .. method:: encode(out) - Write the XML-RPC encoding of this :class:`DateTime` item to the *out* stream - object. + 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. + 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 +289,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 + .. attribute:: data - The binary data encapsulated by the :class:`Binary` instance. The data is - provided as a :class:`bytes` object. + 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: + :class:`Binary` objects have the following methods, supported mainly for + internal use by the marshalling/unmarshalling code: -.. method:: Binary.decode(bytes) + .. method:: decode(bytes) - Accept a base64 :class:`bytes` object and decode it as the instance's new data. + Accept a base64 :class:`bytes` object and decode it as the instance's new data. -.. method:: Binary.encode(out) + .. method:: encode(out) - Write the XML-RPC base 64 encoding of this binary item to the out stream object. + Write the XML-RPC base 64 encoding of this binary item to the *out* stream object. - 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. + 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. + 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 +351,20 @@ The client gets the image and saves it to a file:: 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 + .. attribute:: faultCode - A string indicating the fault type. + A string indicating the fault type. -.. attribute:: Fault.faultString + .. attribute:: faultString - A string containing a diagnostic message associated with the fault. + 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 +401,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 + .. attribute:: url - The URI or URL that triggered the error. + The URI or URL that triggered the error. -.. attribute:: ProtocolError.errcode + .. attribute:: errcode - The error code. + The error code. -.. attribute:: ProtocolError.errmsg + .. attribute:: errmsg - The error message or diagnostic string. + The error message or diagnostic string. -.. attribute:: ProtocolError.headers + .. attribute:: headers - A dict containing the headers of the HTTP/HTTPS request that triggered the - error. + 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::