xmlrpc.client --- XML-RPC 客戶端訪問?

源代碼: Lib/xmlrpc/client.py


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í)行所有必要的證書和主機名檢查。

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)試旗標。

下列形參控制所返回代理實例的使用。 如果 allow_none 為真值,則 Python 常量 None 將被轉(zhuǎn)寫為 XML;默認行為是針對 None 引發(fā) TypeError。 這是對 XML-RPC 規(guī)格的一個常用擴展,但并不被所有客戶端和服務(wù)器所支持;請參閱 http://ontosys.com/xml-rpc/extensions.php 了解詳情。 use_builtin_types 旗標可被用來將日期/時間值表示為 datetime.datetime 對象而將二進制數(shù)據(jù)表示為 bytes 對象;此旗標默認為假值。 datetime.datetime, bytesbytearray 對象可以被傳給調(diào)用操作。 headers 形參為可選的隨每次請求發(fā)送的 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' 標頭,并在發(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 類型

boolean

bool

int, i1, i2, i4, i8 或者 biginteger

int 的范圍從 -2147483648 到 2147483647。值將獲得 <int> 標志。

doublefloat

float。值將獲得 <double> 標志。

string

str

array

listtuple 包含整合元素。數(shù)組以 lists 形式返回。

struct

dict。 鍵必須為字符串,值可以為任何適用的類型。 可以傳入用戶自定義類的對象;只有其 __dict__ 屬性會被傳輸。

dateTime.iso8601

DateTimedatetime.datetime。返回的類型取決于 use_builtin_typesuse_datetime 標志的值。

base64

Binary, bytesbytearray。返回的類型取決于 use_builtin_types 標志的值。

nil

None 常量。僅當 allow_none 為true時才允許傳遞。

bigdecimal

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 傳輸層中的錯誤。 FaultProtocolError 都派生自名為 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ù),請使用 bytesbytearray 類或者下文描述的 Binary 包裝器類。

Server 被保留作為 ServerProxy 的別名用于向下兼容。 新的代碼應(yīng)當使用 ServerProxy。

在 3.5 版更改: 增加了 context 參數(shù)。

在 3.6 版更改: 增加了對帶有前綴的類型標簽的支持 (例如 ex:nil)。 增加了對反 marshall 被 Apache XML-RPC 實現(xiàn)用于表示數(shù)值的附加類型的支持: i1, i2, i8, biginteger, floatbigdecimal。 請參閱 http://ws.apache.org/xmlrpc/types.html 了解詳情。

參見

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ù)或是表示錯誤的 FaultProtocolError 對象。

支持 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 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()

前述服務(wù)器的客戶端代碼:

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 對象?

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

前述服務(wù)器的客戶端代碼:

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 對象?

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

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

前述服務(wù)器的客戶端代碼:

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 對象?

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 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 對象?

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

前述服務(wù)器的客戶端代碼:

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

便捷函數(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 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 服務(wù)器,你必須自行定義一個傳輸。 下面的例子演示了具體做法:

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

客戶端與服務(wù)器用法的示例?

參見 SimpleXMLRPCServer 示例。

備注

1

此做法被首次提及是在 a discussion on xmlrpc.com。