xmlrpc.client– XML–RPC客户端访问

源代码： Lib / xmlrpc / client.py

XML–RPC是一种使用通过HTTP传递的XML的远程过程调用方法（S）作为atransport。有了它，客户端可以在远程服务器上调用带有参数的方法（服务器由URI命名）并获取结构化数据。这个模块支持编写XML-RPC客户端代码;它处理在线上的一致Python对象和XML之间的所有转换细节.

Warning

xmlrpc.client模块不能抵御恶意构建的数据。如果您需要解析不受信任或未经身份验证的数据，请参阅 XML漏洞.

在版本3.5中更改：对于HTTPS URI，xmlrpc.client现在执行所有必要的证书和主机名默认检查.

class xmlrpc.client.ServerProxy(uri, transport=None, encoding=None, verbose=False, allow_none=False, use_datetime=False, use_builtin_types=False, *, context=None)

在版本3.3中更改：添加了use_builtin_types标志.

一个 ServerProxyinstance是一个管理与ismote XML-RPC服务器通信的对象。所需的第一个参数是URI（统一ResourceIndicator），通常是服务器的URL。可选的secondargument是一个传输工厂实例;默认情况下，它是https：URL的内部SafeTransport实例，否则是内部HTTP Transport实例。可选的第三个参数是anncoding，默认为UTF-8。可选的第四个参数是一个调试标志.

以下参数控制返回的代理实例的使用。如果allow_none为真，则Python常量None将被转换为XML;默认行为是None来提高TypeError。这是XML-RPC规范的常用扩展，但并非所有客户端和服务器都支持;请参阅http://ontosys.com/xml-rpc/extensions.php以获取说明.use_builtin_types标志可用于将日期/时间值显示为datetime.datetime对象和二进制数据提出bytes对象;这个标志默认是假的.datetime.datetime, bytes和bytearray对象可以传递给调用。过时的use_datetime标志类似于use_builtin_types但它只适用于日期/时间值.

HTTP和HTTPS传输支持HTTPBasic身份验证的URL语法扩展：http://user:pass@host:port/path。user:pass部分将被base64编码为HTTP’Authorization’标头，并在调用XML-RPC方法时作为连接过程的一部分发送到远程服务器。如果远程服务器需要BasicAuthentication用户和密码，则只需使用此选项。如果提供了HTTPS URL，context可能ssl.SSLContext并配置底层HTTP连接的SSL设置.

返回的实例是一个代理对象，其方法可用于在远程服务器上调用相应的RPC调用。如果远程服务器支持thetrospection API，则代理也可以用于向远程服务器查询它支持的方法（服务发现）并获取其他服务器 – 关联的元数据.

符合要求的类型（例如，可以通过XML编组）包括以下内容（除非另有说明，否则它们将被解组为相同的Python类型）：

XML-RPC类型 Python类型
boolean bool
int, i1,i2, i4,i8或biginteger int范围从-2147483648到2147483647.Values得到<int>标签
double或float float。值得到<double> tag.
string str
array list或tuple包含了一致的元素。数组以lists.
struct dict返回。键必须是字符串，值可以是一致的类型。可以传入用户定义类的对象;只有他们的__dict__属性被传输.
dateTime.iso8601 DateTime或datetime.datetime.Returned类型取决于use_builtin_types和use_datetime flags的值
base64 Binary, bytes 要么bytearray。返回类型取决于use_builtin_types flag.
nil None常量的值。只有在allow_none为真时才允许通过.
bigdecimal decimal.Decimal。仅返回类型.

这是XML-RPC支持的完整数据类型集。方法调用也可能还有一个特殊的Fault实例，用于表示XML-RPC服务器错误，或者ProtocolError用于表示HTTP / HTTPS传输层中的错误。Fault和ProtocolError派生自一个名为Error的基类。请注意，xmlrpc客户端模块当前不是内置类型子类的marshalinstance .

