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. Он возвращает массив возможных подписей для этого метода. Подпись — это массив типов. Первый из этих типов — тип возвращаемого значения метода, остальные — параметры.

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

Сами подписи ограничены параметрами верхнего уровня, ожидаемыми методом. Например, если метод ожидает один массив структур в качестве параметра и возвращает строку, его подпись просто “строка, массив”. Если он ожидает три целых числа и возвращает строку, его подпись — “строка, целое число, целое число, целое число”.

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

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

Бинарные объекты

class xmlrpc.client.Binary

Этот класс можно инициализировать из данных типа bytes (которые могут включать нули). Основной доступ к содержимому объекта 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)

Объекты ошибок

class xmlrpc.client.Fault

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

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)

Объекты ошибок протокола

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.

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 был добавлен.

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

# 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.

Примечания