`xmlrpc.server.md`

313 строк · 25.3 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.13/library/xmlrpc.server.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `xmlrpc.server` – базовые XML-RPC серверы89**Исходный код:** [Lib/xmlrpc/server.py](https://python-all.ru/src/3.13/Lib/xmlrpc/server.py)1011---1213Модуль `xmlrpc.server` предоставляет базовый каркас сервера для XML-RPC серверов, написанных на Python. Серверы могут быть как автономными, с использованием [`SimpleXMLRPCServer`](https://python-all.ru/3.13/library/xmlrpc.server.html#xmlrpc.server.SimpleXMLRPCServer), так и встроенными в CGI-среду, с использованием [`CGIXMLRPCRequestHandler`](https://python-all.ru/3.13/library/xmlrpc.server.html#xmlrpc.server.CGIXMLRPCRequestHandler).1415> **Предупреждение**16>17> Модуль `xmlrpc.server` не защищён от вредоносных данных. Если требуется разбирать непроверенные или неаутентифицированные данные, обратитесь к разделу [Безопасность XML](https://python-all.ru/3.13/library/xml.html#xml-security).1819[Доступность](https://python-all.ru/3.13/library/intro.html#availability): не WASI.2021Этот модуль не работает или недоступен на WebAssembly. Подробнее см. [платформы WebAssembly](https://python-all.ru/3.13/library/intro.html#wasm-availability).2223#### `class xmlrpc.server.SimpleXMLRPCServer(addr, requestHandler=SimpleXMLRPCRequestHandler, logRequests=True, allow_none=False, encoding=None, bind_and_activate=True, use_builtin_types=False)`2425Создаёт новый экземпляр сервера. Этот класс предоставляет методы для регистрации функций, которые могут быть вызваны через протокол XML-RPC. Параметр *requestHandler* должен быть фабрикой экземпляров обработчиков запросов; по умолчанию используется [`SimpleXMLRPCRequestHandler`](https://python-all.ru/3.13/library/xmlrpc.server.html#xmlrpc.server.SimpleXMLRPCRequestHandler). Параметры *addr* и *requestHandler* передаются конструктору [`socketserver.TCPServer`](https://python-all.ru/3.13/library/socketserver.html#socketserver.TCPServer). Если *logRequests* равен true (по умолчанию), запросы будут логироваться; установка этого параметра в false отключает логирование. Параметры *allow\_none* и *encoding* передаются в [`xmlrpc.client`](https://python-all.ru/3.13/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.13/library/xmlrpc.client.html#xmlrpc.client.loads) и управляет тем, какие типы обрабатываются при получении значений даты/времени или двоичных данных; по умолчанию false.2627Изменено в версии 3.3: Добавлен флаг *use\_builtin\_types*.2829#### `class xmlrpc.server.CGIXMLRPCRequestHandler(allow_none=False, encoding=None, use_builtin_types=False)`3031Создаёт новый экземпляр для обработки XML-RPC запросов в CGI-среде. Параметры *allow\_none* и *encoding* передаются в [`xmlrpc.client`](https://python-all.ru/3.13/library/xmlrpc.client.html#module-xmlrpc.client) и управляют XML-RPC ответами, возвращаемыми сервером. Параметр *use\_builtin\_types* передаётся функции [`loads()`](https://python-all.ru/3.13/library/xmlrpc.client.html#xmlrpc.client.loads) и управляет тем, какие типы обрабатываются при получении значений даты/времени или двоичных данных; по умолчанию false.3233Изменено в версии 3.3: Добавлен флаг *use\_builtin\_types*.3435#### `class xmlrpc.server.SimpleXMLRPCRequestHandler`3637Создаёт новый экземпляр обработчика запросов. Этот обработчик поддерживает запросы `POST` и изменяет логирование так, чтобы параметр *logRequests* конструктора [`SimpleXMLRPCServer`](https://python-all.ru/3.13/library/xmlrpc.server.html#xmlrpc.server.SimpleXMLRPCServer) учитывался.3839## Объекты SimpleXMLRPCServer4041Класс [`SimpleXMLRPCServer`](https://python-all.ru/3.13/library/xmlrpc.server.html#xmlrpc.server.SimpleXMLRPCServer) основан на [`socketserver.TCPServer`](https://python-all.ru/3.13/library/socketserver.html#socketserver.TCPServer) и предоставляет средства для создания простых автономных XML-RPC серверов.4243#### `SimpleXMLRPCServer.register_function(function=None, name=None)`4445Регистрирует функцию, которая может отвечать на XML-RPC запросы. Если задано *name*, оно будет именем метода, связанным с *function*, в противном случае будет использовано [`function.__name__`](https://python-all.ru/3.13/reference/datamodel.html#function.__name__). *name* – строка, и может содержать символы, недопустимые в идентификаторах Python, включая точку.4647Этот метод также можно использовать как декоратор. При использовании в качестве декоратора *name* может быть передан только как именованный аргумент для регистрации *function* под именем *name*. Если *name* не указано, будет использовано [`function.__name__`](https://python-all.ru/3.13/reference/datamodel.html#function.__name__).4849Изменено в версии 3.7: `register_function()` можно использовать как декоратор.5051#### `SimpleXMLRPCServer.register_instance(instance, allow_dotted_names=False)`5253Регистрирует объект, который используется для предоставления доступа к именам методов, не зарегистрированных с помощью [`register_function()`](https://python-all.ru/3.13/library/xmlrpc.server.html#xmlrpc.server.SimpleXMLRPCServer.register_function). Если *instance* содержит метод `_dispatch()`, он вызывается с именем запрошенного метода и параметрами из запроса. Его API: `def _dispatch(self, method, params)` (обратите внимание, что *params* не представляет собой список переменных аргументов). Если для выполнения задачи вызывается нижележащая функция, она вызывается как `func(*params)`, с развёртыванием списка параметров. Возвращаемое значение `_dispatch()` возвращается клиенту как результат. Если *instance* не имеет метода `_dispatch()`, в нём ищется атрибут, соответствующий имени запрошенного метода.5455Если необязательный аргумент *allow\_dotted\_names* равен true и экземпляр не имеет метода `_dispatch()`, то если имя запрошенного метода содержит точки, каждый компонент имени метода ищется отдельно, в результате чего выполняется простой иерархический поиск. Найденное значение затем вызывается с параметрами из запроса, а возвращаемое значение передаётся обратно клиенту.5657> **Предупреждение**58>59> Включение опции *allow\_dotted\_names* позволяет злоумышленникам получить доступ к глобальным переменным вашего модуля и может позволить им выполнить произвольный код на вашей машине. Используйте эту опцию только в безопасной закрытой сети.6061#### `SimpleXMLRPCServer.register_introspection_functions()`6263Регистрирует функции интроспекции XML-RPC: `system.listMethods`, `system.methodHelp` и `system.methodSignature`.6465#### `SimpleXMLRPCServer.register_multicall_functions()`6667Регистрирует функцию мультивызова XML-RPC system.multicall.6869#### `SimpleXMLRPCRequestHandler.rpc_paths`7071Значение атрибута, которое должно быть кортежем, перечисляющим допустимые части пути URL для приёма XML-RPC запросов. Запросы, отправленные на другие пути, приведут к HTTP-ошибке 404 «страница не найдена». Если кортеж пуст, все пути считаются допустимыми. Значение по умолчанию – `('/', '/RPC2')`.7273### Пример SimpleXMLRPCServer7475Код сервера:7677```python78from xmlrpc.server import SimpleXMLRPCServer79from xmlrpc.server import SimpleXMLRPCRequestHandler8081# Ограничить конкретным путём.82class RequestHandler(SimpleXMLRPCRequestHandler):83    rpc_paths = ('/RPC2',)8485# Создать сервер86with SimpleXMLRPCServer(('localhost', 8000),87                        requestHandler=RequestHandler) as server:88    server.register_introspection_functions()8990    # Зарегистрировать функцию pow(); будет использовано значение91    # pow.__name__ как имя, то есть просто 'pow'.92    server.register_function(pow)9394    # Зарегистрировать функцию под другим именем95    def adder_function(x, y):96        return x + y97    server.register_function(adder_function, 'add')9899    # Зарегистрировать экземпляр; все методы экземпляра100    # публикуются как XML-RPC-методы (в данном случае только 'mul').101    class MyFuncs:102        def mul(self, x, y):103            return x * y104105    server.register_instance(MyFuncs())106107    # Запустить главный цикл сервера108    server.serve_forever()109```110111Следующий клиентский код будет вызывать методы, предоставленные предыдущим сервером:112113```python114import xmlrpc.client115116s = xmlrpc.client.ServerProxy('http://localhost:8000')117print(s.pow(2,3))  # Возвращает 2**3 = 8118print(s.add(2,3))  # Возвращает 5119print(s.mul(5,2))  # Возвращает 5*2 = 10120121# Вывести список доступных методов122print(s.system.listMethods())123```124125`register_function()` также можно использовать как декоратор. Предыдущий пример сервера может регистрировать функции с помощью декоратора:126127```python128from xmlrpc.server import SimpleXMLRPCServer129from xmlrpc.server import SimpleXMLRPCRequestHandler130131class RequestHandler(SimpleXMLRPCRequestHandler):132    rpc_paths = ('/RPC2',)133134with SimpleXMLRPCServer(('localhost', 8000),135                        requestHandler=RequestHandler) as server:136    server.register_introspection_functions()137138    # Зарегистрировать функцию pow(); будет использовано значение139    # pow.__name__ как имя, то есть просто 'pow'.140    server.register_function(pow)141142    # Зарегистрировать функцию под другим именем, используя143    # register_function как декоратор. *name* можно указать только144    # как именованный аргумент.145    @server.register_function(name='add')146    def adder_function(x, y):147        return x + y148149    # Регистрирует функцию под именем function.__name__.150    @server.register_function151    def mul(x, y):152        return x * y153154    server.serve_forever()155```156157Следующий пример из модуля `Lib/xmlrpc/server.py` показывает сервер, поддерживающий составные имена и регистрирующий функцию multicall.158159> **Предупреждение**160>161> Включение параметра *allow\_dotted\_names* позволяет злоумышленникам получить доступ к глобальным переменным вашего модуля и может позволить им выполнить произвольный код на вашей машине. Используйте этот пример только в безопасной закрытой сети.162163```python164import datetime as dt165166class ExampleService:167    def getData(self):168        return '42'169170    class currentTime:171        @staticmethod172        def getCurrentTime():173            return dt.datetime.now()174175with SimpleXMLRPCServer(("localhost", 8000)) as server:176    server.register_function(pow)177    server.register_function(lambda x,y: x+y, 'add')178    server.register_instance(ExampleService(), allow_dotted_names=True)179    server.register_multicall_functions()180    print('Serving XML-RPC on localhost port 8000')181    try:182        server.serve_forever()183    except KeyboardInterrupt:184        print("\nKeyboard interrupt received, exiting.")185        sys.exit(0)186```187188Демо-сервис ExampleService можно запустить из командной строки:189190```python191python -m xmlrpc.server192```193194Клиент, взаимодействующий с указанным выше сервером, находится в `Lib/xmlrpc/client.py`:195196```python197server = ServerProxy("http://localhost:8000")198199try:200    print(server.currentTime.getCurrentTime())201except Error as v:202    print("ERROR", v)203204multi = MultiCall(server)205multi.getData()206multi.pow(2,9)207multi.add(1,2)208try:209    for response in multi():210        print(response)211except Error as v:212    print("ERROR", v)213```214215Этот клиент, взаимодействующий с демо-сервером XMLRPC, может быть вызван как:216217```python218python -m xmlrpc.client219```220221## CGIXMLRPCRequestHandler222223Класс [`CGIXMLRPCRequestHandler`](https://python-all.ru/3.13/library/xmlrpc.server.html#xmlrpc.server.CGIXMLRPCRequestHandler) можно использовать для обработки XML-RPC-запросов, отправленных в скрипты Python CGI.224225#### `CGIXMLRPCRequestHandler.register_function(function=None, name=None)`226227Регистрирует функцию, которая может отвечать на XML-RPC запросы. Если задано *name*, оно будет именем метода, связанным с *function*, в противном случае будет использовано [`function.__name__`](https://python-all.ru/3.13/reference/datamodel.html#function.__name__). *name* – строка, и может содержать символы, недопустимые в идентификаторах Python, включая точку.228229Этот метод также можно использовать как декоратор. При использовании в качестве декоратора *name* может быть передан только как именованный аргумент для регистрации *function* под именем *name*. Если *name* не указано, будет использовано [`function.__name__`](https://python-all.ru/3.13/reference/datamodel.html#function.__name__).230231Изменено в версии 3.7: `register_function()` можно использовать как декоратор.232233#### `CGIXMLRPCRequestHandler.register_instance(instance)`234235Регистрирует объект, который используется для предоставления имён методов, не зарегистрированных с помощью [`register_function()`](https://python-all.ru/3.13/library/xmlrpc.server.html#xmlrpc.server.CGIXMLRPCRequestHandler.register_function). Если экземпляр содержит метод `_dispatch()`, он вызывается с запрошенным именем метода и параметрами из запроса; возвращаемое значение передаётся клиенту как результат. Если экземпляр не имеет метода `_dispatch()`, выполняется поиск атрибута, соответствующего имени запрошенного метода; если имя запрошенного метода содержит точки, каждый компонент имени метода ищется отдельно, в результате чего выполняется простая иерархическая проверка. Найденное значение затем вызывается с параметрами из запроса, а возвращаемое значение передаётся обратно клиенту.236237#### `CGIXMLRPCRequestHandler.register_introspection_functions()`238239Регистрирует функции интроспекции XML-RPC `system.listMethods`, `system.methodHelp` и `system.methodSignature`.240241#### `CGIXMLRPCRequestHandler.register_multicall_functions()`242243Регистрирует функцию мультивызова XML-RPC `system.multicall`.244245#### `CGIXMLRPCRequestHandler.handle_request(request_text=None)`246247Обрабатывает XML-RPC запрос. Если задан *request\_text*, он должен содержать POST-данные, предоставленные HTTP-сервером, в противном случае будет использовано содержимое stdin.248249Пример:250251```python252class MyFuncs:253    def mul(self, x, y):254        return x * y255256handler = CGIXMLRPCRequestHandler()257handler.register_function(pow)258handler.register_function(lambda x,y: x+y, 'add')259handler.register_introspection_functions()260handler.register_instance(MyFuncs())261handler.handle_request()262```263264## Документирование сервера XMLRPC265266Эти классы расширяют указанные выше классы, чтобы предоставлять HTML-документацию в ответ на HTTP GET запросы. Серверы могут быть автономными, с использованием [`DocXMLRPCServer`](https://python-all.ru/3.13/library/xmlrpc.server.html#xmlrpc.server.DocXMLRPCServer), или встроенными в CGI-среду, с использованием [`DocCGIXMLRPCRequestHandler`](https://python-all.ru/3.13/library/xmlrpc.server.html#xmlrpc.server.DocCGIXMLRPCRequestHandler).267268#### `class xmlrpc.server.DocXMLRPCServer(addr, requestHandler=DocXMLRPCRequestHandler, logRequests=True, allow_none=False, encoding=None, bind_and_activate=True, use_builtin_types=True)`269270Создаёт новый экземпляр сервера. Все параметры имеют то же значение, что и для [`SimpleXMLRPCServer`](https://python-all.ru/3.13/library/xmlrpc.server.html#xmlrpc.server.SimpleXMLRPCServer); *requestHandler* по умолчанию равен [`DocXMLRPCRequestHandler`](https://python-all.ru/3.13/library/xmlrpc.server.html#xmlrpc.server.DocXMLRPCRequestHandler).271272Изменено в версии 3.3: Добавлен флаг *use\_builtin\_types*.273274#### `class xmlrpc.server.DocCGIXMLRPCRequestHandler`275276Создаёт новый экземпляр для обработки XML-RPC запросов в CGI-среде.277278#### `class xmlrpc.server.DocXMLRPCRequestHandler`279280Создаёт новый экземпляр обработчика запросов. Этот обработчик запросов поддерживает XML-RPC POST-запросы, GET-запросы документации и изменяет протоколирование так, чтобы параметр *logRequests* конструктора [`DocXMLRPCServer`](https://python-all.ru/3.13/library/xmlrpc.server.html#xmlrpc.server.DocXMLRPCServer) соблюдался.281282## Объекты DocXMLRPCServer283284Класс [`DocXMLRPCServer`](https://python-all.ru/3.13/library/xmlrpc.server.html#xmlrpc.server.DocXMLRPCServer) является производным от [`SimpleXMLRPCServer`](https://python-all.ru/3.13/library/xmlrpc.server.html#xmlrpc.server.SimpleXMLRPCServer) и предоставляет средство создания самодокументируемых автономных XML-RPC серверов. HTTP POST запросы обрабатываются как вызовы методов XML-RPC. HTTP GET запросы обрабатываются генерацией HTML-документации в стиле pydoc. Это позволяет серверу предоставлять собственную веб-документацию.285286#### `DocXMLRPCServer.set_server_title(server_title)`287288Устанавливает заголовок, используемый в сгенерированной HTML-документации. Этот заголовок будет использоваться внутри элемента HTML «title».289290#### `DocXMLRPCServer.set_server_name(server_name)`291292Устанавливает имя, используемое в сгенерированной HTML-документации. Это имя будет отображаться в верхней части сгенерированной документации внутри элемента «h1».293294#### `DocXMLRPCServer.set_server_documentation(server_documentation)`295296Устанавливает описание, используемое в сгенерированной HTML-документации. Это описание будет отображаться в виде абзаца, под именем сервера, в документации.297298## DocCGIXMLRPCRequestHandler299300Класс [`DocCGIXMLRPCRequestHandler`](https://python-all.ru/3.13/library/xmlrpc.server.html#xmlrpc.server.DocCGIXMLRPCRequestHandler) является производным от [`CGIXMLRPCRequestHandler`](https://python-all.ru/3.13/library/xmlrpc.server.html#xmlrpc.server.CGIXMLRPCRequestHandler) и предоставляет средство создания самодокументируемых XML-RPC CGI-скриптов. HTTP POST запросы обрабатываются как вызовы методов XML-RPC. HTTP GET запросы обрабатываются генерацией HTML-документации в стиле pydoc. Это позволяет серверу предоставлять собственную веб-документацию.301302#### `DocCGIXMLRPCRequestHandler.set_server_title(server_title)`303304Устанавливает заголовок, используемый в сгенерированной HTML-документации. Этот заголовок будет использоваться внутри элемента HTML «title».305306#### `DocCGIXMLRPCRequestHandler.set_server_name(server_name)`307308Устанавливает имя, используемое в сгенерированной HTML-документации. Это имя будет отображаться в верхней части сгенерированной документации внутри элемента «h1».309310#### `DocCGIXMLRPCRequestHandler.set_server_documentation(server_documentation)`311312Устанавливает описание, используемое в сгенерированной HTML-документации. Это описание будет отображаться в виде абзаца, под именем сервера, в документации.313