[Python-checkins] cpython (merge 3.5 -> default): Issue #26889: Tweaked xmlrpc.client documentation.
serhiy.storchaka
python-checkins at python.org
Sat May 7 01:45:33 EDT 2016
https://hg.python.org/cpython/rev/9bdec549bad3
changeset: 101243:9bdec549bad3
parent: 101241:786de3f37ca7
parent: 101242:04250fc723e6
user: Serhiy Storchaka <storchaka at gmail.com>
date: Sat May 07 08:44:36 2016 +0300
summary:
Issue #26889: Tweaked xmlrpc.client documentation.
files:
Doc/library/xmlrpc.client.rst | 191 +++++++++++----------
1 files changed, 102 insertions(+), 89 deletions(-)
diff --git a/Doc/library/xmlrpc.client.rst b/Doc/library/xmlrpc.client.rst
--- 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 @@
.. 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 @@
: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 @@
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 @@
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 @@
: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 @@
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 +289,38 @@
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 @@
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 +401,32 @@
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::
--
Repository URL: https://hg.python.org/cpython
More information about the Python-checkins
mailing list