`xmlrpc.server.md`

270 строк · 22.6 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.5/library/xmlrpc.server.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 21.27. [`xmlrpc.server`](https://python-all.ru/3.5/library/xmlrpc.server.html#module-xmlrpc.server) – Базовые XML-RPC серверы89**Исходный код:** [Lib/xmlrpc/server.py](https://python-all.ru/src/3.5/Lib/xmlrpc/server.py)1011---1213Модуль [`xmlrpc.server`](https://python-all.ru/3.5/library/xmlrpc.server.html#module-xmlrpc.server) предоставляет базовый каркас сервера для XML-RPC серверов, написанных на Python. Серверы могут быть как автономными, с использованием [`SimpleXMLRPCServer`](https://python-all.ru/3.5/library/xmlrpc.server.html#xmlrpc.server.SimpleXMLRPCServer), так и встроенными в CGI-среду, с использованием [`CGIXMLRPCRequestHandler`](https://python-all.ru/3.5/library/xmlrpc.server.html#xmlrpc.server.CGIXMLRPCRequestHandler).1415> **Предупреждение**16>17> Модуль [`xmlrpc.server`](https://python-all.ru/3.5/library/xmlrpc.server.html#module-xmlrpc.server) не защищён от вредоносных данных. Если требуется разбирать непроверенные или неаутентифицированные данные, см. [уязвимости XML](https://python-all.ru/3.5/library/xml.html#xml-vulnerabilities).1819#### `class xmlrpc.server.SimpleXMLRPCServer(addr, requestHandler=SimpleXMLRPCRequestHandler, logRequests=True, allow_none=False, encoding=None, bind_and_activate=True, use_builtin_types=False)`2021Создаёт новый экземпляр сервера. Этот класс предоставляет методы для регистрации функций, которые могут быть вызваны через протокол XML-RPC. Параметр *requestHandler* должен быть фабрикой экземпляров обработчиков запросов; по умолчанию используется [`SimpleXMLRPCRequestHandler`](https://python-all.ru/3.5/library/xmlrpc.server.html#xmlrpc.server.SimpleXMLRPCRequestHandler). Параметры *addr* и *requestHandler* передаются конструктору [`socketserver.TCPServer`](https://python-all.ru/3.5/library/socketserver.html#socketserver.TCPServer). Если *logRequests* равен true (по умолчанию), запросы будут логироваться; установка этого параметра в false отключает логирование. Параметры *allow\_none* и *encoding* передаются в [`xmlrpc.client`](https://python-all.ru/3.5/library/xmlrpc.client.html#module-xmlrpc.client) и управляют XML-RPC ответами, которые будут возвращаться сервером. Параметр *bind\_and\_activate* управляет тем, будут ли `server_bind()` и `server_activate()` вызваны сразу конструктором; по умолчанию true. Установка false позволяет коду изменить переменную класса *allow\_reuse\_address* до привязки адреса. Параметр *use\_builtin\_types* передаётся функции [`loads()`](https://python-all.ru/3.5/library/xmlrpc.client.html#xmlrpc.client.loads) и управляет тем, какие типы обрабатываются при получении значений даты/времени или двоичных данных; по умолчанию false.2223Изменено в версии 3.3: Добавлен флаг *use\_builtin\_types*.2425#### `class xmlrpc.server.CGIXMLRPCRequestHandler(allow_none=False, encoding=None, use_builtin_types=False)`2627Создаёт новый экземпляр для обработки XML-RPC запросов в CGI-среде. Параметры *allow\_none* и *encoding* передаются в [`xmlrpc.client`](https://python-all.ru/3.5/library/xmlrpc.client.html#module-xmlrpc.client) и управляют XML-RPC ответами, возвращаемыми сервером. Параметр *use\_builtin\_types* передаётся функции [`loads()`](https://python-all.ru/3.5/library/xmlrpc.client.html#xmlrpc.client.loads) и управляет тем, какие типы обрабатываются при получении значений даты/времени или двоичных данных; по умолчанию false.2829Изменено в версии 3.3: Добавлен флаг *use\_builtin\_types*.3031#### `class xmlrpc.server.SimpleXMLRPCRequestHandler`3233Создаёт новый экземпляр обработчика запросов. Этот обработчик поддерживает запросы `POST` и изменяет логирование так, чтобы параметр *logRequests* конструктора [`SimpleXMLRPCServer`](https://python-all.ru/3.5/library/xmlrpc.server.html#xmlrpc.server.SimpleXMLRPCServer) учитывался.3435## 21.27.1. Объекты SimpleXMLRPCServer3637Класс [`SimpleXMLRPCServer`](https://python-all.ru/3.5/library/xmlrpc.server.html#xmlrpc.server.SimpleXMLRPCServer) основан на [`socketserver.TCPServer`](https://python-all.ru/3.5/library/socketserver.html#socketserver.TCPServer) и предоставляет средства для создания простых автономных XML-RPC серверов.3839#### `SimpleXMLRPCServer.register_function(function, name=None)`4041Регистрирует функцию, которая может отвечать на запросы XML-RPC. Если указан *name*, он будет именем метода, ассоциированного с *function*, в противном случае будет использовано `function.__name__`. *name* может быть обычной или Unicode-строкой и может содержать символы, недопустимые в идентификаторах Python, включая точку.4243#### `SimpleXMLRPCServer.register_instance(instance, allow_dotted_names=False)`4445Регистрирует объект, который используется для предоставления доступа к именам методов, не зарегистрированных с помощью [`register_function()`](https://python-all.ru/3.5/library/xmlrpc.server.html#xmlrpc.server.SimpleXMLRPCServer.register_function). Если *instance* содержит метод `_dispatch()`, он вызывается с именем запрошенного метода и параметрами из запроса. Его API: `def _dispatch(self, method, params)` (обратите внимание, что *params* не представляет собой список переменных аргументов). Если для выполнения задачи вызывается нижележащая функция, она вызывается как `func(*params)`, с развёртыванием списка параметров. Возвращаемое значение `_dispatch()` возвращается клиенту как результат. Если *instance* не имеет метода `_dispatch()`, в нём ищется атрибут, соответствующий имени запрошенного метода.4647Если необязательный аргумент *allow\_dotted\_names* равен true и экземпляр не имеет метода `_dispatch()`, то если имя запрошенного метода содержит точки, каждый компонент имени метода ищется отдельно, в результате чего выполняется простой иерархический поиск. Найденное значение затем вызывается с параметрами из запроса, а возвращаемое значение передаётся обратно клиенту.4849> **Предупреждение**50>51> Включение опции *allow\_dotted\_names* позволяет злоумышленникам получить доступ к глобальным переменным вашего модуля и может позволить им выполнить произвольный код на вашей машине. Используйте эту опцию только в безопасной закрытой сети.5253#### `SimpleXMLRPCServer.register_introspection_functions()`5455Регистрирует функции интроспекции XML-RPC: `system.listMethods`, `system.methodHelp` и `system.methodSignature`.5657#### `SimpleXMLRPCServer.register_multicall_functions()`5859Регистрирует функцию мультивызова XML-RPC system.multicall.6061#### `SimpleXMLRPCRequestHandler.rpc_paths`6263Значение атрибута, которое должно быть кортежем, перечисляющим допустимые части пути URL для приёма XML-RPC запросов. Запросы, отправленные на другие пути, приведут к HTTP-ошибке 404 «страница не найдена». Если кортеж пуст, все пути считаются допустимыми. Значение по умолчанию – `('/', '/RPC2')`.6465### 21.27.1.1. Пример SimpleXMLRPCServer6667Код сервера:6869```python70from xmlrpc.server import SimpleXMLRPCServer71from xmlrpc.server import SimpleXMLRPCRequestHandler7273# Ограничить конкретным путём.74class RequestHandler(SimpleXMLRPCRequestHandler):75    rpc_paths = ('/RPC2',)7677# Создать сервер78server = SimpleXMLRPCServer(("localhost", 8000),79                            requestHandler=RequestHandler)80server.register_introspection_functions()8182# Зарегистрировать функцию pow(); будет использовано значение83# pow.__name__ как имя, то есть просто 'pow'.84server.register_function(pow)8586# Зарегистрировать функцию под другим именем87def adder_function(x,y):88    return x + y89server.register_function(adder_function, 'add')9091# Зарегистрировать экземпляр; все методы экземпляра92# публикуются как XML-RPC-методы (в данном случае только 'mul').93class MyFuncs:94    def mul(self, x, y):95        return x * y9697server.register_instance(MyFuncs())9899# Запустить главный цикл сервера100server.serve_forever()101```102103Следующий клиентский код будет вызывать методы, предоставленные предыдущим сервером:104105```python106import xmlrpc.client107108s = xmlrpc.client.ServerProxy('http://localhost:8000')109print(s.pow(2,3))  # Возвращает 2**3 = 8110print(s.add(2,3))  # Возвращает 5111print(s.mul(5,2))  # Возвращает 5*2 = 10112113# Вывести список доступных методов114print(s.system.listMethods())115```116117Следующий пример из модуля `Lib/xmlrpc/server.py` показывает сервер, поддерживающий составные имена и регистрирующий функцию multicall.118119> **Предупреждение**120>121> Включение опции *allow\_dotted\_names* позволяет злоумышленникам получить доступ к глобальным переменным вашего модуля и может позволить им выполнить произвольный код на вашей машине. Используйте этот пример только в защищённой закрытой сети.122123```python124import datetime125126class ExampleService:127    def getData(self):128        return '42'129130    class currentTime:131        @staticmethod132        def getCurrentTime():133            return datetime.datetime.now()134135server = SimpleXMLRPCServer(("localhost", 8000))136server.register_function(pow)137server.register_function(lambda x,y: x+y, 'add')138server.register_instance(ExampleService(), allow_dotted_names=True)139server.register_multicall_functions()140print('Serving XML-RPC on localhost port 8000')141try:142    server.serve_forever()143except KeyboardInterrupt:144    print("\nKeyboard interrupt received, exiting.")145    server.server_close()146    sys.exit(0)147```148149Демо-сервис ExampleService можно запустить из командной строки:150151```python152python -m xmlrpc.server153```154155Клиент, который взаимодействует с указанным выше сервером, находится в *Lib/xmlrpc/client.py*:156157```python158server = ServerProxy("http://localhost:8000")159160try:161    print(server.currentTime.getCurrentTime())162except Error as v:163    print("ERROR", v)164165multi = MultiCall(server)166multi.getData()167multi.pow(2,9)168multi.add(1,2)169try:170    for response in multi():171        print(response)172except Error as v:173    print("ERROR", v)174```175176Этот клиент, взаимодействующий с демо-сервером XMLRPC, может быть вызван как:177178```python179python -m xmlrpc.client180```181182## 21.27.2. CGIXMLRPCRequestHandler183184Класс [`CGIXMLRPCRequestHandler`](https://python-all.ru/3.5/library/xmlrpc.server.html#xmlrpc.server.CGIXMLRPCRequestHandler) можно использовать для обработки XML-RPC запросов, отправленных CGI-скриптам Python.185186#### `CGIXMLRPCRequestHandler.register_function(function, name=None)`187188Регистрирует функцию, которая может отвечать на запросы XML-RPC. Если указан *name*, он будет именем метода, ассоциированного с функцией, в противном случае будет использовано *function.\_\_name\_\_*. *name* может быть обычной или Unicode-строкой и может содержать символы, недопустимые в идентификаторах Python, включая точку.189190#### `CGIXMLRPCRequestHandler.register_instance(instance)`191192Регистрирует объект, который используется для предоставления имён методов, не зарегистрированных с помощью [`register_function()`](https://python-all.ru/3.5/library/xmlrpc.server.html#xmlrpc.server.CGIXMLRPCRequestHandler.register_function). Если экземпляр содержит метод `_dispatch()`, он вызывается с запрошенным именем метода и параметрами из запроса; возвращаемое значение передаётся клиенту как результат. Если экземпляр не имеет метода `_dispatch()`, выполняется поиск атрибута, соответствующего имени запрошенного метода; если имя запрошенного метода содержит точки, каждый компонент имени метода ищется отдельно, в результате чего выполняется простая иерархическая проверка. Найденное значение затем вызывается с параметрами из запроса, а возвращаемое значение передаётся обратно клиенту.193194#### `CGIXMLRPCRequestHandler.register_introspection_functions()`195196Регистрирует функции интроспекции XML-RPC `system.listMethods`, `system.methodHelp` и `system.methodSignature`.197198#### `CGIXMLRPCRequestHandler.register_multicall_functions()`199200Регистрирует функцию мультивызова XML-RPC `system.multicall`.201202#### `CGIXMLRPCRequestHandler.handle_request(request_text=None)`203204Обрабатывает XML-RPC запрос. Если задан *request\_text*, он должен содержать POST-данные, предоставленные HTTP-сервером, в противном случае будет использовано содержимое stdin.205206Пример:207208```python209class MyFuncs:210    def mul(self, x, y):211        return x * y212213handler = CGIXMLRPCRequestHandler()214handler.register_function(pow)215handler.register_function(lambda x,y: x+y, 'add')216handler.register_introspection_functions()217handler.register_instance(MyFuncs())218handler.handle_request()219```220221## 21.27.3. Документирование XMLRPC сервера222223Эти классы расширяют указанные выше классы, чтобы предоставлять HTML-документацию в ответ на HTTP GET запросы. Серверы могут быть автономными, с использованием [`DocXMLRPCServer`](https://python-all.ru/3.5/library/xmlrpc.server.html#xmlrpc.server.DocXMLRPCServer), или встроенными в CGI-среду, с использованием [`DocCGIXMLRPCRequestHandler`](https://python-all.ru/3.5/library/xmlrpc.server.html#xmlrpc.server.DocCGIXMLRPCRequestHandler).224225#### `class xmlrpc.server.DocXMLRPCServer(addr, requestHandler=DocXMLRPCRequestHandler, logRequests=True, allow_none=False, encoding=None, bind_and_activate=True, use_builtin_types=True)`226227Создаёт новый экземпляр сервера. Все параметры имеют то же значение, что и для [`SimpleXMLRPCServer`](https://python-all.ru/3.5/library/xmlrpc.server.html#xmlrpc.server.SimpleXMLRPCServer); *requestHandler* по умолчанию равен [`DocXMLRPCRequestHandler`](https://python-all.ru/3.5/library/xmlrpc.server.html#xmlrpc.server.DocXMLRPCRequestHandler).228229Изменено в версии 3.3: Добавлен флаг *use\_builtin\_types*.230231#### `class xmlrpc.server.DocCGIXMLRPCRequestHandler`232233Создаёт новый экземпляр для обработки XML-RPC запросов в CGI-среде.234235#### `class xmlrpc.server.DocXMLRPCRequestHandler`236237Создаёт новый экземпляр обработчика запросов. Этот обработчик запросов поддерживает XML-RPC POST-запросы, GET-запросы документации и изменяет протоколирование так, чтобы параметр *logRequests* конструктора [`DocXMLRPCServer`](https://python-all.ru/3.5/library/xmlrpc.server.html#xmlrpc.server.DocXMLRPCServer) соблюдался.238239## 21.27.4. Объекты DocXMLRPCServer240241Класс [`DocXMLRPCServer`](https://python-all.ru/3.5/library/xmlrpc.server.html#xmlrpc.server.DocXMLRPCServer) является производным от [`SimpleXMLRPCServer`](https://python-all.ru/3.5/library/xmlrpc.server.html#xmlrpc.server.SimpleXMLRPCServer) и предоставляет средство создания самодокументируемых автономных XML-RPC серверов. HTTP POST запросы обрабатываются как вызовы методов XML-RPC. HTTP GET запросы обрабатываются генерацией HTML-документации в стиле pydoc. Это позволяет серверу предоставлять собственную веб-документацию.242243#### `DocXMLRPCServer.set_server_title(server_title)`244245Устанавливает заголовок, используемый в сгенерированной HTML-документации. Этот заголовок будет использоваться внутри элемента HTML «title».246247#### `DocXMLRPCServer.set_server_name(server_name)`248249Устанавливает имя, используемое в сгенерированной HTML-документации. Это имя будет отображаться в верхней части сгенерированной документации внутри элемента «h1».250251#### `DocXMLRPCServer.set_server_documentation(server_documentation)`252253Устанавливает описание, используемое в сгенерированной HTML-документации. Это описание будет отображаться в виде абзаца, под именем сервера, в документации.254255## 21.27.5. DocCGIXMLRPCRequestHandler256257Класс [`DocCGIXMLRPCRequestHandler`](https://python-all.ru/3.5/library/xmlrpc.server.html#xmlrpc.server.DocCGIXMLRPCRequestHandler) является производным от [`CGIXMLRPCRequestHandler`](https://python-all.ru/3.5/library/xmlrpc.server.html#xmlrpc.server.CGIXMLRPCRequestHandler) и предоставляет средство создания самодокументируемых XML-RPC CGI-скриптов. HTTP POST запросы обрабатываются как вызовы методов XML-RPC. HTTP GET запросы обрабатываются генерацией HTML-документации в стиле pydoc. Это позволяет серверу предоставлять собственную веб-документацию.258259#### `DocCGIXMLRPCRequestHandler.set_server_title(server_title)`260261Устанавливает заголовок, используемый в сгенерированной HTML-документации. Этот заголовок будет использоваться внутри элемента HTML «title».262263#### `DocCGIXMLRPCRequestHandler.set_server_name(server_name)`264265Устанавливает имя, используемое в сгенерированной HTML-документации. Это имя будет отображаться в верхней части сгенерированной документации внутри элемента «h1».266267#### `DocCGIXMLRPCRequestHandler.set_server_documentation(server_documentation)`268269Устанавливает описание, используемое в сгенерированной HTML-документации. Это описание будет отображаться в виде абзаца, под именем сервера, в документации.270