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

Объекты 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)))

Объекты даты и времени¶DateTime Objects

class xmlrpc.client.DateTime¶

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

decode(string)¶

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

encode(out)¶

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

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

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

import datetime as dt
from xmlrpc.server import SimpleXMLRPCServer
import xmlrpc.client

def today():
    today = dt.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 as dt

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

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

Двоичные объекты¶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)

Объекты Fault¶Fault Objects

class xmlrpc.client.Fault¶

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

faultCode¶

Целое число (int), указывающее тип ошибки.

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)

Объекты 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)

Объекты MultiCall¶MultiCall Objects

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

class xmlrpc.client.MultiCall(server)¶

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

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

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

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

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

Преобразует params в XML-RPC запрос или в ответ, если methodresponse равно true. params может быть либо кортежем аргументов, либо экземпляром класса исключения Fault. Если methodresponse равно true, может быть возвращено только одно значение, то есть 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.

Пример клиентского использования¶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))

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

См. пример SimpleXMLRPCServer.

Сноски