Содержание страницы

`xmlrpc.server` – Базовые XML-RPC серверы¶xmlrpc.server – Basic XML-RPC servers

Модуль xmlrpc.server предоставляет базовую серверную структуру для XML-RPC серверов, написанных на Python. Серверы могут быть как автономными (с использованием SimpleXMLRPCServer), так и встроенными в CGI-среду (с помощью CGIXMLRPCRequestHandler).

class xmlrpc.server.SimpleXMLRPCServer(addr[, requestHandler[, logRequests[, allow_none[, encoding[, bind_and_activate]]]]])¶: Создаёт новый экземпляр сервера. Этот класс предоставляет методы для регистрации функций, которые могут быть вызваны по протоколу XML-RPC. Параметр requestHandler должен быть фабрикой для экземпляров обработчика запросов; по умолчанию используется SimpleXMLRPCRequestHandler. Параметры addr и requestHandler передаются конструктору socketserver.TCPServer. Если logRequests равен true (по умолчанию), запросы будут логироваться; установка этого параметра в false отключит логирование. Параметры allow_none и encoding передаются xmlrpc.client и управляют XML-RPC ответами, которые будут возвращены сервером. Параметр bind_and_activate определяет, будут ли server_bind() и server_activate() вызваны сразу в конструкторе; по умолчанию true. Если установить false, это позволит коду изменить переменную класса allow_reuse_address до привязки адреса.

class xmlrpc.server.CGIXMLRPCRequestHandler([allow_none[, encoding]])¶: Создаёт новый экземпляр для обработки XML-RPC запросов в CGI-среде. Параметры allow_none и encoding передаются xmlrpc.client и управляют XML-RPC ответами, которые будут возвращены сервером.

class xmlrpc.server.SimpleXMLRPCRequestHandler¶: Создаёт новый экземпляр обработчика запросов. Этот обработчик поддерживает POST запросы и изменяет регистрацию (логирование) так, чтобы учитывался параметр logRequests конструктора SimpleXMLRPCServer.

Объекты SimpleXMLRPCServer¶SimpleXMLRPCServer Objects

Класс SimpleXMLRPCServer основан на socketserver.TCPServer и предоставляет способ создания простых автономных XML-RPC серверов.

SimpleXMLRPCServer.register_function(function[, name])¶: Регистрирует функцию, которая может отвечать на XML-RPC запросы. Если задан name, то это будет имя метода, связанное с function; в противном случае будет использоваться function.__name__. name может быть как обычной, так и Unicode строкой, и может содержать символы, недопустимые в Python-идентификаторах, включая точку.

SimpleXMLRPCServer.register_instance(instance[, allow_dotted_names])¶

Регистрирует объект, который используется для раскрытия имён методов, не зарегистрированных с помощью register_function(). Если instance содержит метод _dispatch(), то он вызывается с именем запрошенного метода и параметрами из запроса. Его API: def _dispatch(self, method, params) (обратите внимание, что params не представляет собой список переменных аргументов). Если он вызывает некоторую базовую функцию для выполнения задачи, эта функция вызывается как func(*params), с разворачиванием списка параметров. Возвращаемое значение из _dispatch() возвращается клиенту в качестве результата. Если instance не имеет метода _dispatch(), то в нём ищется атрибут, соответствующий имени запрошенного метода.

Если необязательный аргумент allow_dotted_names равен true и экземпляр не имеет метода _dispatch(), то в случае, если имя запрошенного метода содержит точки, каждый компонент имени метода ищется отдельно, что приводит к выполнению простого иерархического поиска. Найденное значение затем вызывается с параметрами из запроса, а возвращаемое значение передаётся обратно клиенту.

Предупреждение

Включение опции allow_dotted_names позволяет злоумышленникам получить доступ к глобальным переменным вашего модуля и может позволить им выполнить произвольный код на вашей машине. Используйте эту опцию только в безопасной закрытой сети.

