Skip to content

C
cpython
Commit da7880ad authored by Serhiy Storchaka's avatar Serhiy Storchaka
Browse files
Options

Issue #26889: Tweaked xmlrpc.client documentation.

parent f73a48cb
Hide whitespace changes
Inline Side-by-side
Showing with 102 additions and 89 deletions
Doc/library/xmlrpc.client.rst
View file @ da7880ad
......@@ -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
<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
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
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 <http://tools.ietf.org/html/rfc2045#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 <http://tools.ietf.org/html/rfc2045#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 +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::
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7