Skip to main content

21.26. xmlrpc.client — XML-RPC客户端访问

源代码: Lib/xmlrpc/client.py


XML-RPC是一个远程过程调用方法,它使用通过HTTP(S)传递的XML作为传输。使用它,客户端可以调用远程服务器上的参数(服务器由URI命名)并返回结构化数据的方法。此模块支持编写XML-RPC客户端代码;它处理所有在一致的Python对象和XML之间转换的细节。

警告

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 标志。

ServerProxy 实例是管理与远程XML-RPC服务器的通信的对象。所需的第一个参数是URI(统一资源指示符),通常是服务器的URL。可选的第二个参数是传输工厂实例;默认情况下,它是https:URL的内部 SafeTransport 实例,否则是内部HTTP Transport 实例。可选的第三个参数是一个编码,默认为UTF-8。可选的第四个参数是调试标志。

以下参数控制返回的代理实例的使用。如果 allow_none 为真,Python常量 None 将被转换为XML;默认行为是 None 提出 TypeError。这是对XML-RPC规范的常用扩展,但不是由所有客户端和服务器支持;参见 http://ontosys.com/xml-rpc/extensions.php 的描述。 use_builtin_types 标志可用于使日期/时间值作为 datetime.datetime 对象和二进制数据呈现为 bytes 对象;此标志默认为false。 datetime.datetimebytesbytearray 对象可以传递给调用。过时的 use_datetime 标志与 use_builtin_types 类似,但它仅适用于日期/时间值。

HTTP和HTTPS传输都支持HTTP基本身份验证的URL语法扩展:http://user:pass@host:port/pathuser:pass 部分将作为HTTP“授权”头部进行base64编码,并在调用XML-RPC方法时作为连接过程的一部分发送到远程服务器。如果远程服务器需要基本身份验证用户和密码,则只需使用此选项。如果提供了HTTPS URL,则 context 可以是 ssl.SSLContext 并配置底层HTTPS连接的SSL设置。

返回的实例是一个代理对象,其方法可用于调用远程服务器上的相应RPC调用。如果远程服务器支持自检API,则还可以使用代理查询远程服务器所支持的方法(服务发现)并获取其他与服务器关联的元数据。

符合的类型(例如,可以通过XML编组),包括以下(除非另有说明,它们被解组为同一个Python类型):

XML-RPC类型

Python类型

boolean

bool

inti1i2i4i8biginteger

int 的范围从-2147483648到2147483647.值获取 <int> 标记。

doublefloat

float。值获取 <double> 标记。

string

str

array

listtuple。数组返回为 lists

struct

dict。键必须是字符串,值可以是任何合适的类型。可以传递用户定义类的对象;只传输它们的 __dict__ 属性。

dateTime.iso8601

DateTimedatetime.datetime。返回类型取决于 use_builtin_typesuse_datetime 标志的值。

base64

Binarybytesbytearray。返回类型取决于 use_builtin_types 标志的值。

nil

None 常数。仅当 allow_none 为真时,才允许传递。

bigdecimal

decimal.Decimal。仅返回类型。

这是XML-RPC支持的全套数据类型。方法调用还可以产生用于发信号通知XML-RPC服务器错误的特殊 Fault 实例,或者用于在HTTP/HTTPS传输层中用信号通知错误的 ProtocolErrorFaultProtocolError 都衍生自称为 Error 的基类。请注意,xmlrpc客户端模块当前不封送内置类型的子类的实例。

当传递字符串时,将特殊于XML的字符(如 <>&)自动转义。但是,调用者有责任确保字符串中不包含XML中不允许使用的字符,例如ASCII值在0到31之间的控制字符(除非是tab,换行符和回车符)。如果不这样做,将导致XML-RPC请求不是格式良好的XML。如果您必须通过XML-RPC传递任意字节,请使用 bytesbytearray 类或下面描述的 Binary 包装器类。

Server 保留为 ServerProxy 的别名以实现向后兼容性。新代码应该使用 ServerProxy

在 3.5 版更改: 添加了 context 参数。

在 3.6 版更改: 添加了对带有前缀的类型标签(例如 ex:nil)的支持。添加了对Apache XML-RPC实现用于数字的非网格化附加类型的支持:i1i2i8bigintegerfloatbigdecimal。有关说明,请参阅 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-RPC实现时使用”最佳实践“的提示。

21.26.1. ServerProxy对象

ServerProxy 实例具有与XML-RPC服务器接受的每个远程过程调用相对应的方法。调用方法执行RPC,通过名称和参数签名调度(例如,相同的方法名称可以重载多个参数签名)。 RPC通过返回一个值来完成,该值可以是符合类型的返回数据,或者指示错误的 FaultProtocolError 对象。

支持XML自省API的服务器支持在保留的 system 属性下分组的一些常见方法:

ServerProxy.system.listMethods()

此方法返回一个字符串列表,一个用于XML-RPC服务器支持的每个(非系统)方法。

ServerProxy.system.methodSignature(name)

此方法接受一个参数,即XML-RPC服务器实现的方法的名称。它返回此方法的可能签名数组。签名是一个类型数组。第一种类型是方法的返回类型,其余的是参数。

因为允许多个签名(即,重载),所以该方法返回签名的列表而不是单独。

签名本身仅限于方法预期的顶级参数。例如,如果一个方法期望一个结构体数组作为参数,并返回一个字符串,它的签名只是“string,array”。如果它期望三个整数并返回一个字符串,它的签名是“string,int,int,int”。

如果没有为方法定义签名,则返回非数组值。在Python中,这意味着返回值的类型将不是list。

