20.23. xmlrpclib — XML-RPCClient 端访问
2.2 版中的新Function。
源代码: Lib/xmlrpclib.py
XML-RPC 是一种远程过程调用方法,它使用pass HTTP(S)传递的 XML 作为传输方式。借助它,Client 端可以在远程服务器(该服务器由 URI 命名)上调用带有参数的方法,并获取结构化数据。该模块支持编写 XML-RPCClient 端代码。它处理可转换的 Python 对象和在线 XML 之间进行转换的所有细节。
Warning
xmlrpclib模块不能安全防范恶意构建的数据。如果您需要解析不可信或未经身份验证的数据,请参见XML vulnerabilities。
在版本 2.7.9 中更改:对于 HTTPS URI,默认情况下,xmlrpclib现在执行所有必要的证书和主机名检查。
-
- class *
xmlrpclib.
ServerProxy
(* uri * [,* transport * [,* encoding * [,* verbose * [,* allow_none * [,* use_datetime * [,* context *]]]]]]]))
- ServerProxy实例是 Management 与远程 XML-RPC 服务器通信的对象。所需的第一个参数是 URI(统一资源指示符),通常是服务器的 URL。可选的第二个参数是运输工厂实例;默认情况下,它是 https:URL 的内部
SafeTransport
实例,否则是内部 HTTPTransport
实例。可选的第三个参数是一种编码,默认情况下为 UTF-8.可选的第四个参数是调试标志。
- class *
以下参数控制返回的代理实例的使用。如果* allow_none *为 true,则 Python 常量None
将转换为 XML;默认行为是None
引发TypeError。这是 XML-RPC 规范的常用扩展,但并非所有 Client 端和服务器都支持。有关说明,请参见http://ontosys.com/xml-rpc/extensions.php。 * use_datetime *标志可用于使日期/时间值显示为datetime.datetime对象。默认情况下为 false。 datetime.datetime对象可以传递给调用。
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 type | Python type |
---|---|
boolean | bool |
int 或i4 | int或long的范围是-2147483648 至 2147483647. |
double | float |
string | str或unicode |
array | list 或tuple包含合格元素。数组返回为lists 。 |
struct | dict。键必须是字符串,值可以是任何兼容类型。用户定义类的对象可以传入;仅传送其dict属性。 |
dateTime.iso8601 | DateTime或datetime.datetime。返回的类型取决于* use_datetime *标志的值。 |
base64 | Binary |
nil | None 常数。仅当* allow_none *为 true 时才允许传递。 |
这是 XML-RPC 支持的完整数据类型集。方法调用可能还会引发一个特殊的Fault实例,该实例用于表示 XML-RPC 服务器错误,或者ProtocolError用来表示 HTTP/HTTPS 传输层中的错误。 Fault和ProtocolError都源自称为Error
的 Base Class。请注意,即使可以从 Python 2.2 开始,也可以对内置类型进行子类化,但是 xmlrpclib 模块当前不会封送此类子类的实例。
传递字符串时,将自动转义 XML 专用的字符,例如<
,>
和&
。但是,调用者有责任确保字符串中没有 XML 不允许的字符,例如 ASCII 值介于 0 到 31 之间的控制字符(当然,制表符,换行符和回车符除外);否则,将导致 XML-RPC 请求不是格式正确的 XML。如果必须pass XML-RPC 传递任意字符串,请使用下面描述的Binary包装器类。
Server
保留为ServerProxy的别名,以实现向后兼容。新代码应使用ServerProxy。
在版本 2.5 中更改:添加了* use_datetime *标志。
在 2.6 版中进行了更改:new-style class es 实例如果具有* __ dict __ *属性并且没有以特殊方式编组的 Base Class,则可以传递它们。
在版本 2.7.9 中进行了更改:添加了* context *参数。
See also
-
用多种语言很好地描述了 XML-RPC 操作和 Client 端软件。包含 XML-RPCClient 端开发人员需要了解的几乎所有内容。
-
描述用于自省的 XML-RPC 协议扩展。
-
官方规范。
-
弗雷德里克·隆德(Fredrik Lundh)的“非官方勘误表,旨在阐明 XML-RPC 规范中的某些细节,并暗示设计自己的 XML-RPC 实现时要使用的'最佳实践'。”
20.23.1. ServerProxy 对象
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 标记。
20.23.2. 布尔对象
可以从任何 Python 值初始化此类。返回的实例仅取决于其真实值。它passcmp(),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()
先前服务器的 Client 端代码:
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. 日期时间对象
-
类别
xmlrpclib.
DateTime
- 可以使用从纪元开始的秒数,时间 Tuples,ISO 8601 时间/日期字符串或datetime.datetime实例初始化此类。它具有以下方法,编组/解组代码主要支持内部使用:
-
decode
(* string *)- 接受一个字符串作为实例的新时间值。
-
encode
(* out *)- 将此DateTime项的 XML-RPC 编码写入* out *流对象。
它还passcmp()和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()
先前服务器的 Client 端代码:
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. 二进制对象
-
类别
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 规范。
它还passcmp()方法支持某些 Python 的内置运算符。
二进制对象的用法示例。我们将pass 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()
Client 端获取图像并将其保存到文件中:
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. 故障对象
-
类别
xmlrpclib.
Fault
- Fault对象封装 XML-RPC 故障标记的内容。故障对象具有以下属性:
-
faultCode
- 指示故障类型的字符串。
-
faultString
- 包含与故障关联的诊断消息的字符串。
在下面的示例中,我们将有意pass返回复杂类型的对象来产生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()
先前服务器的 Client 端代码:
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. ProtocolError 对象
-
类别
xmlrpclib.
ProtocolError
- ProtocolError对象描述基础传输层中的协议错误(例如,如果 URI 命名的服务器不存在,则为 404“未找到”错误)。它具有以下属性:
-
url
- 触发错误的 URI 或 URL。
-
errcode
- 错误代码。
-
errmsg
- 错误消息或诊断字符串。
-
headers
- 一个字符串,其中包含触发错误的 HTTP/HTTPS 请求的 Headers。
在下面的示例中,我们将pass提供不指向 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 版的新Function。
MultiCall对象提供了一种将对远程服务器的多个调用封装到单个请求[1]中的方法。
- 类别
xmlrpclib.
MultiCall
(服务器)
此类的用法示例如下。服务器代码
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()
先前服务器的 Client 端代码:
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. 便利Function
-
xmlrpclib.
boolean
(* value *)- 将任何 Python 值转换为 XML-RPC 布尔常量
True
或False
之一。
- 将任何 Python 值转换为 XML-RPC 布尔常量
-
xmlrpclib.
dumps
(* params * [,* methodname * [,* methodresponse * [,* encoding * [,* allow_none *]]]]) -
xmlrpclib.
loads
(* data * [,* use_datetime *])- 将 XML-RPC 请求或响应转换为 Python 对象
(params, methodname)
。 * params *是参数的 Tuples; * methodname *是字符串,如果数据包中没有方法名称,则为None
。如果 XML-RPC 数据包表示故障情况,则此函数将引发Fault异常。 * use_datetime *标志可用于使日期/时间值显示为datetime.datetime个对象;默认情况下为 false。
- 将 XML-RPC 请求或响应转换为 Python 对象
在版本 2.5 中更改:添加了* use_datetime *标志。
20.23.9. Client 端用法示例
# 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
要pass 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. Client 端和服务器使用示例
See SimpleXMLRPCServer Example.
Footnotes
- [1]
- 此方法已在xmlrpc.com 上的讨论中首次提出。