xmlrpc.client — XML-RPCClient 端访问

源代码： Lib/xmlrpc/client.py

---

XML-RPC 是一种远程过程调用方法，它使用pass HTTP(S)传递的 XML 作为传输方式。借助它，Client 端可以在远程服务器(该服务器由 URI 命名)上调用带有参数的方法，并获取结构化数据。该模块支持编写 XML-RPCClient 端代码。它处理可转换的 Python 对象和在线 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 *)
  • ServerProxy实例是 Management 与远程 XML-RPC 服务器通信的对象。所需的第一个参数是 URI(统一资源指示符)，通常是服务器的 URL。可选的第二个参数是运输工厂实例；默认情况下，它是 https：URL 的内部SafeTransport实例，否则是内部 HTTP Transport实例。可选的第三个参数是一种编码，默认情况下为 UTF-8.可选的第四个参数是调试标志。

以下参数控制返回的代理实例的使用。如果* allow_none *为 true，则 Python 常量None将转换为 XML；默认行为是None引发TypeError。这是 XML-RPC 规范的常用扩展，但并非所有 Client 端和服务器都支持。有关说明，请参见http://ontosys.com/xml-rpc/extensions.php。 * use_builtin_types *标志可用于将日期/时间值表示为datetime.datetime个对象，将二进制数据表示为bytes个对象；默认情况下，此标志为 false。 datetime.datetime，bytes和bytearray对象可以传递给调用。 * headers 参数是随每个请求发送的可选 HTTPHeaders 序列，表示为表示标题名称和值的 2Tuples 序列。 (例如[('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“授权”Headers，并在调用 XML-RPC 方法时作为连接过程的一部分发送到远程服务器。仅当远程服务器需要基本身份验证用户和密码时，才需要使用此选项。如果提供了 HTTPS URL，则* context *可以为ssl.SSLContext并配置基础 HTTPS 连接的 SSL 设置。

返回的实例是具有方法的代理对象，该方法可用于在远程服务器上调用相应的 RPC 调用。如果远程服务器支持自省 API，则代理还可用于向远程服务器查询其支持的方法(服务发现)并获取其他与服务器相关的元数据。

兼容的类型(例如可以pass XML 编组的类型)包括以下内容(除非另有说明，否则它们不编组为相同的 Python 类型)：

这是 XML-RPC 支持的完整数据类型集。方法调用可能还会引发一个特殊的Fault实例，该实例用于表示 XML-RPC 服务器错误，或者ProtocolError用来表示 HTTP/HTTPS 传输层中的错误。 Fault和ProtocolError都源自称为Error的 Base Class。请注意，xmlrpcClient 端模块当前不封送内置类型的子类的实例。

传递字符串时，<，>和&等 XML 专用字符将自动转义。但是，调用者有责任确保字符串中没有 XML 不允许的字符，例如 ASCII 值介于 0 到 31 之间的控制字符(当然，制表符，换行符和回车符除外)；否则，将导致 XML-RPC 请求不是格式正确的 XML。如果必须pass XML-RPC 传递任意字节，请使用下面介绍的bytes或bytearray类或Binary包装器类。

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

在版本 3.5 中进行了更改：添加了* context *参数。

在版本 3.6 中进行了更改：添加了对带有前缀(例如ex:nil)的类型标签的支持。增加了对由 Apache XML-RPC 实现用于数字的编组其他类型的支持：i1，i2，i8，biginteger，float和bigdecimal。有关说明，请参见http://ws.apache.org/xmlrpc/types.html。

ServerProxy Objects

ServerProxy实例具有与 XML-RPC 服务器接受的每个远程过程调用相对应的方法。调用该方法会执行 RPC，该 RPC 由名称和参数签名共同调度(例如，相同的方法名称可能会因多个参数签名而重载)。 RPC pass返回一个值结束，该值可以是一致类型的数据，也可以是表示错误的Fault或ProtocolError对象。

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

• ServerProxy.system. listMethods ( )

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

• ServerProxy.system. methodSignature(* name *)

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

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

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

先前服务器的 Client 端代码：

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

DateTime Objects

• 类别 xmlrpc.client. DateTime

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

• decode(* string *)

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

• encode(* out *)

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

它还pass丰富的比较和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()

先前服务器的 Client 端代码：

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

Binary Objects

• 类别 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 规范。

它还passeq()和ne()方法支持某些 Python 的内置运算符。

二进制对象的用法示例。我们将pass 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()

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

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)

Fault Objects

• 类别 xmlrpc.client. Fault

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

• faultCode

  • 指示故障类型的字符串。

• faultString

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

在下面的示例中，我们将有意pass返回复杂类型的对象来产生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()

先前服务器的 Client 端代码：

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)

ProtocolError Objects

• 类别 xmlrpc.client. ProtocolError

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

• url

  • 触发错误的 URI 或 URL。

• errcode

  • 错误代码。

• errmsg

  • 错误消息或诊断字符串。

• headers

  • 包含触发错误的 HTTP/HTTPS 请求 Headers 的字典。

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

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

• 类别 xmlrpc.client. MultiCall(服务器)
  • 创建一个用于 boxcar 方法调用的对象。服务器是呼叫的finally目标。可以对结果对象进行调用，但是它们将立即返回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()

先前服务器的 Client 端代码：

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

Convenience Functions

• xmlrpc.client. dumps(* params ， methodname = None ， methodresponse = None ， encoding = None ， allow_none = False *)

  • 将* params 转换为 XML-RPC 请求。如果 methodresponse *为 true，则返回响应。 * params 可以是参数的 Tuples，也可以是Fault异常类的实例。如果 methodresponse 为 true，则只能返回一个值，这意味着 params 的长度必须为 1. encoding (如果提供)是在生成的 XML 中使用的编码；默认值为 UTF-8. Python 的None值不能在标准 XML-RPC 中使用；要允许pass extensions 使用它，请为 allow_none *提供一个真值。

• xmlrpc.client. loads(* data ， use_datetime = False ， use_builtin_types = False *)

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

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

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

Client 端用法示例

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

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

Client 端和服务器使用示例

See SimpleXMLRPCServer Example.

Footnotes

• [1]
  • 此方法已在xmlrpc.com 上的讨论中首次提出。