当传递字符串时，特殊于XML的字符，如<, >和&将是自动逃脱。但是，调用者有责任确保该字符串没有XML中不允许的字符，例如ASCII值介于0和31之间的控制字符（当然，tab，换行符和回车符除外）;如果不这样做，将导致XML-RPCrequest不是格式良好的XML。如果你必须通过XML-RPC传递任意字节，使用bytes或bytearray类或下面描述的Binary包装类.

Server保留为别名对于ServerProxy的向后兼容性。新代码应该使用ServerProxy.

在版本3.5中更改：添加了context参数

更改版本3.6：添加了带前缀的类型标签的支持（例如ex:nil）。增加了对XML XML-RPCimplementation用于数字的其他类型的解组支持：i1, i2, i8, biginteger,float和bigdecimal。参见http：//ws.apache.org/xmlrpc/types.html的描述.

参见

XML-RPC HOWTO
对XML-RPC操作和客户端的一个很好的描述几种语言的软件。包含XML-RPC客户端开发人员需要知道的几乎所有内容.
XML-RPC内省
描述内省的XML-RPC协议扩展.
XML-RPC规范
官方规范.
非官方的XML-RPC勘误表
Fredrik Lundh的“非官方勘误表，旨在澄清XML-RPC规范中的某些细节，如同以及在设计自己的XML-RPCimplementations时使用的“最佳实践”的提示。“

ServerProxy Objects

A ServerProxyinstance具有与XML-RPC服务器接受的每个remoteprocedure调用相对应的方法。调用该方法执行一个RPC，由名称和参数签名分派（例如，相同的方法名称可以用多个参数签名重载）。RPC通过返回一个值来完成，该值可以是符合类型的返回数据，也可以是Fault或ProtocolError表示错误的对象.

支持XML内省API的服务器支持一些常用的方法，这些方法在保留的system属性下

ServerProxy.system.listMethods（）

此方法返回一个字符串列表，一个用于XML-RPC服务器支持的每个（非系统）方法.

ServerProxy.system.methodSignature (name )

此方法采用一个参数，即XML-RPCserver实现的方法的名称。它返回此方法的可能签名数组。签名是一系列类型。这些类型中的第一种是方法的返回类型，其余是参数.

因为允许多个签名（即重载），所以此方法返回签名列表而不是单个签名.

签名本身仅限于amethod预期的顶级参数。例如，如果一个方法需要一个结构数组作为参数，并且它返回一个字符串，那么它的签名就是“string，array”。如果它期望有三个整数并返回一个字符串，那么它的签名是“string，int，int，int”.

如果没有为方法定义签名，则返回非数组值。InPython这意味着返回值的类型将是列表之外的东西.

