20.23. xmlrpclib — XML-RPC 客户端访问

笔记

xmlrpclib 模块已在 Python 3 中重命名为 xmlrpc.client。 2to3 工具将在将您的源代码转换为 Python 3 时自动调整导入。

2.2 版中的新功能。

源代码： :source:`Lib/xmlrpclib.py`

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

警告

xmlrpclib 模块对于恶意构建的数据并不安全。如果您需要解析不受信任或未经身份验证的数据，请参阅 XML 漏洞。

2.7.9 版更改：对于 HTTPS URI，xmlrpclib 现在默认执行所有必要的证书和主机名检查。

class xmlrpclib.ServerProxy(uri[, transport[, encoding[, verbose[, allow_none[, use_datetime[, context]]]]]])

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_datetime 标志可用于使日期/时间值显示为 datetime.datetime 对象；默认情况下这是错误的。 datetime.datetime 对象可以传递给调用。

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 类型	蟒蛇型
`boolean`	`bool`
`int` 或 `i4`	int 或 long 范围从 -2147483648 到 2147483647。
`double`	`float`
`string`	str 或 unicode
`array`	`list` 或元组包含符合元素。数组返回为 `lists`。
`struct`	字典。键必须是字符串，值可以是任何符合要求的类型。可以传入用户自定义类的对象；仅传输它们的 __dict__ 属性。
`dateTime.iso8601`	DateTime 或 datetime.datetime。返回类型取决于 use_datetime 标志的值。
`base64`	`Binary`
`nil`	`None` 常数。仅当 allow_none 为真时才允许传递。

这是 XML-RPC 支持的完整数据类型集。方法调用还可能引发一个特殊的 Fault 实例，用于发出 XML-RPC 服务器错误的信号，或 ProtocolError 用于发出 HTTP/HTTPS 传输层中的错误信号。 Fault 和 ProtocolError 都派生自名为 Error 的基类。请注意，即使从 Python 2.2 开始，您可以对内置类型进行子类化，但 xmlrpclib 模块当前不会封送此类子类的实例。

传递字符串时，<、>、&等XML特有的字符会被自动转义。但是，调用者有责任确保字符串不含 XML 中不允许的字符，例如 ASCII 值在 0 到 31 之间的控制字符（当然，制表符、换行符和回车符除外）；不这样做将导致 XML-RPC 请求不是格式正确的 XML。如果您必须通过 XML-RPC 传递任意字符串，请使用下面描述的 Binary 包装器类。

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

2.5 版更改：添加了 use_datetime 标志。

2.6 版更改：新式类的实例可以传入，如果它们具有 __dict__ 属性并且没有基类以一种特殊的方式编组。

在 2.7.9 版更改：添加了 上下文 参数。

也可以看看

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

20.23.1。服务器代理对象

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

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

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

ServerProxy.system.methodSignature(name)

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

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

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

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

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

20.23.2. 布尔对象

此类可以从任何 Python 值初始化；返回的实例仅取决于其真值。它通过 __cmp__()、__repr__()、__int__() 和 __nonzero__() 方法支持各种 Python 运算符，所有这些都以明显的方式实现。

它还具有以下方法，主要由解组代码支持供内部使用：

Boolean.encode(out): 将此布尔项的 XML-RPC 编码写入输出流对象。

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

import xmlrpclib
from SimpleXMLRPCServer 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 xmlrpclib

proxy = xmlrpclib.ServerProxy("http://localhost:8000/")
print "3 is even: %s" % str(proxy.is_even(3))
print "100 is even: %s" % str(proxy.is_even(100))

20.23.3. 日期时间对象

class xmlrpclib.DateTime

此类可以使用自纪元以来的秒数、时间元组、ISO 8601 时间/日期字符串或 datetime.datetime 实例进行初始化。它有以下方法，主要支持编组/解组代码内部使用：

decode(string): 接受一个字符串作为实例的新时间值。

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

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

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

import datetime
from SimpleXMLRPCServer import SimpleXMLRPCServer
import xmlrpclib

def today():
    today = datetime.datetime.today()
    return xmlrpclib.DateTime(today)

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

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

import xmlrpclib
import datetime

proxy = xmlrpclib.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")

20.23.4. 二进制对象

class xmlrpclib.Binary

此类可以从字符串数据（可能包括 NUL）初始化。对 Binary 对象内容的主要访问由属性提供：

data: Binary 实例封装的二进制数据。数据以 8 位字符串的形式提供。

Binary 对象有以下方法，主要支持编组/解组代码内部使用：

decode(string): 接受 base64 字符串并将其解码为实例的新数据。

encode(out)

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

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

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

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

from SimpleXMLRPCServer import SimpleXMLRPCServer
import xmlrpclib

def python_logo():
     with open("python_logo.jpg", "rb") as handle:
         return xmlrpclib.Binary(handle.read())

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

