cpython: 04250fc723e6 (original) (raw)

--- 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 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, [](#l1.19) allow_none=False, use_datetime=False, [](#l1.20) @@ -46,15 +46,19 @@ 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. +

• 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[](#l1.32)
• 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 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. |
• +---------------------------------+---------------------------------------------+

• +----------------------+-------------------------------------------------------+
• | 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 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. @@ -164,7 +169,7 @@ returning a value, which may be either r :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.[](#l1.162)

-.. 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[](#l1.170)

•  object.[](#l1.171)

-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[](#l1.199)

•  provided as a :class:`bytes` object.[](#l1.200)

-: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.[](#l1.212)

-.. 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.[](#l1.219)

• 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.

•  The encoded data will have newlines every 76 characters as per[](#l1.225)

•  `RFC 2045 section 6.8 <http://tools.ietf.org/html/rfc2045#section-6.8>`_,[](#l1.226)

•  which was the de facto standard base64 specification when the[](#l1.227)

•  XML-RPC spec was written.[](#l1.228)

-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 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

• .. attribute:: faultCode

• A string indicating the fault type.

•  A string indicating the fault type.[](#l1.253)

-.. 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.[](#l1.260)

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.[](#l1.282)

-.. attribute:: ProtocolError.errcode

• .. attribute:: errcode

• The error code.

•  The error code.[](#l1.289)

-.. attribute:: ProtocolError.errmsg

• .. attribute:: errmsg

• The error message or diagnostic string.

•  The error message or diagnostic string.[](#l1.296)

-.. 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[](#l1.304)

•  error.[](#l1.305)

In the following example we're going to intentionally cause a :exc:ProtocolError by providing an invalid URI::