traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Issue #26889: Tweaked xmlrpc.client documentation.

This commit is contained in:
Serhiy Storchaka 2016-05-07 08:44:36 +03:00
parent 234480df1c da7880ad95
commit 72ac6a7675
1 changed files with 102 additions and 89 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

191
Doc/library/xmlrpc.client.rst
View File

@ -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 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 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 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 .. versionchanged:: 3.5
For https URIs, :mod:`xmlrpc.client` now performs all the necessary 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, \ .. class:: ServerProxy(uri, transport=None, encoding=None, verbose=False, \
allow_none=False, use_datetime=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:`SafeTransport` instance for https: URLs and an internal HTTP
:class:`Transport` instance otherwise. The optional third argument is an :class:`Transport` instance otherwise. The optional third argument is an
encoding, by default UTF-8. The optional fourth argument is a debugging flag. 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 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 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 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 all clients and servers; see `http://ontosys.com/xml-rpc/extensions.php
description. The *use_builtin_types* flag can be used to cause date/time values <https://web.archive.org/web/20130120074804/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 to be presented as :class:`datetime.datetime` objects and binary data to be
presented as :class:`bytes` objects; this flag is false by default. 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 The obsolete *use_datetime* flag is similar to *use_builtin_types* but it
applies only to date/time values. 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 methods it supports (service discovery) and fetch other server-associated
metadata. metadata.
:class:`ServerProxy` instance methods take Python basic types and objects as Types that are conformable (e.g. that can be marshalled through XML),
arguments and return Python basic types and classes. Types that are conformable include the following (and except where noted, they are unmarshalled
(e.g. that can be marshalled through XML), include the following (and except as the same Python type):
where noted, they are unmarshalled as the same Python type):
.. tabularcolumns:: |l|L| .. tabularcolumns:: |l|L|
+---------------------------------+---------------------------------------------+ +----------------------+-------------------------------------------------------+
| Name | Meaning | | XML-RPC type | Python type |
+=================================+=============================================+ +======================+=======================================================+
| :const:`boolean` | The :const:`True` and :const:`False` | | ``boolean`` | :class:`bool` |
| | constants | +----------------------+-------------------------------------------------------+
+---------------------------------+---------------------------------------------+ | ``int`` or ``i4`` | :class:`int` in range from -2147483648 to 2147483647. |
| :const:`integers` | Pass in directly | +----------------------+-------------------------------------------------------+
+---------------------------------+---------------------------------------------+ | ``double`` | :class:`float` |
| :const:`floating-point numbers` | Pass in directly | +----------------------+-------------------------------------------------------+
+---------------------------------+---------------------------------------------+ | ``string`` | :class:`str` |
| :const:`strings` | Pass in directly | +----------------------+-------------------------------------------------------+
+---------------------------------+---------------------------------------------+ | ``array`` | :class:`list` or :class:`tuple` containing |
| :const:`arrays` | Any Python sequence type containing | | | conformable elements. Arrays are returned as |
| | conformable elements. Arrays are returned | | | :class:`list`\ s. |
| | as lists | +----------------------+-------------------------------------------------------+
+---------------------------------+---------------------------------------------+ | ``struct`` | :class:`dict`. Keys must be strings, values may be |
| :const:`structures` | A Python dictionary. Keys must be strings, | | | any conformable type. Objects of user-defined |
| | values may be any conformable type. Objects | | | classes can be passed in; only their :attr:`__dict__` |
| | of user-defined classes can be passed in; | | | attribute is transmitted. |
| | only their *__dict__* attribute is | +----------------------+-------------------------------------------------------+
| | transmitted. | | ``dateTime.iso8601`` | :class:`DateTime` or :class:`datetime.datetime`. |
+---------------------------------+---------------------------------------------+ | | Returned type depends on values of |
| :const:`dates` | In seconds since the epoch. Pass in an | | | *use_builtin_types* and *use_datetime* flags. |
| | instance of the :class:`DateTime` class or | +----------------------+-------------------------------------------------------+
| | a :class:`datetime.datetime` instance. | | ``base64`` | :class:`Binary`, :class:`bytes` or |
+---------------------------------+---------------------------------------------+ | | :class:`bytearray`. Returned type depends on the |
| :const:`binary data` | Pass in an instance of the :class:`Binary` | | | value of the *use_builtin_types* flag. |
| | wrapper class or a :class:`bytes` instance. | +----------------------+-------------------------------------------------------+
+---------------------------------+---------------------------------------------+ | ``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 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 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, 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 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 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 via XML-RPC, use :class:`bytes` or :class:`bytearray` classes or the
described below. :class:`Binary` wrapper class described below.
:class:`Server` is retained as an alias for :class:`ServerProxy` for backwards :class:`Server` is retained as an alias for :class:`ServerProxy` for backwards
compatibility. New code should use :class:`ServerProxy`. 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. :class:`Fault` or :class:`ProtocolError` object indicating an error.
Servers that support the XML introspection API support some common methods 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() .. method:: ServerProxy.system.listMethods()
@ -231,24 +236,26 @@ The client code for the preceding server::
DateTime Objects DateTime Objects
---------------- ----------------
This class may be initialized with seconds since the epoch, a time .. class:: DateTime
tuple, an ISO 8601 time/date string, or a :class:`datetime.datetime`
instance. It has the following methods, supported mainly for internal This class may be initialized with seconds since the epoch, a time
use by the marshalling/unmarshalling code: 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 Write the XML-RPC encoding of this :class:`DateTime` item to the *out* stream
object. object.
It also supports certain of Python's built-in operators through rich comparison It also supports certain of Python's built-in operators through rich comparison
and :meth:`__repr__` methods. and :meth:`__repr__` methods.
A working example follows. The server code:: A working example follows. The server code::
@ -282,36 +289,38 @@ The client code for the preceding server::
Binary Objects Binary Objects
-------------- --------------
This class may be initialized from bytes data (which may include NULs). The .. class:: Binary
primary access to the content of a :class:`Binary` object is provided by an
attribute: 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 The binary data encapsulated by the :class:`Binary` instance. The data is
provided as a :class:`bytes` object. provided as a :class:`bytes` object.
:class:`Binary` objects have the following methods, supported mainly for :class:`Binary` objects have the following methods, supported mainly for
internal use by the marshalling/unmarshalling code: 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 The encoded data will have newlines every 76 characters as per
`RFC 2045 section 6.8 <http://tools.ietf.org/html/rfc2045#section-6.8>`_, `RFC 2045 section 6.8 <http://tools.ietf.org/html/rfc2045#section-6.8>`_,
which was the de facto standard base64 specification when the which was the de facto standard base64 specification when the
XML-RPC spec was written. XML-RPC spec was written.
It also supports certain of Python's built-in operators through :meth:`__eq__` It also supports certain of Python's built-in operators through :meth:`__eq__`
and :meth:`__ne__` methods. and :meth:`__ne__` methods.
Example usage of the binary objects. We're going to transfer an image over Example usage of the binary objects. We're going to transfer an image over
XMLRPC:: XMLRPC::
@ -342,18 +351,20 @@ The client gets the image and saves it to a file::
Fault Objects Fault Objects
------------- -------------
A :class:`Fault` object encapsulates the content of an XML-RPC fault tag. Fault .. class:: Fault
objects have the following attributes:
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 In the following example we're going to intentionally cause a :exc:`Fault` by
returning a complex type object. The server code:: returning a complex type object. The server code::
@ -390,30 +401,32 @@ The client code for the preceding server::
ProtocolError Objects ProtocolError Objects
--------------------- ---------------------
A :class:`ProtocolError` object describes a protocol error in the underlying .. class:: ProtocolError
transport layer (such as a 404 'not found' error if the server named by the URI
does not exist). It has the following attributes: 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 A dict containing the headers of the HTTP/HTTPS request that triggered the
error. error.
In the following example we're going to intentionally cause a :exc:`ProtocolError` In the following example we're going to intentionally cause a :exc:`ProtocolError`
by providing an invalid URI:: by providing an invalid URI::