server.serve_forever()

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

import xmlrpclib

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

20.23.5。故障对象

class xmlrpclib.Fault

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

faultCode: 指示故障类型的字符串。

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

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

from SimpleXMLRPCServer 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 xmlrpclib

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

20.23.6。协议错误对象

class xmlrpclib.ProtocolError

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

url: 触发错误的 URI 或 URL。

errcode: 错误代码。

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

headers: 包含触发错误的 HTTP/HTTPS 请求标头的字符串。

在下面的示例中，我们将通过提供一个不指向 XMLRPC 服务器的 URI 故意导致 ProtocolError：

import xmlrpclib

# create a ServerProxy with a URI that doesn't respond to XMLRPC requests
proxy = xmlrpclib.ServerProxy("http://www.google.com/")

try:
    proxy.some_method()
except xmlrpclib.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

20.23.7。多重呼叫对象

2.4 版中的新功能。

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

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

此类的使用示例如下。服务器代码

from SimpleXMLRPCServer 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 xmlrpclib

proxy = xmlrpclib.ServerProxy("http://localhost:8000/")
multicall = xmlrpclib.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)

20.23.8. 便利功能

xmlrpclib.boolean(value): 将任何 Python 值转换为 XML-RPC 布尔常量之一，True 或 False。

xmlrpclib.dumps(params[, methodname[, methodresponse[, encoding[, allow_none]]]]): 将 params 转换为 XML-RPC 请求。或者如果 methodresponse 为真，则进入响应。 params 可以是参数元组或 Fault 异常类的实例。如果 methodresponse 为真，则只能返回单个值，这意味着 params 的长度必须为 1。 encoding（如果提供）是在生成的 XML 中使用的编码；默认为 UTF-8。 Python 的 None 值不能在标准 XML-RPC 中使用；要允许通过扩展使用它，请为 allow_none 提供真实值。

xmlrpclib.loads(data[, use_datetime]): 将 XML-RPC 请求或响应转换为 Python 对象，即 (params, methodname)。 params 是一个参数元组； methodname 是一个字符串，或者 None 如果数据包中没有方法名称。如果 XML-RPC 数据包表示故障条件，则此函数将引发 Fault 异常。 use_datetime 标志可用于使日期/时间值显示为 datetime.datetime 对象；默认情况下这是错误的。

2.5 版更改：添加了 use_datetime 标志。

20.23.9。客户端使用示例

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

# server = ServerProxy("http://localhost:8000") # local server
server = ServerProxy("http://betty.userland.com")

print server

try:
    print server.examples.getStateName(41)
except Error as v:
    print "ERROR", v

要通过 HTTP 代理访问 XML-RPC 服务器，您需要定义自定义传输。以下示例显示了如何：

import xmlrpclib, httplib

class ProxiedTransport(xmlrpclib.Transport):
    def set_proxy(self, proxy):
        self.proxy = proxy

    def make_connection(self, host):
        self.realhost = host
        h = httplib.HTTPConnection(self.proxy)
        return h

    def send_request(self, connection, handler, request_body):
        connection.putrequest("POST", 'http://%s%s' % (self.realhost, handler))

    def send_host(self, connection, host):
        connection.putheader('Host', self.realhost)

p = ProxiedTransport()
p.set_proxy('proxy-server:8080')
server = xmlrpclib.ServerProxy('http://time.xmlrpc.com/RPC2', transport=p)
print server.currentTime.getCurrentTime()

20.23.10。客户端和服务器使用示例

请参阅 SimpleXMLRPCServer 示例。

脚注

1: 这种方法首先在 xmlrpc.com 上的讨论中提出。

20.23. xmlrpclib — XML-RPC 客户端访问 — Python 文档

目录

20.23. xmlrpclib — XML-RPC 客户端访问

20.23.1。服务器代理对象

20.23.2. 布尔对象

20.23.3. 日期时间对象

20.23.4. 二进制对象

20.23.5。故障对象

20.23.6。协议错误对象

20.23.7。多重呼叫对象

20.23.8. 便利功能

20.23.9。客户端使用示例

20.23.10。客户端和服务器使用示例

20.23. xmlrpclib — XML-RPC 客户端访问 — Python 文档

20.23. xmlrpclib — XML-RPC 客户端访问

20.23.1。 服务器代理对象

20.23.2. 布尔对象

20.23.3. 日期时间对象

20.23.4. 二进制对象

20.23.5。 故障对象

20.23.6。 协议错误对象

20.23.7。 多重呼叫对象

20.23.8. 便利功能

20.23.9。 客户端使用示例

20.23.10。 客户端和服务器使用示例

20.23.1。服务器代理对象

20.23.5。故障对象

20.23.6。协议错误对象

20.23.7。多重呼叫对象

20.23.9。客户端使用示例

20.23.10。客户端和服务器使用示例