SimpleXMLRPCServer.register_introspection_functions()¶: Регистрирует функции интроспекции XML-RPC: system.listMethods, system.methodHelp и system.methodSignature.

SimpleXMLRPCServer.register_multicall_functions()¶: Регистрирует функцию мультивызова XML-RPC system.multicall.

SimpleXMLRPCRequestHandler.rpc_paths¶: Значение атрибута, которое должно быть кортежем, перечисляющим допустимые части пути URL для приёма XML-RPC запросов. Запросы, отправленные на другие пути, приведут к HTTP-ошибке 404 «страница не найдена». Если этот кортеж пуст, все пути считаются допустимыми. Значение по умолчанию – ('/', '/RPC2').

Пример SimpleXMLRPCServer¶SimpleXMLRPCServer Example

Код сервера:

from xmlrpc.server import SimpleXMLRPCServer
from xmlrpc.server import SimpleXMLRPCRequestHandler

# Ограничить конкретным путём.
class RequestHandler(SimpleXMLRPCRequestHandler):
    rpc_paths = ('/RPC2',)

# Создать сервер
server = SimpleXMLRPCServer(("localhost", 8000),
                            requestHandler=RequestHandler)
server.register_introspection_functions()

# Зарегистрировать функцию pow(); будет использовано значение
# pow.__name__ как имя, то есть просто 'pow'.
server.register_function(pow)

# Зарегистрировать функцию под другим именем
def adder_function(x,y):
    return x + y
server.register_function(adder_function, 'add')

# Зарегистрировать экземпляр; все методы экземпляра
# опубликованы как методы XML-RPC (в данном случае просто 'div').
class MyFuncs:
    def div(self, x, y):
        return x // y

server.register_instance(MyFuncs())

# Запустить главный цикл сервера
server.serve_forever()

Следующий клиентский код будет вызывать методы, предоставленные предыдущим сервером:

import xmlrpc.client

s = xmlrpc.client.ServerProxy('http://localhost:8000')
print(s.pow(2,3))  # Возвращает 2**3 = 8
print(s.add(2,3))  # Возвращает 5
print(s.mul(5,2))  # Возвращает 5*2 = 10

# Вывести список доступных методов
print(s.system.listMethods())

CGIXMLRPCRequestHandler¶

Класс CGIXMLRPCRequestHandler может использоваться для обработки XML-RPC запросов, отправленных в CGI-сценарии Python.

CGIXMLRPCRequestHandler.register_function(function[, name])¶: Регистрирует функцию, которая может отвечать на запросы XML-RPC. Если указан name, он будет именем метода, ассоциированного с функцией, в противном случае будет использовано function.__name__. name может быть обычной или Unicode-строкой и может содержать символы, недопустимые в идентификаторах Python, включая точку.

CGIXMLRPCRequestHandler.register_instance(instance)¶: Регистрирует объект, который используется для раскрытия имён методов, не зарегистрированных с помощью register_function(). Если экземпляр содержит метод _dispatch(), он вызывается с именем запрошенного метода и параметрами из запроса; возвращаемое значение возвращается клиенту в качестве результата. Если экземпляр не имеет метода _dispatch(), то в нём ищется атрибут, соответствующий имени запрошенного метода; если имя запрошенного метода содержит точки, каждый компонент имени метода ищется отдельно, что приводит к выполнению простого иерархического поиска. Найденное значение затем вызывается с параметрами из запроса, а возвращаемое значение передаётся обратно клиенту.

CGIXMLRPCRequestHandler.register_introspection_functions()¶: Регистрирует функции интроспекции XML-RPC: system.listMethods, system.methodHelp и system.methodSignature.

CGIXMLRPCRequestHandler.register_multicall_functions()¶: Регистрирует функцию мультивызова XML-RPC system.multicall.