ServerProxy.system.methodHelp (name）

此方法采用一个参数，即XML-RPCserver实现的方法的名称。它返回描述该方法使用的文档字符串。如果没有这样的字符串可用，则返回空字符串。documentationstring可能包含HTML标记.

在版本3.5中更改：的实例ServerProxy支持上下文管理器关闭底层运输的协议.

下面是一个工作实例。服务器代码：

from xmlrpc.server import SimpleXMLRPCServerdef is_even(n):    return n % 2 == 0server = SimpleXMLRPCServer(("localhost", 8000))print("Listening on port 8000...")server.register_function(is_even, "is_even")server.serve_forever()

前一个服务器的客户端代码：

import xmlrpc.clientwith xmlrpc.client.ServerProxy("http://localhost:8000/") as proxy:    print("3 is even: %s" % str(proxy.is_even(3)))    print("100 is even: %s" % str(proxy.is_even(100)))

DateTime Objects

class xmlrpc.client.DateTime

自从纪元，时间尺，ISO 8601时间/日期字符串或datetime.datetime实例。它有以下方法，主要由编组/解组编码内部使用支持：

decode（string）

接受一个字符串作为实例的新时间值.

encode（out）

写这个DateTime项目到outstreamobject.

它还通过丰富的比较支持Python的某些内置运算符和__repr__()方法。

下面是一个工作实例。服务器代码：

import datetimefrom xmlrpc.server import SimpleXMLRPCServerimport xmlrpc.clientdef today():    today = datetime.datetime.today()    return xmlrpc.client.DateTime(today)server = SimpleXMLRPCServer(("localhost", 8000))print("Listening on port 8000...")server.register_function(today, "today")server.serve_forever()

前面服务器的客户端代码：

import xmlrpc.clientimport datetimeproxy = xmlrpc.client.ServerProxy("http://localhost:8000/")today = proxy.today()# convert the ISO8601 string to a datetime objectconverted = datetime.datetime.strptime(today.value, "%Y%m%dT%H:%M:%S")print("Today: %s" % converted.strftime("%d.%m.%Y, %H:%M"))

二进制对象

class xmlrpc.client.Binary

可以从字节数据（可以包括NUL）初始化该类。对Binary对象内容的初步访问由anattribute提供：

data

由Binary实例。数据提供为bytes对象

Binary对象有以下方法，主要由编组/解组编码支持：

decode（bytes）

接受一个base64 bytes对象并将其解码为实例的新数据.

encode (out)

写这个二进制文件的XML–RPC base 64编码项目到out流对象.

根据 RFC 2045第6.8节，编码数据每76个字符都会有换行符，这是编写XML–RPC规范时事实上的标准base64规范.

它还支持某些Python的内置操作符__eq__()和__ne__() methods.

二进制对象的示例用法。我们要将图像传输到XMLRPC：

from xmlrpc.server import SimpleXMLRPCServerimport xmlrpc.clientdef python_logo():    with open("python_logo.jpg", "rb") as handle:        return xmlrpc.client.Binary(handle.read())server = SimpleXMLRPCServer(("localhost", 8000))print("Listening on port 8000...")server.register_function(python_logo, "python_logo")server.serve_forever()

客户端获取映像并将其保存到文件中：

import xmlrpc.clientproxy = xmlrpc.client.ServerProxy("http://localhost:8000/")with open("fetched_python_logo.jpg", "wb") as handle:    handle.write(proxy.python_logo().data)

故障对象

class xmlrpc.client.Fault

Fault对象封装XML–RPC故障标记的内容。Faultobjects具有以下属性：

faultCode

指示故障类型的字符串.

faultString

包含与fault相关的诊断消息的字符串

在下面的例子中，我们将故意通过返回复杂类型的对象来导致Fault。服务器代码：

from xmlrpc.server import SimpleXMLRPCServer# A marshalling error is going to occur because we"re returning a# complex numberdef add(x, y):    return x+y+0jserver = SimpleXMLRPCServer(("localhost", 8000))print("Listening on port 8000...")server.register_function(add, "add")server.serve_forever()

前面服务器的客户端代码：

import xmlrpc.clientproxy = xmlrpc.client.ServerProxy("http://localhost:8000/")try:    proxy.add(2, 5)except xmlrpc.client.Fault as err:    print("A fault occurred")    print("Fault code: %d" % err.faultCode)    print("Fault string: %s" % err.faultString)

ProtocolError Objects

class xmlrpc.client.ProtocolError

ProtocolError对象描述了底层传输层中的协议错误（如如果URI所指定的服务器不存在，则为404’未找到’错误。它具有以下属性：

url

触发错误的URI或URL

errcode

错误代码

errmsg

错误信息或诊断字符串.

headers

包含触发了错误的HTTP / HTTPS请求标头的dict

在下面的示例中，我们将通过提供无效的URI故意导致ProtocolError：

import xmlrpc.client# create a ServerProxy with a URI that doesn"t respond to XMLRPC requestsproxy = xmlrpc.client.ServerProxy("http://google.com/")try:    proxy.some_method()except xmlrpc.client.ProtocolError as err:    print("A protocol error occurred")    print("URL: %s" % err.url)    print("HTTP/HTTPS headers: %s" % err.headers)    print("Error code: %d" % err.errcode)    print("Error message: %s" % err.errmsg)

MultiCall对象

MultiCall对象提供了一种方法，可以将对ismote服务器的多个调用封装到单个请求中[1] .

class xmlrpc.client.MultiCall（server）

创建一个用于boxcar方法调用的对象。server是呼叫的最终目标。可以对结果对象进行调用，但是会立即返回None，只存储MultiCall对象中的调用名称和参数。调用对象本身会导致所有存储的调用作为单个system.multicall请求传输。这个电话的结果是发电机;迭代这个发生器产生个人结果.

下面是该类的用法示例。服务器代码：

from xmlrpc.server import SimpleXMLRPCServerdef add(x, y):    return x + ydef subtract(x, y):    return x - ydef multiply(x, y):    return x * ydef divide(x, y):    return x // y# A simple server with simple arithmetic functionsserver = SimpleXMLRPCServer(("localhost", 8000))print("Listening on port 8000...")server.register_multicall_functions()server.register_function(add, "add")server.register_function(subtract, "subtract")server.register_function(multiply, "multiply")server.register_function(divide, "divide")server.serve_forever()

前一个服务器的客户端代码：

import xmlrpc.clientproxy = xmlrpc.client.ServerProxy("http://localhost:8000/")multicall = xmlrpc.client.MultiCall(proxy)multicall.add(7, 3)multicall.subtract(7, 3)multicall.multiply(7, 3)multicall.divide(7, 3)result = multicall()print("7+3=%d, 7-3=%d, 7*3=%d, 7//3=%d" % tuple(result))

便利功能

xmlrpc.client.dumps（params, methodname=None, methodresponse=None, encoding=None, allow_none=False）

将params转换为XML–RPC请求。如果methodresponse是真的，或者作出回应。params可以是一个参数元组，也可以是Fault异常类。如果methodresponse为真，则只能返回一个值，这意味着params的长度必须为1 encoding，ifsupplied，是在生成的XML中使用的编码;默认值为UTF-8.Python的None值不能在标准XML–RPC中使用;允许通过扩展使用，为allow_none.

xmlrpc.client.loads（data, use_datetime=False, use_builtin_types=False）

将XML-RPC请求或响应转换为Python对象，(params,methodname). params是一个参数元组;methodname是一个字符串，或None如果数据包中没有方法名称。如果XML-RPC数据包表示故障情况，则此函数将引发Fault异常.use_builtin_typesflag可用于使日期/时间值呈现为datetime.datetime对象和二进制数据，表示为bytes对象;这个标志默认是假的

过时的use_datetimeflag类似于use_builtin_types但它只适用于日期/时间值.

更改版本3.3：添加了use_builtin_types标志.

客户端使用示例

# simple test program (from the XML-RPC specification)from xmlrpc.client import ServerProxy, Error# server = ServerProxy("http://localhost:8000") # local serverwith ServerProxy("http://betty.userland.com") as proxy:    print(proxy)    try:        print(proxy.examples.getStateName(41))    except Error as v:        print("ERROR", v)

要通过HTTP代理访问XML–RPC服务器，您需要定义customtransport。以下示例说明如何：

import http.clientimport xmlrpc.clientclass ProxiedTransport(xmlrpc.client.Transport):    def set_proxy(self, host, port=None, headers=None):        self.proxy = host, port        self.proxy_headers = headers    def make_connection(self, host):        connection = http.client.HTTPConnection(*self.proxy)        connection.set_tunnel(host, headers=self.proxy_headers)        self._connection = host, connection        return connectiontransport = ProxiedTransport()transport.set_proxy("proxy-server", 8080)server = xmlrpc.client.ServerProxy("http://betty.userland.com", transport=transport)print(server.examples.getStateName(41))

客户端和服务器使用示例

请参阅SimpleXMLRPCServer示例.

脚注

[1] 这个方法首先在xmlrpc.com的讨论中提出.

评论被关闭。