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

Объекты ServerProxy

Экземпляр 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

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()
# convert the ISO 8601 string to a datetime object
converted = dt.datetime.strptime(today.value, "%Y%m%dT%H:%M:%S")
print(f"Today: {converted.strftime('%d.%m.%Y, %H:%M')}")

Двоичные объекты

class xmlrpc.client.Binary

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

data

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

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

decode(bytes)

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

encode(out)

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

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

Он также поддерживает некоторые встроенные операторы Python с помощью методов __eq__() и __ne__().

Пример использования двоичных объектов. Передадим изображение по XML-RPC:

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 инкапсулирует содержимое тега fault в XML-RPC. У объектов Fault есть следующие атрибуты:

faultCode

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

faultString

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

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

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

Код клиента для приведённого выше сервера:

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 описывает ошибку протокола на базовом транспортном уровне (например, ошибку 404 «не найдено», если сервер, указанный в URI, не существует). У него есть следующие атрибуты:

url

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

errcode

Код ошибки.

errmsg

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

headers

Словарь с заголовками HTTP/HTTPS-запроса, вызвавшего ошибку.

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

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 позволяет объединить несколько вызовов удалённого сервера в один запрос [1].

class xmlrpc.client.MultiCall(server)

Создаёт объект для объединения вызовов методов. 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

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

Код клиента для приведённого выше сервера:

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

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

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. Значение Python None нельзя использовать в стандартном XML-RPC; чтобы разрешить его использование с помощью расширения, задайте для allow_none значение true.

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; по умолчанию этот флаг имеет значение false.

Устаревший флаг 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)

Чтобы получить доступ к серверу 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))

Пример использования клиента и сервера

См. Пример SimpleXMLRPCServer.

Сноски