xmlrpc.server — Базовые XML-RPC-серверы

Объекты SimpleXMLRPCServer

Класс 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').

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

# Restrict to a particular path.
class RequestHandler(SimpleXMLRPCRequestHandler):
    rpc_paths = ('/RPC2',)

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

    # Register pow() function; this will use the value of
    # pow.__name__ as the name, which is just 'pow'.
    server.register_function(pow)

    # Register a function under a different name
    def adder_function(x, y):
        return x + y
    server.register_function(adder_function, 'add')

    # Register an instance; all the methods of the instance are
    # published as XML-RPC methods (in this case, just 'mul').
    class MyFuncs:
        def mul(self, x, y):
            return x * y

    server.register_instance(MyFuncs())

    # Run the server's main loop
    server.serve_forever()

import xmlrpc.client

s = xmlrpc.client.ServerProxy('http://localhost:8000')
print(s.pow(2,3))  # Returns 2**3 = 8
print(s.add(2,3))  # Returns 5
print(s.mul(5,2))  # Returns 5*2 = 10

# Print list of available methods
print(s.system.listMethods())

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

    # Register pow() function; this will use the value of
    # pow.__name__ as the name, which is just 'pow'.
    server.register_function(pow)

    # Register a function under a different name, using
    # register_function as a decorator. *name* can only be given
    # as a keyword argument.
    @server.register_function(name='add')
    def adder_function(x, y):
        return x + y

    # Register a function under function.__name__.
    @server.register_function
    def mul(x, y):
        return x * y

    server.serve_forever()

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)

python -m xmlrpc.server

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)

python -m xmlrpc.client

CGIXMLRPCRequestHandler

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

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

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

Эти классы расширяют описанные выше классы и предоставляют 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.

Объекты DocXMLRPCServer

Класс 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 и позволяет создавать CGI-скрипты XML-RPC с собственной документацией. 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-документации. В документации это описание будет отображаться в виде абзаца под именем сервера.