建站
咨詢
售后
建站咨詢
新聞中心
xmlrpc.client —- XML-RPC 客戶端訪問
源代碼: Lib/xmlrpc/client.py
成都創(chuàng)新互聯(lián)公司長期為上千客戶提供的網(wǎng)站建設(shè)服務(wù)，團隊從業(yè)經(jīng)驗10年，關(guān)注不同地域、不同群體，并針對不同對象提供差異化的產(chǎn)品和服務(wù)；打造開放共贏平臺，與合作伙伴共同營造健康的互聯(lián)網(wǎng)生態(tài)環(huán)境。為龍城企業(yè)提供專業(yè)的成都做網(wǎng)站、網(wǎng)站制作、成都外貿(mào)網(wǎng)站建設(shè)，龍城網(wǎng)站改版等技術(shù)服務(wù)。擁有10余年豐富建站經(jīng)驗和眾多成功案例,為您定制開發(fā)。
XML-RPC 是一種遠程過程調(diào)用方法，它以使用 HTTP(S) 傳遞的 XML 作為載體。 通過它，客戶端可以在遠程服務(wù)器（服務(wù)器以 URI 指明）上調(diào)用帶參數(shù)的方法并獲取結(jié)構(gòu)化的數(shù)據(jù)。 本模塊支持編寫 XML-RPC 客戶端代碼；它會處理在通用 python 對象和 XML 之間進行在線翻譯的所有細節(jié)。
警告
xmlrpc.client 模塊對于惡意構(gòu)建的數(shù)據(jù)是不安全的。 如果你需要解析不受信任或未經(jīng)身份驗證的數(shù)據(jù)，請參閱 XML 漏洞。
在 3.5 版更改: 對于 HTTPS URI，現(xiàn)在 xmlrpc.client 默認會執(zhí)行所有必要的證書和主機名檢查。
Availability: not Emscripten, not WASI.
This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssembly platforms for more information.
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 實例是管理與遠程 XML-RPC 服務(wù)器通信的對象。 要求的第一個參數(shù)為 URI (統(tǒng)一資源定位符)，通常就是服務(wù)器的 URL。 可選的第二個參數(shù)為傳輸工廠實例；在默認情況下對于 https: URL 是一個內(nèi)部 SafeTransport 實例，在其他情況下則是一個內(nèi)部 HTTP Transport 實例。 可選的第三個參數(shù)為編碼格式，默認為 UTF-8。 可選的第四個參數(shù)為調(diào)試旗標。
The following parameters govern the use of the returned proxy instance. If allow_none is true, the Python constant None will be translated into XML; the default behaviour is for None to raise a TypeError. This is a commonly used extension to the XML-RPC specification, but isn’t supported by all clients and servers; see http://ontosys.com/xml-rpc/extensions.php for a description. The use_builtin_types flag can be used to cause date/time values to be presented as datetime.datetime objects and binary data to be presented as bytes objects; this flag is false by default. datetime.datetime, bytes and bytearray objects may be passed to calls. The headers parameter is an optional sequence of HTTP headers to send with each request, expressed as a sequence of 2-tuples representing the header name and value. (e.g. [('Header-Name', 'value')]). The obsolete use_datetime flag is similar to use_builtin_types but it applies only to date/time values.
在 3.3 版更改: 增加了 use_builtin_types 旗標。
在 3.8 版更改: 增加了 headers 形參。
HTTP 和 HTTPS 傳輸均支持用于 HTTP 基本身份驗證的 URL 語法擴展: http://user:pass@host:port/path。 user:pass 部分將以 base64 編碼為 HTTP ‘Authorization’ 標頭，并在發(fā)起調(diào)用 XML-RPC 方法時作為連接過程的一部分發(fā)送給遠程服務(wù)器。 你只需要在遠程服務(wù)器要求基本身份驗證賬號和密碼時使用此語法。 如果提供了 HTTPS URL，context 可以為 ssl.SSLContext 并配置有下層 HTTPS 連接的 SSL 設(shè)置。
返回的實例是一個代理對象，具有可被用來在遠程服務(wù)器上發(fā)起相應(yīng) RPC 調(diào)用的方法。 如果遠程服務(wù)器支持內(nèi)省 API，則也可使用該代理對象在遠程服務(wù)器上查詢它所支持的方法（服務(wù)發(fā)現(xiàn)）并獲取其他服務(wù)器相關(guān)的元數(shù)據(jù)
適用的類型（即可通過 XML 生成 marshall 對象），包括如下類型（除了已說明的例外，它們都會被反 marshall 為同樣的 Python 類型）:
|
XML-RPC類型 |
Python 類型 |
|---|---|
|
bool |
|
int 的范圍從 -2147483648 到 2147483647。值將獲得 |
|
float。值將獲得 |
|
str |
|
list 或 tuple 包含整合元素。數(shù)組以 lists 形式返回。 |
|
dict。 鍵必須為字符串，值可以為任何適用的類型。 可以傳入用戶自定義類的對象；只有其 dict 屬性會被傳輸。 |
|
DateTime 或 datetime.datetime。返回的類型取決于 use_builtin_types 和 use_datetime 標志的值。 |
|
Binary, bytes 或 bytearray。返回的類型取決于 use_builtin_types 標志的值。 |
|
|
|
decimal.Decimal. 僅返回類型。 |
這是This is the full set of data types supported by XML-RPC 所支持數(shù)據(jù)類型的完整集合。 方法調(diào)用也可能引發(fā)一個特殊的 Fault 實例，用來提示 XML-RPC 服務(wù)器錯誤，或是用 ProtocolError 來提示 HTTP/HTTPS 傳輸層中的錯誤。 Fault 和 ProtocolError 都派生自名為 Error 的基類。 請注意 xmlrpc client 模塊目前不可 marshal 內(nèi)置類型的子類的實例。
當傳入字符串時，XML 中的特殊字符如 <, > 和 & 將被自動轉(zhuǎn)義。 但是，調(diào)用方有責任確保字符串中沒有 XML 中不允許的字符，例如 ASCII 值在 0 和 31 之間的控制字符（當然，制表、換行和回車除外）；不這樣做將導(dǎo)致 XML-RPC 請求的 XML 格式不正確。 如果你必須通過 XML-RPC 傳入任意字節(jié)數(shù)據(jù)，請使用 bytes 或 bytearray 類或者下文描述的 Binary 包裝器類。
Server 被保留作為 ServerProxy 的別名用于向下兼容。 新的代碼應(yīng)當使用 ServerProxy。
在 3.5 版更改: 增加了 context 參數(shù)。
在 3.6 版更改: Added support of type tags with prefixes (e.g. ex:nil). Added support of unmarshalling additional types used by Apache XML-RPC implementation for numerics: i1, i2, i8, biginteger, float and bigdecimal. See https://ws.apache.org/xmlrpc/types.html for a description.
參見
XML-RPC HOWTO
以多種語言對 XML-RPC 操作和客戶端軟件進行了很好的說明。 包含 XML-RPC 客戶端開發(fā)者所需知道的幾乎任何事情。
XML-RPC Introspection
描述了用于內(nèi)省的 XML-RPC 協(xié)議擴展。
XML-RPC Specification
官方規(guī)范說明。
ServerProxy 對象
ServerProxy 實例有一個方法與 XML-RPC 服務(wù)器所接受的每個遠程過程調(diào)用相對應(yīng)。 調(diào)用該方法會執(zhí)行一個 RPC，通過名稱和參數(shù)簽名來調(diào)度（例如同一個方法名可通過多個參數(shù)簽名來重載）。 RPC 結(jié)束時返回一個值，它可以是適用類型的返回數(shù)據(jù)或是表示錯誤的 Fault 或 ProtocolError 對象。
支持 XML 內(nèi)省 API 的服務(wù)器還支持一些以保留的 system 屬性分組的通用方法:
ServerProxy.system.listMethods()
此方法返回一個字符串列表，每個字符串都各自對應(yīng) XML-RPC 服務(wù)器所支持的（非系統(tǒng)）方法。
ServerProxy.system.methodSignature(name)
此方法接受一個形參，即某個由 XML-RPC 服務(wù)器所實現(xiàn)的方法名稱。 它返回一個由此方法可能的簽名組成的數(shù)組。 一個簽名就是一個類型數(shù)組。 這些類型中的第一個是方法的的返回類型，其余的均為形參。
由于允許多個簽名（即重載），此方法是返回一個簽名列表而非一個單例。
簽名本身被限制為一個方法所期望的最高層級形參。 舉例來說如果一個方法期望有一個結(jié)構(gòu)體數(shù)組作為形參，并返回一個字符串，則其簽名就是 “string, array”。 如果它期望有三個整數(shù)并返回一個字符串，則其簽名是 “string, int, int, int”。
如果方法沒有定義任何簽名，則將返回一個非數(shù)組值。 在 Python 中這意味著返回值的類型為列表以外的類型。
ServerProxy.system.methodHelp(name)
此方法接受一個形參，即 XML-RPC 服務(wù)器所實現(xiàn)的某個方法的名稱。 它返回描述相應(yīng)方法用法的文檔字符串。 如果沒有可用的文檔字符串，則返回空字符串。 文檔字符串可以包含 HTML 標記。
在 3.5 版更改: ServerProxy 的實例支持 context manager 協(xié)議用于關(guān)閉下層傳輸。
以下是一個可運行的示例。 服務(wù)器端代碼:
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()
前述服務(wù)器的客戶端代碼:
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 對象
class xmlrpc.client.DateTime
該類的初始化可以使用距離 Unix 紀元的秒數(shù)、時間元組、ISO 8601 時間/日期字符串或 datetime.datetime 實例。 它具有下列方法，主要是為 marshall 和反 marshall 代碼的內(nèi)部使用提供支持:
-
decode(string)
接受一個字符串作為實例的新時間值。
-
encode(out)
將此 DateTime 條目的 XML-RPC 編碼格式寫入到 out 流對象。
它還通過富比較和 __repr__() 方法來支持某些 Python 內(nèi)置運算符。
以下是一個可運行的示例。 服務(wù)器端代碼:
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()
前述服務(wù)器的客戶端代碼:
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"))
Binary 對象
class xmlrpc.client.Binary
該類的初始化可以使用字節(jié)數(shù)據(jù)（可包括 NUL）。 對 Binary 對象的初始訪問是由一個屬性來提供的:
-
data
被 Binary 實例封裝的二進制數(shù)據(jù)。 該數(shù)據(jù)以 bytes 對象的形式提供。
Binary 對象具有下列方法，支持這些方法主要是供 marshall 和反 marshall 代碼在內(nèi)部使用:
-
decode(bytes)
接受一個 base64 bytes 對象并將其解碼為實例的新數(shù)據(jù)。
-
encode(out)
將此二進制條目的 XML-RPC base 64 編碼格式寫入到 out 流對象。
被編碼數(shù)據(jù)將依據(jù) RFC 2045 第 6.8 節(jié) 每 76 個字符換行一次，這是撰寫 XML-RPC 規(guī)范說明時 base64 規(guī)范的事實標準。
它還通過 __eq__() 和 __ne__() 方法來支持某些 Python 內(nèi)置運算符。
該二進制對象的示例用法。 我們將通過 XMLRPC 來傳輸一張圖片:
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)
Fault 對象
class xmlrpc.client.Fault
Fault 對象封裝了 XML-RPC fault 標簽的內(nèi)容。 Fault 對象具有下列屬性:
-
faultCode
一個指明 fault 類型的整數(shù)。
-
faultString
一個包含與 fault 相關(guān)聯(lián)的診斷消息的字符串。
在接下來的示例中我們將通過返回一個復(fù)數(shù)類型的值來故意引發(fā)一個 Fault。 服務(wù)器端代碼:
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()
前述服務(wù)器的客戶端代碼:
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 對象
class xmlrpc.client.ProtocolError
ProtocolError 對象描述了下層傳輸層中的協(xié)議錯誤（例如當 URI 所指定的服務(wù)器不存在時的 404 ‘not found’ 錯誤）。 它具有下列屬性:
-
url
觸發(fā)錯誤的 URI 或 URL。
-
errcode
錯誤代碼。
-
errmsg
錯誤消息或診斷字符串。
-
headers
一個包含觸發(fā)錯誤的 HTTP/HTTPS 請求的標頭的字典。
在接下來的示例中我們將通過提供一個無效的 URI 來故意引發(fā)一個 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 對象提供了一種將對遠程服務(wù)器的多個調(diào)用封裝為一個單獨請求的方式 1。
class xmlrpc.client.MultiCall(server)
創(chuàng)建一個用于盒式方法調(diào)用的對象。 server 是調(diào)用的最終目標。 可以對結(jié)果對象發(fā)起調(diào)用，但它們將立即返回 None，并只在 MultiCall 對象中存儲調(diào)用名稱和形參。 調(diào)用該對象本身會導(dǎo)致所有已存儲的調(diào)用作為一個單獨的 system.multicall 請求被發(fā)送。 此調(diào)用的結(jié)果是一個 generator；迭代這個生成器會產(chǎn)生各個結(jié)果。
以下是該類的用法示例。 服務(wù)器端代碼:
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()
前述服務(wù)器的客戶端代碼:
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))
便捷函數(shù)
xmlrpc.client.dumps(params, methodname=None, methodresponse=None, encoding=None, allow_none=False)
請 params 轉(zhuǎn)換為一個 XML-RPC 請求。 或者當 methodresponse 為真值時則轉(zhuǎn)換為一個請求。 params 可以是一個參數(shù)元組或是一個 Fault 異常類的實例。 如果 methodresponse 為真值，只有單獨的值可以被返回，這意味著 params 的長度必須為 1。 如果提供了 encoding，則在生成的 XML 會使用該編碼格式；默認的編碼格式為 UTF-8。 Python 的 None 值不可在標準 XML-RPC 中使用；要通過擴展來允許使用它，請為 allow_none 提供一個真值。
xmlrpc.client.loads(data, use_datetime=False, use_builtin_types=False)
將一個 XML-RPC 請求或響應(yīng)轉(zhuǎn)換為 Python 對象 (params, methodname)。 params 是一個參數(shù)元組；methodname 是一個字符串，或者如果數(shù)據(jù)包沒有提供方法名則為 None。 如果 XML-RPC 數(shù)據(jù)包是代表一個故障條件，則此函數(shù)將引發(fā)一個 Fault 異常。 use_builtin_types 旗標可被用于將日期/時間值表示為 datetime.datetime 對象并將二進制數(shù)據(jù)表示為 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 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 服務(wù)器，你必須自行定義一個傳輸。 下面的例子演示了具體做法:
import http.clientimport xmlrpc.clientclass ProxiedTransport(xmlrpc.client.Transport):def set_proxy(self, host, port=None, headers=None):self.proxy = host, portself.proxy_headers = headersdef make_connection(self, host):connection = http.client.HTTPConnection(*self.proxy)connection.set_tunnel(host, headers=self.proxy_headers)self._connection = host, connectionreturn connectiontransport = ProxiedTransport()transport.set_proxy('proxy-server', 8080)server = xmlrpc.client.ServerProxy('http://betty.userland.com', transport=transport)print(server.examples.getStateName(41))
客戶端與服務(wù)器用法的示例
參見 SimpleXMLRPCServer 示例。
備注
1
此做法被首次提及是在 a discussion on xmlrpc.com。
分享題目：創(chuàng)新互聯(lián)Python教程：xmlrpc.client—-XML-RPC客戶端訪問
網(wǎng)站鏈接：http://fisionsoft.com.cn/article/cogpdid.html
