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

源代码： Lib/xmlrpc/client.py

XML-RPC是一种远程过程调用方法，它使用通过HTTP传递的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, *, headers=(), context=None)¶

A ServerProxy 实例是管理与远程XML-RPC服务器通信的对象。必需的第一个参数是一个URI（统一资源指示器），通常是服务器的URL。可选的第二个参数是传输工厂实例；默认情况下，它是内部的 SafeTransport https:urls和内部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 对象；默认情况下，此标志为假。 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` or `biginteger`	`int` 范围从-2147483648到2147483647。价值观得到 `<int>` 标签。
`double` or `float`	`float` . 值获得 `<double>` 标签。
`string`	`str`
`array`	`list` 或 `tuple` 包含一致的元素。数组返回为 `lists` .
`struct`	`dict` . 键必须是字符串，值可以是任何兼容类型。可以传入用户定义类的对象；只有它们 `__dict__` 属性被传输。
`dateTime.iso8601`	`DateTime` 或 `datetime.datetime` . 返回的类型取决于 use_builtin_types 和 use_datetime flag。
`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客户机模块当前不封送内置类型子类的实例。

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

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

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

在 3.6 版更改: 增加了对带有前缀的类型标签的支持（例如 ex:nil ）添加了对ApacheXML-RPC实现用于数字的其他类型的解组支持： i1 ， i2 ， i8 ， biginteger ， float 和 bigdecimal . 有关说明，请参阅http://ws.apache.org/xmlrpc/types.html。

参见

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

服务器代理对象¶

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

支持XML内省API的服务器支持在保留的 system 属性：

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

ServerProxy.system.methodSignature(name)¶

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

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

签名本身仅限于方法所期望的顶级参数。例如，如果一个方法需要一个结构数组作为参数，并且它返回一个字符串，那么它的签名就是“string，array”。如果它需要三个整数并返回一个字符串，则其签名为“string，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)))

日期时间对象¶

class xmlrpc.client.DateTime¶

这个类可以用epoch、时间元组、iso 8601时间/日期字符串或 datetime.datetime 实例。它有以下方法，主要由编组/解编代码内部使用支持：

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

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

它还通过丰富的比较和 __repr__() 方法。

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

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¶

这个类可以从字节数据（可能包括nuls）初始化。对 Binary 对象由属性提供：

data¶: 二进制数据由 Binary 实例。数据作为 bytes 对象。

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

decode(bytes)¶: 接受Base64 bytes 对象并将其解码为实例的新数据。

encode(out)¶

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

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

它还通过 __eq__() 和 __ne__() 方法。

二进制对象的示例用法。我们将通过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¶

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

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

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

errcode¶: 错误代码。

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

headers¶: 包含触发错误的HTTP/HTTPS请求头的dict。

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

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)¶: 创建用于boxcar方法调用的对象。 服务器 是调用的最终目标。可以调用结果对象，但它们将立即返回 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))

便利功能¶

xmlrpc.client.dumps(params, methodname=None, methodresponse=None, encoding=None, allow_none=False)¶: 转换 帕拉姆 进入XML-RPC请求。或做出回应，如果 方法反应 是真的。 帕拉姆 可以是参数的元组，也可以是 Fault 异常类。如果 方法反应 为真，只能返回单个值，这意味着 帕拉姆 长度必须为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) . 帕拉姆 是一组参数； 方法名称 是字符串，或 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示例 .

脚注

1: 这种方法首次出现在 a discussion on xmlrpc.com .

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

服务器代理对象¶

日期时间对象¶

二进制对象¶

故障对象¶

原结肠镜对象¶

多所有对象¶

便利功能¶

客户端使用示例¶

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

Table of Contents

上一个主题

下一个主题

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

服务器代理对象¶

日期时间对象¶

二进制对象¶

故障对象¶

原结肠镜对象¶

多所有对象¶

便利功能¶

客户端使用示例¶

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

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