CGIXMLRPCRequestHandler.handle_request([request_text = None])¶: Обрабатывает XML-RPC-запрос. Если передан request_text, это должны быть POST-\nданные, предоставленные HTTP-сервером; в противном случае используется содержимое stdin.

Пример:

class MyFuncs:
    def div(self, x, y) : return x // y


handler = CGIXMLRPCRequestHandler()
handler.register_function(pow)
handler.register_function(lambda x,y: x+y, 'add')
handler.register_introspection_functions()
handler.register_instance(MyFuncs())
handler.handle_request()

Документирование сервера XMLRPC¶Documenting XMLRPC server

Эти классы расширяют приведённые выше классы для обслуживания HTML-документации в ответ\nна HTTP GET-запросы. Серверы могут быть либо автономными, использующими\nDocXMLRPCServer, либо встроенными в CGI-среду, использующими\nDocCGIXMLRPCRequestHandler.

class xmlrpc.server.DocXMLRPCServer(addr[, requestHandler[, logRequests[, allow_none[, encoding[, bind_and_activate]]]]])¶: Создаёт новый экземпляр сервера. Все параметры имеют то же значение, что и для\nSimpleXMLRPCServer; requestHandler по умолчанию равен\nDocXMLRPCRequestHandler.

class xmlrpc.server.DocCGIXMLRPCRequestHandler¶: Создаёт новый экземпляр для обработки XML-RPC запросов в CGI-среде.

class xmlrpc.server.DocXMLRPCRequestHandler¶: Создаёт новый экземпляр обработчика запросов. Этот обработчик поддерживает POST-запросы XML-RPC, GET-запросы документации и настраивает протоколирование так, чтобы значение параметра logRequests конструктора DocXMLRPCServer учитывалось.

Объекты DocXMLRPCServer¶DocXMLRPCServer Objects

Класс DocXMLRPCServer является производным от SimpleXMLRPCServer\nи предоставляет способ создания самодокументированных автономных XML-RPC-серверов. HTTP POST-запросы обрабатываются как вызовы методов XML-RPC. HTTP GET-запросы обрабатываются путём генерации HTML-документации в стиле pydoc. Это позволяет серверу предоставлять собственную веб-документацию.

DocXMLRPCServer.set_server_title(server_title)¶: Устанавливает заголовок, используемый в сгенерированной HTML-документации. Этот заголовок будет использоваться внутри элемента HTML «title».

DocXMLRPCServer.set_server_name(server_name)¶: Устанавливает имя, используемое в сгенерированной HTML-документации. Это имя будет отображаться в верхней части сгенерированной документации внутри элемента «h1».

DocXMLRPCServer.set_server_documentation(server_documentation)¶: Устанавливает описание, используемое в сгенерированной HTML-документации. Это описание будет отображаться в виде абзаца, под именем сервера, в документации.

DocCGIXMLRPCRequestHandler¶

Класс DocCGIXMLRPCRequestHandler является производным от\nCGIXMLRPCRequestHandler и предоставляет способ создания\nсамодокументированных XML-RPC CGI-скриптов. HTTP POST-запросы обрабатываются как вызовы методов XML-RPC. HTTP GET-запросы обрабатываются путём генерации HTML-документации в стиле pydoc. Это позволяет серверу предоставлять собственную веб-документацию.

DocCGIXMLRPCRequestHandler.set_server_title(server_title)¶: Устанавливает заголовок, используемый в сгенерированной HTML-документации. Этот заголовок будет использоваться внутри элемента HTML «title».

DocCGIXMLRPCRequestHandler.set_server_name(server_name)¶: Устанавливает имя, используемое в сгенерированной HTML-документации. Это имя будет отображаться в верхней части сгенерированной документации внутри элемента «h1».

DocCGIXMLRPCRequestHandler.set_server_documentation(server_documentation)¶: Устанавливает описание, используемое в сгенерированной HTML-документации. Это описание будет отображаться в виде абзаца, под именем сервера, в документации.