21.26. xmlrpc.client – клиентский доступ XML-RPC¶xmlrpc.client – XML-RPC client access

21.26.1. Объекты ServerProxy¶ServerProxy Objects

Экземпляр ServerProxy имеет метод, соответствующий каждому удаленному вызову процедуры, принимаемому XML-RPC сервером. Вызов метода выполняет RPC, диспетчеризуемый по имени и сигнатуре аргументов (например, одно и то же имя метода может быть перегружено несколькими сигнатурами аргументов). RPC завершается возвратом значения, которое может быть либо возвращенными данными в совместимом типе, либо Fault или ProtocolError объектом, указывающим на ошибку.

Серверы, поддерживающие API интроспекции XML, предоставляют несколько общих методов, сгруппированных в зарезервированном атрибуте system:

ServerProxy.system.listMethods()¶

Этот метод возвращает список строк, по одной для каждого (не системного) метода, поддерживаемого XML-RPC сервером.

ServerProxy.system.methodSignature(name)¶

Этот метод принимает один параметр – имя метода, реализованного XML-RPC сервером. Он возвращает массив возможных сигнатур для этого метода. Сигнатура – это массив типов. Первый из этих типов – возвращаемый тип метода, остальные – параметры.

Поскольку допускается несколько сигнатур (т.е. перегрузка), этот метод возвращает список сигнатур, а не один элемент.

Сигнатуры ограничены параметрами верхнего уровня, ожидаемыми методом. Например, если метод ожидает один массив структур в качестве параметра и возвращает строку, его сигнатура – просто «string, array». Если он ожидает три целых числа и возвращает строку, его сигнатура – «string, int, int, int».

Если для метода не определена сигнатура, возвращается не-массив. В Python это означает, что тип возвращаемого значения будет чем-то отличным от list.

ServerProxy.system.methodHelp(name)¶

Этот метод принимает один параметр – имя метода, реализованного XML-RPC сервером. Он возвращает строку документации, описывающую использование этого метода. Если такая строка отсутствует, возвращается пустая строка. Строка документации может содержать HTML-разметку.

Далее следует работающий пример. Код сервера:

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

Клиентский код для указанного сервера:

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

21.26.2. Объекты DateTime¶DateTime Objects

class xmlrpc.client.DateTime¶

Этот класс можно инициализировать секундами с начала эпохи, временным кортежем, строкой даты/времени в формате ISO 8601 или экземпляром datetime.datetime. Он имеет следующие методы, поддерживаемые в основном для внутреннего использования кодом маршалинга/демаршалинга:

decode(string)¶

Принимает строку в качестве нового значения времени экземпляра.

encode(out)¶

Записывает XML-RPC кодировку этого элемента DateTime в потоковый объект out .

Он также поддерживает некоторые встроенные операторы Python через методы rich comparison и __repr__().

Далее следует работающий пример. Код сервера:

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

Клиентский код для указанного сервера:

import xmlrpc.client
import datetime

proxy = xmlrpc.client.ServerProxy("http://localhost:8000/")

today = proxy.today()
# преобразует строку в формате ISO8601 в объект datetime
converted = datetime.datetime.strptime(today.value, "%Y%m%dT%H:%M:%S")
print("Today: %s" % converted.strftime("%d.%m.%Y, %H:%M"))

21.26.3. Объекты Binary¶Binary Objects

class xmlrpc.client.Binary¶

Этот класс можно инициализировать данными bytes (которые могут содержать NUL-символы). Основной доступ к содержимому объекта Binary предоставляется через атрибут:

data¶

Двоичные данные, инкапсулированные экземпляром Binary. Данные предоставляются как объект bytes.

Объекты Binary имеют следующие методы, предназначенные в основном для внутреннего использования кодом маршалинга/демаршалинга:

decode(bytes)¶

Принимает объект base64 bytes и декодирует его как новые данные экземпляра.

encode(out)¶

Записывает XML-RPC base64-кодировку этого двоичного объекта в потоковый объект out.

Закодированные данные будут содержать переводы строки каждые 76 символов в соответствии с RFC 2045, раздел 6.8, что было фактическим стандартом спецификации base64 на момент написания спецификации XML-RPC.

