Документация Python неофициальный перевод
Содержание страницы

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

Исходный код: Lib/xmlrpc/server.py

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

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

Модуль xmlrpc.server не защищён от вредоносных данных. Если требуется разбирать непроверенные или неаутентифицированные данные, обратитесь к разделу Безопасность XML.

Доступность: не WASI.

Этот модуль не работает или недоступен на WebAssembly. Подробнее см. платформы WebAssembly.

class xmlrpc.server.SimpleXMLRPCServer(addr, requestHandler=SimpleXMLRPCRequestHandler, logRequests=True, allow_none=False, encoding=None, bind_and_activate=True, use_builtin_types=False)

Создаёт новый экземпляр сервера. Этот класс предоставляет методы для регистрации функций, которые могут быть вызваны через протокол 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 до привязки адреса. Параметр use_builtin_types передаётся функции loads() и управляет тем, какие типы обрабатываются при получении значений даты/времени или двоичных данных; по умолчанию false.

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

class xmlrpc.server.CGIXMLRPCRequestHandler(allow_none=False, encoding=None, use_builtin_types=False)

Создаёт новый экземпляр для обработки XML-RPC запросов в CGI-среде. Параметры allow_none и encoding передаются в xmlrpc.client и управляют XML-RPC ответами, возвращаемыми сервером. Параметр use_builtin_types передаётся функции loads() и управляет тем, какие типы обрабатываются при получении значений даты/времени или двоичных данных; по умолчанию false.

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

class xmlrpc.server.SimpleXMLRPCRequestHandler

Создаёт новый экземпляр обработчика запросов. Этот обработчик поддерживает запросы POST и изменяет логирование так, чтобы параметр logRequests конструктора SimpleXMLRPCServer учитывался.

Объекты SimpleXMLRPCServerSimpleXMLRPCServer objects

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

SimpleXMLRPCServer.register_function(function=None, name=None)

Регистрирует функцию, которая может отвечать на XML-RPC запросы. Если задан name, он будет именем метода, связанного с function; в противном случае используется function.__name__. name – строка, которая может содержать символы, недопустимые в идентификаторах Python, включая точку.

Этот метод также можно использовать как декоратор. При использовании в качестве декоратора name может быть указан только как именованный аргумент для регистрации function под именем name. Если name не задан, используется function.__name__.

Изменено в версии 3.7: register_function() можно использовать как декоратор.

SimpleXMLRPCServer.register_instance(instance, allow_dotted_names=False)

Регистрирует объект, который используется для предоставления доступа к именам методов, не зарегистрированных с помощью 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').

Пример SimpleXMLRPCServerSimpleXMLRPCServer example

Код сервера:

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

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

# Создать сервер
with SimpleXMLRPCServer(('localhost', 8000),
                        requestHandler=RequestHandler) as server:
    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-методы (в данном случае только 'mul').
    class MyFuncs:
        def mul(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())

register_function() также можно использовать как декоратор. Предыдущий пример сервера может регистрировать функции с помощью декоратора:

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

class RequestHandler(SimpleXMLRPCRequestHandler):
    rpc_paths = ('/RPC2',)

with SimpleXMLRPCServer(('localhost', 8000),
                        requestHandler=RequestHandler) as server:
    server.register_introspection_functions()

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

    # Зарегистрировать функцию под другим именем, используя
    # register_function как декоратор. *name* можно указать только
    # как именованный аргумент.
    @server.register_function(name='add')
    def adder_function(x, y):
        return x + y

    # Регистрирует функцию под именем function.__name__.
    @server.register_function
    def mul(x, y):
        return x * y

    server.serve_forever()

Следующий пример из модуля Lib/xmlrpc/server.py показывает сервер, поддерживающий составные имена и регистрирующий функцию multicall.

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

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

import datetime as dt

class ExampleService:
    def getData(self):
        return '42'

    class currentTime:
        @staticmethod
        def getCurrentTime():
            return dt.datetime.now()

with SimpleXMLRPCServer(("localhost", 8000)) as server:
    server.register_function(pow)
    server.register_function(lambda x,y: x+y, 'add')
    server.register_instance(ExampleService(), allow_dotted_names=True)
    server.register_multicall_functions()
    print('Serving XML-RPC on localhost port 8000')
    try:
        server.serve_forever()
    except KeyboardInterrupt:
        print("\nKeyboard interrupt received, exiting.")
        sys.exit(0)

Демо-сервис ExampleService можно запустить из командной строки:

python -m xmlrpc.server

Клиент, взаимодействующий с указанным выше сервером, находится в Lib/xmlrpc/client.py:

server = ServerProxy("http://localhost:8000")

try:
    print(server.currentTime.getCurrentTime())
except Error as v:
    print("ERROR", v)

multi = MultiCall(server)
multi.getData()
multi.pow(2,9)
multi.add(1,2)
try:
    for response in multi():
        print(response)
except Error as v:
    print("ERROR", v)

Этот клиент, взаимодействующий с демо-сервером XMLRPC, может быть вызван как:

python -m xmlrpc.client

CGIXMLRPCRequestHandler

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

CGIXMLRPCRequestHandler.register_function(function=None, name=None)

Регистрирует функцию, которая может отвечать на XML-RPC запросы. Если задано name, оно будет именем метода, связанным с function, в противном случае будет использовано function.__name__. name – строка, и может содержать символы, недопустимые в идентификаторах Python, включая точку.

Этот метод также можно использовать как декоратор. При использовании в качестве декоратора name может быть передан только как именованный аргумент для регистрации function под именем name. Если name не указано, будет использовано function.__name__.

Изменено в версии 3.7: register_function() можно использовать как декоратор.

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-данные, предоставленные HTTP-сервером, в противном случае будет использовано содержимое stdin.

Пример:

class MyFuncs:
    def mul(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()

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

Эти классы расширяют указанные выше классы, чтобы предоставлять HTML-документацию в ответ на HTTP GET запросы. Серверы могут быть автономными, с использованием DocXMLRPCServer, или встроенными в CGI-среду, с использованием DocCGIXMLRPCRequestHandler.

class xmlrpc.server.DocXMLRPCServer(addr, requestHandler=DocXMLRPCRequestHandler, logRequests=True, allow_none=False, encoding=None, bind_and_activate=True, use_builtin_types=True)

Создаёт новый экземпляр сервера. Все параметры имеют то же значение, что и для SimpleXMLRPCServer; requestHandler по умолчанию равен DocXMLRPCRequestHandler.

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

class xmlrpc.server.DocCGIXMLRPCRequestHandler

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

class xmlrpc.server.DocXMLRPCRequestHandler

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

Объекты DocXMLRPCServerDocXMLRPCServer objects

Класс DocXMLRPCServer является производным от SimpleXMLRPCServer и предоставляет средство создания самодокументируемых автономных 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 является производным от CGIXMLRPCRequestHandler и предоставляет средство создания самодокументируемых 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-документации. Это описание будет отображаться в виде абзаца, под именем сервера, в документации.