バージョン 2.2 で 新たに追加 された仕様です。
XML-RPCはXMLを利用した遠隔手続き呼び出し(Remote Procedure Call)の一種 で、HTTPをトランスポートとして使用します。XML-RPCでは、クライアントはリ モートサーバ(URIで指定されたサーバ)上のメソッドをパラメータを指定して呼 び出し、構造化されたデータを取得します。このモジュールは、XML-RPCクライ アントの開発をサポートしており、Pythonオブジェクトに適合する転送用XMLの 変換の全てを行います。
uri[, transport[, encoding[, verbose[, allow_none[, use_datetime]]]]]) |
None
は XML
に翻訳されます; デフォルトの動作は None
に対して
TypeError を送出します。
この仕様は XML-RPC 仕様でよく用いられている拡張ですが、
全てのクライアントやサーバでサポートされているわけではありません;
詳細記述については http://ontosys.com/xml-rpc/extensions.html
を参照してください。
use_datetimeフラグはdatetime.datetimeのオブジェクトとして
日付/時刻を表現する時に使用し、デフォルトでは false に設定されています。
datetime.datetime、
datetime.dateおよびdatetime.time
のオブジェクトを渡すことができます。
datetime.dateオブジェクトは
時刻``00:00:00''に変換されます。
datetime.timeオブジェクトは、
今日の日付に変換されます。
HTTP及びHTTPS通信の両方で、http://user:pass@host:port/path
のよう
なHTTP基本認証のための拡張URL構文をサポートしています。user:pass
はbase64でエンコードしてHTTPの`Authorization'ヘッダとなり、XML-RPCメソッ
ド呼び出し時に接続処理の一部としてリモートサーバに送信されます。リモート
サーバが基本認証を要求する場合のみ、この機能を利用する必要があります。
生成されるインスタンスはリモートサーバへのプロクシオブジェクトで、RPC呼 び出しを行う為のメソッドを持ちます。リモートサーバがイントロスペクション APIをサポートしている場合は、リモートサーバのサポートするメソッドを検索 (サービス検索)やサーバのメタデータの取得なども行えます。
ServerProxyインスタンスのメソッドは引数としてPythonの基礎型とオ ブジェクトを受け取り、戻り値としてPythonの基礎型かオブジェクトを返しま す。以下の型をXMLに変換(XMLを通じてマーシャルする)する事ができます(特別 な指定がない限り、逆変換でも同じ型として変換されます):
名前 | 意味 |
---|---|
boolean | 定数TrueとFalse |
整数 | そのまま |
浮動小数点 | そのまま |
文字列 | そのまま |
配列 | 変換可能な要素を含むPythonシーケンス。 戻り値はリスト。 |
構造体 | Pythonの辞書。キーは文字列のみ。全ての値は変換可能でな くてはならない。 |
日付 | エポックからの経過秒数。引数として指定する時は DataTimeラッパクラスまたは、 datetime.datetime、 datetime.date、 datetime.timeのいずれかのインスタンスを使用する。 |
バイナリ | Binaryラッパクラスのインスタンス |
上記のXML-RPCでサポートする全データ型を使用することができます。メソッド 呼び出し時、XML-RPCサーバエラーが発生するとFaultインスタンス を送出し、HTTP/HTTPSトランスポート層でエラーが発生した場合には ProtocolErrorを送出します。 Errorをベースとする FaultとProtocolErrorの両方が発生します。 Python 2.2以降では組み込み型のサ ブクラスを作成する事ができますが、現在のところxmlrpclibではそのようなサ ブクラスのインスタンスをマーシャルすることはできません。
文字列を渡す場合、"<"・">"・"&"などのXMLで特殊な意味を持 つ文字は自動的にエスケープされます。しかし、ASCII値0〜31の制御文字などの XMLで使用することのできない文字を使用することはできず、使用するとその XML-RPCリクエストはwell-formedなXMLとはなりません。そのような文字列を渡 す必要がある場合は、後述のBinaryラッパクラスを使用してください。
Serverは、上位互換性の為にServerProxyの別名として残され ています。新しいコードではServerProxyを使用してください。
バージョン 2.5 で 変更 された仕様: The use_datetime flag was added
参考: