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. Если имя* не указано, будет использоваться
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 multicall system.multicall.
-
SimpleXMLRPCRequestHandler.
rpc_paths
¶ Значение атрибута, которое должно быть кортежем, перечисляющим допустимые части пути URL для приема XML-RPC запросов. Запросы, направленные на другие пути, приведут к HTTP-ошибке 404 «нет такой страницы». Если этот кортеж пуст, все пути будут считаться допустимыми. Значение по умолчанию -
('/', '/RPC2')
.
Пример SimpleXMLRPCServer¶
Код сервера:
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())
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()
# 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()
Следующий пример, включенный в модуль 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 запросов, отправленных CGI-скриптам Python.
-
CGIXMLRPCRequestHandler.
register_function
(function=None, name=None)¶ Зарегистрируйте функцию, которая может отвечать на запросы XML-RPC. Если указано name, то это будет имя метода, связанное с function, в противном случае будет использоваться
function.__name__
. name является строкой и может содержать символы, не разрешенные в идентификаторах Python, включая символ точки.Этот метод также можно использовать в качестве декоратора. При использовании в качестве декоратора, name может быть задано только в качестве аргумента ключевого слова для регистрации function под 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
и предоставляет средства для создания самодокументирующихся 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. Это описание будет отображаться в документации в виде абзаца под именем сервера.