`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 现在默认执行所有必要的证书和主机名检查。

可用性：不支持 Emscripten，不支持 WASI。

此模块在 WebAssembly 平台 wasm32-emscripten 和 wasm32-wasi 上不可用或无法正常工作。有关更多信息，请参阅 WebAssembly 平台。

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

ServerProxy 实例是一个管理与远程 XML-RPC 服务器通信的对象。必需的第一个参数是 URI（统一资源标识符），通常是服务器的 URL。可选的第二个参数是传输工厂实例；默认情况下，它是 https: URL 的内部 SafeTransport 实例，以及其他情况下的内部 HTTP Transport 实例。可选的第三个参数是编码，默认为 UTF-8。可选的第四个参数是调试标志。

以下参数控制返回的代理实例的使用。如果 allow_none 为 true，则 Python 常量 None 将被转换为 XML；默认行为是 None 引发 TypeError。这是 XML-RPC 规范的常用扩展，但并非所有客户端和服务器都支持；有关说明，请参阅 http://ontosys.com/xml-rpc/extensions.php。use_builtin_types 标志可用于使日期/时间值显示为 datetime.datetime 对象，并将二进制数据显示为 bytes 对象；此标志默认情况下为 false。datetime.datetime、bytes 和 bytearray 对象可以传递给调用。headers 参数是一个可选的 HTTP 标头序列，用于随每个请求发送，表示为表示标头名称和值的 2 元组序列。（例如 [('Header-Name', 'value')]）。已过时的 use_datetime 标志类似于 use_builtin_types，但它仅适用于日期/时间值。

版本 3.3 中的变化：添加了 use_builtin_types 标志。

版本 3.8 中的变化：添加了 headers 参数。

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

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

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

XML-RPC 类型	Python 类型
`boolean`	`bool`
`int`、`i1`、`i2`、`i4`、`i8` 或 `biginteger`	范围从 -2147483648 到 2147483647 的 `int`。值获取 `<int>` 标记。
`double` 或 `float`	`浮点数`。值的标签为 `<double>`。
`字符串`	`字符串`
`数组`	包含一致元素的 `列表` 或 `元组`。数组以 `列表` 形式返回。
`结构体`	`字典`。键必须是字符串，值可以是任何一致的类型。可以传入用户定义类的对象；只传输它们的 `__dict__` 属性。
`dateTime.iso8601`	`DateTime` 或 `datetime.datetime`。返回类型取决于 use_builtin_types 和 use_datetime 标志的值。
`base64`	`Binary`、`字节串` 或 `字节数组`。返回类型取决于 use_builtin_types 标志的值。
`nil`	`None` 常量。只有在 allow_none 为 true 时才允许传递。
`bigdecimal`	`decimal.Decimal`。仅返回类型。

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

传递字符串时，XML 特殊字符（如 <、> 和 &）将自动转义。但是，调用者有责任确保字符串中不包含 XML 不允许的字符，例如 ASCII 值介于 0 到 31 之间的控制字符（当然，制表符、换行符和回车符除外）；否则将导致 XML-RPC 请求不是格式良好的 XML。如果必须通过 XML-RPC 传递任意字节，请使用 字节串 或 字节数组 类或下面描述的 Binary 包装类。

为了向后兼容，Server 将保留为 ServerProxy 的别名。新代码应使用 ServerProxy。

版本 3.5 中的变化：添加了 *context* 参数。

版本 3.6 中的变化：添加了对带前缀的类型标签的支持（例如 ex:nil）。添加了对 Apache XML-RPC 实现用于数字的附加类型的解组支持：i1、i2、i8、biginteger、float 和 bigdecimal。有关说明，请参阅 https://ws.apache.org/xmlrpc/types.html。

另请参阅

XML-RPC 操作指南: 对多种语言的 XML-RPC 操作和客户端软件的详细说明。包含 XML-RPC 客户端开发人员需要了解的几乎所有内容。
XML-RPC 自省: 描述用于自省的 XML-RPC 协议扩展。
XML-RPC 规范: 官方规范。

ServerProxy 对象¶

ServerProxy 实例有一个方法，对应于 XML-RPC 服务器接受的每个远程过程调用。调用该方法将执行一个 RPC，该 RPC 由名称和参数签名分派（例如，可以使用多个参数签名重载相同的方法名称）。RPC 通过返回值结束，该值可以是符合类型的返回数据，也可以是表示错误的 Fault 或 ProtocolError 对象。

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

ServerProxy.system.listMethods()¶: 此方法返回一个字符串列表，XML-RPC 服务器支持的每个（非系统）方法对应一个字符串。

ServerProxy.system.methodSignature(name)¶

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

由于允许多个签名（即重载），因此此方法返回签名列表而不是单个签名。

签名本身仅限于方法所需的参数的顶层。例如，如果一个方法需要一个结构体数组作为参数，并且它返回一个字符串，那么它的签名就是“字符串，数组”。如果它需要三个整数并返回一个字符串，那么它的签名就是“字符串，整数，整数，整数”。

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

ServerProxy.system.methodHelp(name)¶: 此方法接受一个参数，即 XML-RPC 服务器实现的方法的名称。它返回一个文档字符串，描述该方法的用法。如果没有此类字符串可用，则返回一个空字符串。文档字符串可能包含 HTML 标记。

在 3.5 版更改: ServerProxy 的实例支持上下文管理器协议来关闭底层传输。

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

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

日期时间对象¶

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

二进制对象¶

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)

错误对象¶

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)

协议错误对象¶

class xmlrpc.client.ProtocolError¶

ProtocolError 对象描述了底层传输层中的协议错误（例如，如果 URI 命名的服务器不存在，则为 404“未找到”错误）。它具有以下属性

url¶: 触发错误的 URI 或 URL。

errcode¶: 错误代码。

errmsg¶: 错误消息或诊断字符串。

headers¶: 一个字典，包含触发错误的 HTTP/HTTPS 请求的标头。

在以下示例中，我们将通过提供无效的 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)

多调用对象¶

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

class xmlrpc.client.MultiCall(server)¶: 创建一个用于批量处理方法调用的对象。*server* 是调用的最终目标。可以对结果对象进行调用，但它们会立即返回 None，并且只在 MultiCall 对象中存储调用名称和参数。调用对象本身会导致所有存储的调用作为单个 system.multicall 请求传输。此调用的结果是一个生成器；迭代此生成器会产生各个结果。

以下是此类的用法示例。服务器代码

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

便捷函数¶

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 对象；默认情况下，此标志为假。

已过时的 use_datetime 标志类似于 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 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))

客户端和服务器使用示例¶

请参阅 SimpleXMLRPCServer 示例。

脚注

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

ServerProxy 对象¶

日期时间对象¶

二进制对象¶

错误对象¶

协议错误对象¶

多调用对象¶

便捷函数¶

客户端使用示例¶

客户端和服务器使用示例¶

目录

上一主题

下一主题

本页

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

ServerProxy 对象¶

日期时间对象¶

二进制对象¶

错误对象¶

协议错误对象¶

多调用对象¶

便捷函数¶

客户端使用示例¶

客户端和服务器使用示例¶

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