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

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

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

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 учитывается.

1. Объекты SimpleXMLRPCServer

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

SimpleXMLRPCServer.register_function(function, name=None)

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

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 и объект instance не имеет метода _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').

1.1. Пример SimpleXMLRPCServer

Код сервера:

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

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

# Create server
server = SimpleXMLRPCServer(("localhost", 8000),
                            requestHandler=RequestHandler)
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())

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

import datetime

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

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

server = SimpleXMLRPCServer(("localhost", 8000))
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.")
    server.server_close()
    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

2. CGIXMLRPCRequestHandler

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

CGIXMLRPCRequestHandler.register_function(function, name=None)

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

CGIXMLRPCRequestHandler.register_instance(instance)

Регистрирует объект, используемый для экспонирования имён методов, не зарегистрированных с помощью register_function(). Если объект instance содержит метод _dispatch(), он вызывается с именем запрошенного метода и параметрами из запроса; возвращаемое значение возвращается клиенту в качестве результата. Если объект instance не имеет метода _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()

3. Документирование 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 соблюдался.

4. Объекты 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-документации. Это описание будет отображаться как абзац, ниже имени сервера, в документации.

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