SimpleXMLRPCServer — Базовый сервер XML-RPC

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

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

class SimpleXMLRPCServer.SimpleXMLRPCServer(addr[, requestHandler[, logRequests[, allow_none[, encoding[, bind_and_activate]]]])

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

Изменено в версии 2.5: Были добавлены параметры allow_none и encoding.

Изменено в версии 2.6: Был добавлен параметр bind_and_activate.

class SimpleXMLRPCServer.CGIXMLRPCRequestHandler([allow_none[, encoding]])

Создаёт новый экземпляр для обработки XML-RPC запросов в среде CGI. Параметры allow_none и encoding передаются в xmlrpclib и контролируют XML-RPC ответы, которые будут возвращены сервером.

Введено в версии 2.3.

Изменено в версии 2.5: Были добавлены параметры allow_none и encoding.

class SimpleXMLRPCServer.SimpleXMLRPCRequestHandler

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

1. Объекты SimpleXMLRPCServer

Класс 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 позволяет злоумышленникам получить доступ к глобальным переменным вашего модуля и может позволить им выполнить произвольный код на вашем компьютере. Используйте эту опцию только в безопасной закрытой сети.

Изменено в версии 2.3.5,: 2.4.1 allow_dotted_names был добавлен для устранения уязвимости; предыдущие версии небезопасны.

SimpleXMLRPCServer.register_introspection_functions()

Регистрирует функции интроспекции XML-RPC system.listMethods, system.methodHelp и system.methodSignature.

Введено в версии 2.3.

SimpleXMLRPCServer.register_multicall_functions()

Регистрирует систему мультикалла XML-RPC system.multicall.

SimpleXMLRPCRequestHandler.rpc_paths

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

Введено в версии 2.5.

SimpleXMLRPCRequestHandler.encode_threshold

Если этот атрибут не None, ответы, превышающие это значение, будут закодированы с использованием кодировки передачи gzip, если это разрешено клиентом. По умолчанию 1400, что примерно соответствует одному TCP пакету.

Введено в версии 2.7.

1.1. Пример SimpleXMLRPCServer

Код сервера:

from SimpleXMLRPCServer import SimpleXMLRPCServer
from SimpleXMLRPCServer 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 'div').
class MyFuncs:
    def div(self, x, y):
        return x // y

server.register_instance(MyFuncs())

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

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

import xmlrpclib

s = xmlrpclib.ServerProxy('http://localhost:8000')
print s.pow(2,3)  # Returns 2**3 = 8
print s.add(2,3)  # Returns 5
print s.div(5,2)  # Returns 5//2 = 2

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

Следующий пример SimpleXMLRPCServer включён в модуль Lib/SimpleXMLRPCServer.py:

server = SimpleXMLRPCServer(("localhost", 8000))
server.register_function(pow)
server.register_function(lambda x,y: x+y, 'add')
server.register_multicall_functions()
server.serve_forever()

Этот демонстрационный сервер может быть запущен из командной строки как:

python -m SimpleXMLRPCServer

Пример кода клиента, взаимодействующего с сервером, включен в Lib/xmlrpclib.py:

server = ServerProxy("http://localhost:8000")
print server
multi = MultiCall(server)
multi.pow(2, 9)
multi.add(5, 1)
multi.add(24, 11)
try:
    for response in multi():
        print response
except Error, v:
    print "ERROR", v

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

python -m xmlrpclib

2. 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(). Если 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 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()