ServerProxy.system.methodHelp(name)

此方法接受一个参数,即XML-RPC服务器实现的方法的名称。它返回一个描述该方法的使用的文档字符串。如果没有这样的字符串可用,则返回一个空字符串。文档字符串可能包含HTML标记。

在 3.5 版更改: ServerProxy 的实例支持 context manager 协议关闭底层传输。

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

from xmlrpc.server import SimpleXMLRPCServer

def is_even(n):
    return n % 2 == 0

server = SimpleXMLRPCServer(("localhost", 8000))
print("Listening on port 8000...")
server.register_function(is_even, "is_even")
server.serve_forever()

上一个服务器的客户端代码:

import xmlrpc.client

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

21.26.2. DateTime对象

class xmlrpc.client.DateTime

该类可以从时代开始以秒为单位初始化,时间元组,ISO 8601时间/日期字符串或 datetime.datetime 实例。它有以下方法,主要支持由编组/取消编组代码内部使用:

decode(string)

接受字符串作为实例的新时间值。

encode(out)

将此 DateTime 项的XML-RPC编码写入 out 流对象。

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

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

import datetime
from xmlrpc.server import SimpleXMLRPCServer
import xmlrpc.client

def 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.client
import datetime

proxy = xmlrpc.client.ServerProxy("http://localhost:8000/")

today = proxy.today()
# convert the ISO8601 string to a datetime object
converted = datetime.datetime.strptime(today.value, "%Y%m%dT%H:%M:%S")
print("Today: %s" % converted.strftime("%d.%m.%Y, %H:%M"))

21.26.3. 二进制对象

class xmlrpc.client.Binary

该类可以从字节数据(其可以包括NUL)初始化。对 Binary 对象的内容的主要访问由属性提供:

data

Binary 实例封装的二进制数据。数据作为 bytes 对象提供。

Binary 对象有以下方法,主要支持由编组/取消编组代码内部使用:

decode(bytes)

接受base64 bytes 对象,并将其解码为实例的新数据。

encode(out)

将此二进制项的XML-RPC base 64编码写入 out 流对象。

编码数据将根据 RFC 2045第6.8节 每76个字符有换行符,这是在编写XML-RPC规范时事实上的标准base64规范。

它还通过 __eq__()__ne__() 方法支持某些Python的内置运算符。

二进制对象的用法示例。我们将通过XMLRPC传输图像:

from xmlrpc.server import SimpleXMLRPCServer
import xmlrpc.client

def 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.client

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

21.26.4. 故障对象

class xmlrpc.client.Fault

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

faultCode

指示故障类型的字符串。

faultString

包含与故障相关联的诊断消息的字符串。

在下面的示例中,我们将通过返回一个复杂类型的对象来有意地创建一个 Fault。服务器代码:

from xmlrpc.server import SimpleXMLRPCServer

# A marshalling error is going to occur because we're returning a
# complex number
def add(x, y):
    return x+y+0j

server = SimpleXMLRPCServer(("localhost", 8000))
print("Listening on port 8000...")
server.register_function(add, 'add')

server.serve_forever()

上一个服务器的客户端代码:

import xmlrpc.client

proxy = 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)

21.26.5. ProtocolError对象

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 requests
proxy = 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)

21.26.6. 多对象对象

MultiCall 对象提供了一种将对远程服务器的多个调用封装到单个请求 [1] 中的方法。

class xmlrpc.client.MultiCall(server)

创建一个用于boxcar方法调用的对象。 server 是呼叫的最终目标。可以对结果对象进行调用,但是它们将立即返回 None,并且仅将调用名称和参数存储在 MultiCall 对象中。调用对象本身会使所有存储的调用作为单个 system.multicall 请求传输。这个调用的结果是 generator;迭代该生成器产生单独的结果。

接下来是该类的使用示例。服务器代码:

from xmlrpc.server import SimpleXMLRPCServer

def add(x, y):
    return x + y

def subtract(x, y):
    return x - y

def multiply(x, y):
    return x * y

def divide(x, y):
    return x // y

# A simple server with simple arithmetic functions
server = 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.client

proxy = 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))

21.26.7. 便利功能

xmlrpc.client.dumps(params, methodname=None, methodresponse=None, encoding=None, allow_none=False)

params 转换为XML-RPC请求。或如果 methodresponse 为真,则返回响应。 params 可以是参数的元组或 Fault 异常类的实例。如果 methodresponse 为真,则只能返回单个值,这意味着 params 的长度必须为1.如果提供,encoding 是生成的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_types 标志可用于使日期/时间值作为 datetime.datetime 对象和二进制数据呈现为 bytes 对象;此标志默认为false。

过时的 use_datetime 标志与 use_builtin_types 类似,但它仅适用于日期/时间值。

在 3.3 版更改: 已添加 use_builtin_types 标志。

21.26.8. 客户端使用示例

# simple test program (from the XML-RPC specification)
from xmlrpc.client import ServerProxy, Error

# server = ServerProxy("http://localhost:8000") # local server
with 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服务器,您需要定义自定义传输。以下示例显示如何:

import http.client
import xmlrpc.client

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

transport = ProxiedTransport()
transport.set_proxy('proxy-server', 8080)
server = xmlrpc.client.ServerProxy('http://betty.userland.com', transport=transport)
print(server.examples.getStateName(41))

21.26.9. 客户端和服务器使用示例

SimpleXMLRPCServer示例

脚注

[1]

这种方法首先在 关于xmlrpc.com的讨论 中提出。