Он также поддерживает некоторые встроенные операторы Python через __eq__() и __ne__().

Пример использования двоичных объектов. Мы собираемся передать изображение через 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)

21.26.4. Объекты Fault¶Fault Objects

class xmlrpc.client.Fault¶

Объект Fault инкапсулирует содержимое тега ошибки (fault tag) XML-RPC. Объекты Fault имеют следующие атрибуты:

faultCode¶

Строка, указывающая тип ошибки.

faultString¶

Строка, содержащая диагностическое сообщение, связанное с ошибкой.

В следующем примере мы намеренно вызовем Fault, возвращая объект сложного типа. Код сервера:

from xmlrpc.server import SimpleXMLRPCServer

# Произойдёт ошибка маршалинга, потому что возвращается
# комплексное число
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()

Клиентский код для указанного сервера:

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)

21.26.5. Объекты ProtocolError¶ProtocolError Objects

class xmlrpc.client.ProtocolError¶

Объект ProtocolError описывает протокольную ошибку на уровне нижележащего транспорта (например, ошибку 404 «не найдено», если сервер по указанному URI не существует). Он имеет следующие атрибуты:

url¶

URI или URL, вызвавший ошибку.

errcode¶

Код ошибки.

errmsg¶

Сообщение об ошибке или диагностическая строка.

headers¶

Словарь (dict), содержащий заголовки HTTP/HTTPS-запроса, вызвавшего ошибку.

В следующем примере мы намеренно вызовем ProtocolError, предоставив неверный URI:

import xmlrpc.client

# Создание ServerProxy с URI, который не отвечает на XMLRPC-запросы
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)

21.26.6. Объекты MultiCall¶MultiCall Objects

Объект MultiCall позволяет инкапсулировать несколько вызовов к удалённому серверу в один запрос 1.

class xmlrpc.client.MultiCall(server)¶

Создаёт объект для группировки вызовов методов. server – конечная цель вызова. Вызовы могут направляться результирующему объекту, но они сразу же возвращают None, и сохраняют только имя метода и параметры в объект MultiCall. Вызов самого объекта приводит к передаче всех сохранённых вызовов в виде одного запроса system.multicall. Результатом этого вызова является generator; итерация по этому генератору даёт отдельные результаты.

Далее приведён пример использования этого класса. Серверный код:

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

# Простой сервер с простыми арифметическими функциями
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()

Клиентский код для указанного сервера:

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

21.26.7. Вспомогательные функции¶Convenience Functions

xmlrpc.client.dumps(params, methodname=None, methodresponse=None, encoding=None, allow_none=False)¶

Преобразует params в запрос XML-RPC. Или в ответ, если methodresponse истинно. params может быть кортежем аргументов или экземпляром Fault класса исключения. Если methodresponse истинно, только одно значение может быть возвращено, то есть params должен иметь длину 1. encoding, если указан, это кодировка для генерируемого XML; по умолчанию UTF-8. Значение None Python не может использоваться в стандартном 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_types можно использовать, чтобы значения даты/времени представлялись как объекты datetime.datetime, а бинарные данные – как объекты bytes; по умолчанию этот флаг выключен.

Устаревший флаг use_datetime похож на use_builtin_types, но применяется только к значениям даты/времени.

Изменено в версии 3.3: Добавлен флаг use_builtin_types.

21.26.8. Пример использования клиента¶Example of Client Usage

# простая тестовая программа (из спецификации XML-RPC)
from xmlrpc.client import ServerProxy, Error

# server = ServerProxy("http://localhost:8000") # локальный сервер
with ServerProxy("http://betty.userland.com") as proxy:

    print(proxy)

    try:
        print(proxy.examples.getStateName(41))
    except Error as v:
        print("ERROR", v)

Для доступа к XML-RPC серверу через HTTP-прокси необходимо определить собственный транспорт. В следующем примере показано, как это сделать:

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

21.26.9. Пример использования клиента и сервера¶Example of Client and Server Usage

См. пример SimpleXMLRPCServer.

Сноски

1

Этот подход был впервые представлен в обсуждении на xmlrpc.com.