xmlrpc.server
— Базовые серверы XML-RPC¶
Модуль 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 — истина (по умолчанию), запросы будут регистрироваться; установка для этого параметра значения ложь отключит журналирование. Параметры allow_none и encoding передаются вxmlrpc.client
и управляют ответами XML-RPC, которые будут возвращены сервером. Параметр bind_and_activate определяет, вызываются лиserver_bind()
иserver_activate()
сразу конструктором; по умолчанию — истина. Установка для него значения ложь позволяет коду манипулировать переменной класса allow_reuse_address до привязки адреса. Параметр use_builtin_types передаётся в функциюloads()
и определяет, какие типы обрабатываются при получении значений даты/времени или двоичных данных; по умолчанию — ложь.Изменено в версии 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()
и определяет, какие типы обрабатываются при получении значений даты/времени или двоичных данных; по умолчанию — ложь.Изменено в версии 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 значение истина и экземпляр не имеет метода
_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
, показан
сервер, разрешающий имена с точками и регистрирующий функцию многократного
вызова.
Предупреждение
Включение опции 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
¶ Создать новый экземпляр обработчика запросов. Данный обработчик запросов поддерживает запросы POST XML-RPC, запросы 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
и предоставляет средства для создания
самодокументированных сценариев 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-документации. Это описание будет отображаться в документации в виде абзаца под именем сервера.