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

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

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

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

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

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 сохраняется.

Объекты 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').

Пример SimpleXMLRPCServer

Код сервера:

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

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

    class currentTime:
        @staticmethod
        def getCurrentTime():
            return datetime.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()

Документирование сервера 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-документации. Это описание появится в документации в виде абзаца под именем сервера.