– XML-RPC客户端访问 – Internet协议和支持（Python教程）（参考资料）
xmlrpc.client– XML–RPC客户端访问
源代码： Lib / xmlrpc / client.py
XML–RPC是一种使用通过HTTP传递的XML的远程过程调用方法（S）作为atransport。有了它，客户端可以在远程服务器上调用带有参数的方法（服务器由URI命名）并获取结构化数据。这个模块支持编写XML-RPC客户端代码;它处理在线上的一致Python对象和XML之间的所有转换细节.
Warning
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, *, context=None) -
在版本3.3中更改：添加了use_builtin_types标志.
一个
ServerProxyinstance是一个管理与ismote XML-RPC服务器通信的对象。所需的第一个参数是URI（统一ResourceIndicator），通常是服务器的URL。可选的secondargument是一个传输工厂实例;默认情况下，它是https：URL的内部SafeTransport实例，否则是内部HTTPTransport实例。可选的第三个参数是anncoding，默认为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对象可以传递给调用。过时的use_datetime标志类似于use_builtin_types但它只适用于日期/时间值.HTTP和HTTPS传输支持HTTPBasic身份验证的URL语法扩展：
http://user:pass@host:port/path。user:pass部分将被base64编码为HTTP’Authorization’标头，并在调用XML-RPC方法时作为连接过程的一部分发送到远程服务器。如果远程服务器需要BasicAuthentication用户和密码，则只需使用此选项。如果提供了HTTPS URL，context可能ssl.SSLContext并配置底层HTTP连接的SSL设置.返回的实例是一个代理对象，其方法可用于在远程服务器上调用相应的RPC调用。如果远程服务器支持thetrospection API，则代理也可以用于向远程服务器查询它支持的方法（服务发现）并获取其他服务器 – 关联的元数据.
符合要求的类型（例如，可以通过XML编组）包括以下内容（除非另有说明，否则它们将被解组为相同的Python类型）：
XML-RPC类型 Python类型 booleanboolint,i1,i2,i4,i8或bigintegerint范围从-2147483648到2147483647.Values得到<int>标签double或floatfloat。值得到<double>tag.stringstrarraylist或tuple包含了一致的元素。数组以lists.structdict返回。键必须是字符串，值可以是一致的类型。可以传入用户定义类的对象;只有他们的__dict__属性被传输.dateTime.iso8601DateTime或datetime.datetime.Returned类型取决于use_builtin_types和use_datetime flags的值base64Binary,bytes要么bytearray。返回类型取决于use_builtin_types flag.nilNone常量的值。只有在allow_none为真时才允许通过.bigdecimaldecimal.Decimal。仅返回类型.这是XML-RPC支持的完整数据类型集。方法调用也可能还有一个特殊的
Fault实例，用于表示XML-RPC服务器错误，或者ProtocolError用于表示HTTP / HTTPS传输层中的错误。Fault和ProtocolError派生自一个名为Error的基类。请注意，xmlrpc客户端模块当前不是内置类型子类的marshalinstance .当传递字符串时，特殊于XML的字符，如
<,>和&将是自动逃脱。但是，调用者有责任确保该字符串没有XML中不允许的字符，例如ASCII值介于0和31之间的控制字符（当然，tab，换行符和回车符除外）;如果不这样做，将导致XML-RPCrequest不是格式良好的XML。如果你必须通过XML-RPC传递任意字节，使用bytes或bytearray类或下面描述的Binary包装类.Server保留为别名对于ServerProxy的向后兼容性。新代码应该使用ServerProxy.在版本3.5中更改：添加了context参数
更改版本3.6：添加了带前缀的类型标签的支持（例如
ex:nil）。增加了对XML XML-RPCimplementation用于数字的其他类型的解组支持：i1,i2,i8,biginteger,float和bigdecimal。参见http：//ws.apache.org/xmlrpc/types.html的描述.
参见
- XML-RPC HOWTO
- 对XML-RPC操作和客户端的一个很好的描述几种语言的软件。包含XML-RPC客户端开发人员需要知道的几乎所有内容.
- XML-RPC内省
- 描述内省的XML-RPC协议扩展.
- XML-RPC规范
- 官方规范.
- 非官方的XML-RPC勘误表
- Fredrik Lundh的“非官方勘误表，旨在澄清XML-RPC规范中的某些细节，如同以及在设计自己的XML-RPCimplementations时使用的“最佳实践”的提示。“
ServerProxy Objects
A ServerProxyinstance具有与XML-RPC服务器接受的每个remoteprocedure调用相对应的方法。调用该方法执行一个RPC，由名称和参数签名分派（例如，相同的方法名称可以用多个参数签名重载）。RPC通过返回一个值来完成，该值可以是符合类型的返回数据，也可以是Fault或ProtocolError表示错误的对象.
支持XML内省API的服务器支持一些常用的方法，这些方法在保留的system属性下
ServerProxy.system.listMethods（）-
此方法返回一个字符串列表，一个用于XML-RPC服务器支持的每个（非系统）方法.
ServerProxy.system.methodSignature(name )-
此方法采用一个参数，即XML-RPCserver实现的方法的名称。它返回此方法的可能签名数组。签名是一系列类型。这些类型中的第一种是方法的返回类型，其余是参数.
因为允许多个签名（即重载），所以此方法返回签名列表而不是单个签名.
签名本身仅限于amethod预期的顶级参数。例如，如果一个方法需要一个结构数组作为参数，并且它返回一个字符串，那么它的签名就是“string，array”。如果它期望有三个整数并返回一个字符串，那么它的签名是“string，int，int，int”.
如果没有为方法定义签名，则返回非数组值。InPython这意味着返回值的类型将是列表之外的东西.
ServerProxy.system.methodHelp(name）-
此方法采用一个参数，即XML-RPCserver实现的方法的名称。它返回描述该方法使用的文档字符串。如果没有这样的字符串可用，则返回空字符串。documentationstring可能包含HTML标记.
在版本3.5中更改：的实例ServerProxy支持上下文管理器关闭底层运输的协议.
下面是一个工作实例。服务器代码：
from xmlrpc.server import SimpleXMLRPCServerdef is_even(n): return n % 2 == 0server = SimpleXMLRPCServer(("localhost", 8000))print("Listening on port 8000...")server.register_function(is_even, "is_even")server.serve_forever()
前一个服务器的客户端代码：
import xmlrpc.clientwith 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
- class
xmlrpc.client.DateTime -
自从纪元，时间尺，ISO 8601时间/日期字符串或
datetime.datetime实例。它有以下方法，主要由编组/解组编码内部使用支持：decode（string）-
接受一个字符串作为实例的新时间值.
encode（out）-
写这个
DateTime项目到outstreamobject.
它还通过丰富的比较支持Python的某些内置运算符和
__repr__()方法。
下面是一个工作实例。服务器代码：
import datetimefrom xmlrpc.server import SimpleXMLRPCServerimport xmlrpc.clientdef 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.clientimport datetimeproxy = xmlrpc.client.ServerProxy("http://localhost:8000/")today = proxy.today()# convert the ISO8601 string to a datetime objectconverted = 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对象内容的初步访问由anattribute提供：data-
由
Binary实例。数据提供为bytes对象
Binary对象有以下方法，主要由编组/解组编码支持：decode（bytes）-
接受一个base64
bytes对象并将其解码为实例的新数据.
encode(out)-
写这个二进制文件的XML–RPC base 64编码项目到out流对象.
根据 RFC 2045第6.8节，编码数据每76个字符都会有换行符，这是编写XML–RPC规范时事实上的标准base64规范.
它还支持某些Python的内置操作符
__eq__()和__ne__()methods.
from xmlrpc.server import SimpleXMLRPCServerimport xmlrpc.clientdef 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.clientproxy = 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故障标记的内容。Faultobjects具有以下属性：faultCode-
指示故障类型的字符串.
faultString-
包含与fault相关的诊断消息的字符串
在下面的例子中，我们将故意通过返回复杂类型的对象来导致Fault。服务器代码：
from xmlrpc.server import SimpleXMLRPCServer# A marshalling error is going to occur because we"re returning a# complex numberdef add(x, y): return x+y+0jserver = SimpleXMLRPCServer(("localhost", 8000))print("Listening on port 8000...")server.register_function(add, "add")server.serve_forever()
前面服务器的客户端代码：
import xmlrpc.clientproxy = 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
- class
xmlrpc.client.ProtocolError -
ProtocolError对象描述了底层传输层中的协议错误（如如果URI所指定的服务器不存在，则为404’未找到’错误。它具有以下属性：url-
触发错误的URI或URL
errcode-
错误代码
errmsg-
错误信息或诊断字符串.
在下面的示例中，我们将通过提供无效的URI故意导致ProtocolError：
import xmlrpc.client# create a ServerProxy with a URI that doesn"t respond to XMLRPC requestsproxy = 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对象
MultiCall对象提供了一种方法，可以将对ismote服务器的多个调用封装到单个请求中[1] .
- class
xmlrpc.client.MultiCall（server） -
创建一个用于boxcar方法调用的对象。server是呼叫的最终目标。可以对结果对象进行调用，但是会立即返回
None，只存储MultiCall对象中的调用名称和参数。调用对象本身会导致所有存储的调用作为单个system.multicall请求传输。这个电话的结果是发电机;迭代这个发生器产生个人结果.
下面是该类的用法示例。服务器代码：
from xmlrpc.server import SimpleXMLRPCServerdef add(x, y): return x + ydef subtract(x, y): return x - ydef multiply(x, y): return x * ydef divide(x, y): return x // y# A simple server with simple arithmetic functionsserver = 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.clientproxy = 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，ifsupplied，是在生成的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_typesflag可用于使日期/时间值呈现为datetime.datetime对象和二进制数据，表示为bytes对象;这个标志默认是假的过时的use_datetimeflag类似于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 serverwith 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服务器，您需要定义customtransport。以下示例说明如何：
import http.clientimport xmlrpc.clientclass 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 connectiontransport = ProxiedTransport()transport.set_proxy("proxy-server", 8080)server = xmlrpc.client.ServerProxy("http://betty.userland.com", transport=transport)print(server.examples.getStateName(41))
评论被关闭。