`xmlrpc.client.md`

482 строк · 27.0 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.0/library/xmlrpc.client.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `xmlrpc.client` – клиентский доступ к XML-RPC89XML-RPC – это метод удаленного вызова процедур, использующий XML, передаваемый через HTTP в качестве tранспорта. С его помощью клиент может вызывать методы с параметрами на удаленном сервере (сервер задается URI) и получать структурированные данные. Этот модуль поддерживает написание клиентского кода XML-RPC; он обрабатывает все детали преобразования между совместимыми объектами Python и XML при передаче.1011#### `[xmlrpc.client.ServerProxy]class xmlrpc.client.ServerProxy(uri[, transport[, encoding[, verbose[, allow_none[, use_datetime]]]]])`1213Экземпляр [`ServerProxy`](https://python-all.ru/3.0/library/xmlrpc.client.html#xmlrpc.client.ServerProxy) – это объект, управляющий взаимодействием с удалённым XML-RPC сервером. Обязательный первый аргумент – это URI (Uniform Resource Indicator), обычно это URL сервера. Второй необязательный аргумент – это экземпляр фабрики транспорта; по умолчанию это внутренний экземпляр `SafeTransport` для URL с https: и внутренний HTTP `Transport` в остальных случаях. Третий необязательный аргумент – это кодировка, по умолчанию UTF-8. Четвертый необязательный аргумент – флаг отладки. Если *allow\_none* истинно, то константа Python `None` будет преобразована в XML; по умолчанию `None` вызывает исключение [`TypeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.TypeError). Это часто используемое расширение спецификации XML-RPC, но поддерживается не всеми клиентами и серверами; описание см. на [http://ontosys.com/xml-rpc/extensions.php](https://python-all.ru/3.0/library/xmlrpc.client.html). Флаг *use\_datetime* можно использовать, чтобы значения даты/времени представлялись как объекты [`datetime.datetime`](https://python-all.ru/3.0/library/datetime.html#datetime.datetime); по умолчанию он равен false. Объекты [`datetime.datetime`](https://python-all.ru/3.0/library/datetime.html#datetime.datetime) можно передавать в вызовы.1415Оба транспорта, HTTP и HTTPS, поддерживают расширение синтаксиса URL для HTTP базовой аутентификации: `http://user:pass@host:port/path`. Часть `user:pass` будет закодирована в base64 как HTTP-заголовок ‘Authorization’ и отправлена на удаленный сервер в процессе установки соединения при вызове метода XML-RPC. Использовать это нужно только в том случае, если удаленный сервер требует имя пользователя и пароль для базовой аутентификации.1617Возвращаемый экземпляр – это прокси-объект с методами, которые можно использовать для вызова соответствующих RPC-вызовов на удалённом сервере. Если удалённый сервер поддерживает API интроспекции, прокси также можно использовать для запроса методов, которые он поддерживает (обнаружение служб), и получения других метаданных, связанных с сервером.1819Методы экземпляра [`ServerProxy`](https://python-all.ru/3.0/library/xmlrpc.client.html#xmlrpc.client.ServerProxy) принимают в качестве аргументов основные типы и объекты Python и возвращают основные типы и классы Python. Типы, которые являются совместимыми (т.е. могут быть преобразованы через XML), включают следующие (и, если не указано иное, они десериализуются в тот же тип Python):2021| Имя | Значение |22| --- | --- |23| `логическое значение` | Константы [`True`](https://python-all.ru/3.0/library/constants.html#True) и [`False`](https://python-all.ru/3.0/library/constants.html#False) |24| `целые числа` | Передаются напрямую |25| `с плавающей запятой числа` | Передаются напрямую |26| `строки` | Передаются напрямую |27| `массивы` | Любой тип последовательности Python, содержащий совместимые элементы. Массивы возвращаются как списки. |28| `структуры` | Словарь Python. Ключи должны быть строками, значения – любым совместимым типом. Можно передавать объекты пользовательских классов; передается только их атрибут *\_\_dict\_\_*. |29| `даты` | в секундах с начала эпохи (передаётся экземпляр класса `DateTime`) или экземпляр [`datetime.datetime`](https://python-all.ru/3.0/library/datetime.html#datetime.datetime). |30| `двоичные данные` | передаётся экземпляр класса-обёртки `Binary` |3132Это полный набор типов данных, поддерживаемых XML-RPC. Вызовы методов также могут возбуждать специальный экземпляр `Fault`, используемый для сигнализации ошибок сервера XML-RPC, или `ProtocolError`, используемый для сигнализации ошибки на транспортном уровне HTTP/HTTPS. И `Fault`, и `ProtocolError` являются производными от базового класса `Error`. Обратите внимание, что модуль xmlrpc.client в настоящее время не маршалирует экземпляры подклассов встроенных типов.3334При передаче строк символы, имеющие специальное значение в XML, такие как `<`, `>` и `&`, автоматически экранируются. Однако вызывающий код должен обеспечить, чтобы строка не содержала символов, недопустимых в XML, например, управляющих символов с ASCII-кодами от 0 до 31 (за исключением, разумеется, табуляции, перевода строки и возврата каретки); несоблюдение этого приведёт к XML-RPC запросу, который не является корректным XML. Если нужно передавать произвольные строки через XML-RPC, используйте класс-обёртку `Binary`, описанный ниже.3536`Server` сохранен как псевдоним [`ServerProxy`](https://python-all.ru/3.0/library/xmlrpc.client.html#xmlrpc.client.ServerProxy) для обратной совместимости. В новом коде следует использовать [`ServerProxy`](https://python-all.ru/3.0/library/xmlrpc.client.html#xmlrpc.client.ServerProxy).3738> **См. также**39>40> **[Руководство по XML-RPC](https://python-all.ru/3.0/library/xmlrpc.client.html)**41>42> Хорошее описание работы XML-RPC и клиентского ПО на нескольких языках. Содержит практически всё, что нужно знать разработчику XML-RPC клиента.43>44> **[Интроспекция XML-RPC](https://python-all.ru/3.0/library/xmlrpc.client.html)**45>46> Описывает расширение протокола XML-RPC для интроспекции.47>48> **[Спецификация XML-RPC](https://python-all.ru/3.0/library/xmlrpc.client.html)**49>50> Официальная спецификация.51>52> **[Неофициальные исправления XML-RPC](https://python-all.ru/3.0/library/xmlrpc.client.html)**53>54> «Неофициальные исправления» Фредрика Лунда, предназначенные для разъяснения некоторых деталей спецификации XML-RPC, а также для указания на «лучшие практики» при разработке собственных реализаций XML-RPC.5556## Объекты ServerProxy5758Экземпляр [`ServerProxy`](https://python-all.ru/3.0/library/xmlrpc.client.html#xmlrpc.client.ServerProxy) имеет метод, соответствующий каждому удаленному вызову процедуры, принимаемому XML-RPC сервером. Вызов метода выполняет RPC, диспетчеризуемый по имени и сигнатуре аргументов (например, одно и то же имя метода может быть перегружено несколькими сигнатурами). RPC завершается возвратом значения, которое может быть либо возвращенными данными в совместимом типе, либо объектом `Fault` или `ProtocolError`, указывающим на ошибку.5960Серверы, поддерживающие XML introspection API, предоставляют несколько общих методов, сгруппированных под зарезервированным членом `system`:6162#### `[xmlrpc.client.ServerProxy.system.listMethods]ServerProxy.system.listMethods()`6364Этот метод возвращает список строк, по одной для каждого (не системного) метода, поддерживаемого XML-RPC сервером.6566#### `[xmlrpc.client.ServerProxy.system.methodSignature]ServerProxy.system.methodSignature(name)`6768Этот метод принимает один параметр – имя метода, реализованного сервером XML-RPC. Он возвращает массив возможных сигнатур для этого метода. Сигнатура представляет собой массив типов. Первый из этих типов – тип возвращаемого значения метода, остальные – параметры.6970Поскольку допускается несколько сигнатур (т.е. перегрузка), этот метод возвращает список сигнатур, а не один элемент.7172Сигнатуры ограничены параметрами верхнего уровня, ожидаемыми методом. Например, если метод ожидает один массив структур в качестве параметра и возвращает строку, его сигнатура – просто «string, array». Если он ожидает три целых числа и возвращает строку, его сигнатура – «string, int, int, int».7374Если сигнатура для метода не определена, возвращается значение, не являющееся массивом. В Python это означает, что тип возвращаемого значения будет отличаться от list.7576#### `[xmlrpc.client.ServerProxy.system.methodHelp]ServerProxy.system.methodHelp(name)`7778Этот метод принимает один параметр – имя метода, реализованного XML-RPC сервером. Он возвращает строку документации, описывающую использование этого метода. Если такая строка отсутствует, возвращается пустая строка. Строка документации может содержать HTML-разметку.7980Далее следует работающий пример. Код сервера:8182```python83from xmlrpc.server import SimpleXMLRPCServer8485def is_even(n):86    return n%2 == 08788server = SimpleXMLRPCServer(("localhost", 8000))89print("Listening on port 8000...")90server.register_function(is_even, "is_even")91server.serve_forever()92```9394Клиентский код для указанного сервера:9596```python97import xmlrpc.client9899proxy = xmlrpc.client.ServerProxy("http://localhost:8000/")100print("3 is even: %s" % str(proxy.is_even(3)))101print("100 is even: %s" % str(proxy.is_even(100)))102```103104## Объекты даты и времени105106Этот класс может быть инициализирован секундами с начала эпохи, временным кортежем, строкой времени/даты в формате ISO 8601 или экземпляром [`datetime.datetime`](https://python-all.ru/3.0/library/datetime.html#datetime.datetime). Он имеет следующие методы, поддерживаемые в основном для внутреннего использования кодом маршалинга/демаршалинга:107108#### `[xmlrpc.client.DateTime.decode]DateTime.decode(string)`109110Принимает строку в качестве нового значения времени экземпляра.111112#### `[xmlrpc.client.DateTime.encode]DateTime.encode(out)`113114Записывает XML-RPC кодирование этого элемента115116`DateTime`117118в объект потока119120*out*121122.123124Он также поддерживает некоторые встроенные операторы Python через методы расширенного сравнения и [`__repr__()`](https://python-all.ru/3.0/reference/datamodel.html#object.__repr__).125126Далее следует работающий пример. Код сервера:127128```python129import datetime130from xmlrpc.server import SimpleXMLRPCServer131import xmlrpc.client132133def today():134    today = datetime.datetime.today()135    return xmlrpc.client.DateTime(today)136137server = SimpleXMLRPCServer(("localhost", 8000))138print("Listening on port 8000...")139server.register_function(today, "today")140server.serve_forever()141```142143Клиентский код для указанного сервера:144145```python146import xmlrpc.client147import datetime148149proxy = xmlrpc.client.ServerProxy("http://localhost:8000/")150151today = proxy.today()152# преобразует строку в формате ISO8601 в объект datetime153converted = datetime.datetime.strptime(today.value, "%Y%m%dT%H:%M:%S")154print("Today: %s" % converted.strftime("%d.%m.%Y, %H:%M"))155```156157## Двоичные объекты158159Этот класс может быть инициализирован строковыми данными (которые могут содержать NUL). Основной доступ к содержимому объекта `Binary` осуществляется через атрибут:160161#### `[xmlrpc.client.Binary.data]Binary.data`162163Двоичные данные, инкапсулированные экземпляром164165`Binary`166167. Данные предоставляются в виде 8-битной строки.168169Объекты `Binary` имеют следующие методы, поддерживаемые в основном для внутреннего использования кодом маршалинга/демаршалинга:170171#### `[xmlrpc.client.Binary.decode]Binary.decode(string)`172173Принимает строку в base64 и декодирует её как новые данные экземпляра.174175#### `[xmlrpc.client.Binary.encode]Binary.encode(out)`176177Записывает XML-RPC base64-кодирование этого двоичного элемента в объект потока out.178179Закодированные данные будут содержать символы новой строки каждые 76 символов согласно [RFC 2045, раздел 6.8](https://python-all.ru/3.0/library/xmlrpc.client.html), что было фактическим стандартом спецификации base64 на момент написания спецификации XML-RPC.180181Он также поддерживает некоторые встроенные операторы Python через методы [`__eq__()`](https://python-all.ru/3.0/reference/datamodel.html#object.__eq__) и [`__ne__()`](https://python-all.ru/3.0/reference/datamodel.html#object.__ne__).182183Пример использования двоичных объектов. Мы собираемся передать изображение через XMLRPC:184185```python186from xmlrpc.server import SimpleXMLRPCServer187import xmlrpc.client188189def python_logo():190     handle = open("python_logo.jpg")191     return xmlrpc.client.Binary(handle.read())192     handle.close()193194server = SimpleXMLRPCServer(("localhost", 8000))195print("Listening on port 8000...")196server.register_function(python_logo, 'python_logo')197198server.serve_forever()199```200201Клиент получает изображение и сохраняет его в файл:202203```python204import xmlrpc.client205206proxy = xmlrpc.client.ServerProxy("http://localhost:8000/")207handle = open("fetched_python_logo.jpg", "w")208handle.write(proxy.python_logo().data)209handle.close()210```211212## Объекты Fault213214Объект `Fault` инкапсулирует содержимое тега ошибки XML-RPC. Объекты Fault имеют следующие члены:215216#### `[xmlrpc.client.Fault.faultCode]Fault.faultCode`217218Строка, указывающая тип ошибки.219220#### `[xmlrpc.client.Fault.faultString]Fault.faultString`221222Строка, содержащая диагностическое сообщение, связанное с ошибкой.223224В следующем примере мы намеренно вызовем `Fault`, возвращая объект сложного типа. Код сервера:225226```python227from xmlrpc.server import SimpleXMLRPCServer228229# Произойдёт ошибка маршалинга, потому что возвращается230# комплексное число231def add(x,y):232    return x+y+0j233234server = SimpleXMLRPCServer(("localhost", 8000))235print("Listening on port 8000...")236server.register_function(add, 'add')237238server.serve_forever()239```240241Клиентский код для указанного сервера:242243```python244import xmlrpc.client245246proxy = xmlrpc.client.ServerProxy("http://localhost:8000/")247try:248    proxy.add(2, 5)249except xmlrpc.client.Fault, err:250    print("A fault occurred")251    print("Fault code: %d" % err.faultCode)252    print("Fault string: %s" % err.faultString)253```254255## Объекты ProtocolError256257Объект `ProtocolError` описывает ошибку протокола на уровне нижележащего транспорта (например, ошибку 404 «не найдено», если сервер, указанный в URI, не существует). Он имеет следующие члены:258259#### `[xmlrpc.client.ProtocolError.url]ProtocolError.url`260261URI или URL, вызвавший ошибку.262263#### `[xmlrpc.client.ProtocolError.errcode]ProtocolError.errcode`264265Код ошибки.266267#### `[xmlrpc.client.ProtocolError.errmsg]ProtocolError.errmsg`268269Сообщение об ошибке или диагностическая строка.270271#### `[xmlrpc.client.ProtocolError.headers]ProtocolError.headers`272273Словарь (dict), содержащий заголовки HTTP/HTTPS-запроса, вызвавшего ошибку.274275В следующем примере мы намеренно вызовем `ProtocolError`, указав неверный URI:276277```python278import xmlrpc.client279280# создать ServerProxy с недопустимым URI281proxy = xmlrpc.client.ServerProxy("http://invalidaddress/")282283try:284    proxy.some_method()285except xmlrpc.client.ProtocolError, err:286    print("A protocol error occurred")287    print("URL: %s" % err.url)288    print("HTTP/HTTPS headers: %s" % err.headers)289    print("Error code: %d" % err.errcode)290    print("Error message: %s" % err.errmsg)291```292293## Объекты MultiCall294295В [http://www.xmlrpc.com/discuss/msgReader%241208](https://python-all.ru/3.0/library/xmlrpc.client.html) представлен подход к объединению нескольких вызовов удаленного сервера в один запрос.296297#### `[xmlrpc.client.MultiCall]class xmlrpc.client.MultiCall(server)`298299Create an object used to boxcar method calls.300301*server*302303is the eventual target of the call. Calls can be made to the result object, but they will immediately return304305`None`306307, and only store the call name and parameters in the308309[`MultiCall`](https://python-all.ru/3.0/library/xmlrpc.client.html#xmlrpc.client.MultiCall)310311object. Calling the object itself causes all stored calls to be transmitted as a single312313`system.multicall`314315request. The result of this call is a316317[*generator*](https://python-all.ru/3.0/glossary.html#term-generator)318319; iterating over this generator yields the individual results.320321Пример использования этого класса приведён ниже. Код сервера322323```python324from xmlrpc.server import SimpleXMLRPCServer325326def add(x,y):327    return x+y328329def subtract(x, y):330    return x-y331332def multiply(x, y):333    return x*y334335def divide(x, y):336    return x/y337338# Простой сервер с простыми арифметическими функциями339server = SimpleXMLRPCServer(("localhost", 8000))340print("Listening on port 8000...")341server.register_multicall_functions()342server.register_function(add, 'add')343server.register_function(subtract, 'subtract')344server.register_function(multiply, 'multiply')345server.register_function(divide, 'divide')346server.serve_forever()347```348349Клиентский код для указанного сервера:350351```python352import xmlrpc.client353354proxy = xmlrpc.client.ServerProxy("http://localhost:8000/")355multicall = xmlrpc.client.MultiCall(proxy)356multicall.add(7,3)357multicall.subtract(7,3)358multicall.multiply(7,3)359multicall.divide(7,3)360result = multicall()361362print("7+3=%d, 7-3=%d, 7*3=%d, 7/3=%d" % tuple(result))363```364365## Вспомогательные функции366367#### `[xmlrpc.client.dumps]xmlrpc.client.dumps(params[, methodname[, methodresponse[, encoding[, allow_none]]]])`368369Преобразует370371*params*372373в XML-RPC запрос или в ответ, если374375*methodresponse*376377истинно.378379*params*380381может быть либо кортежем аргументов, либо экземпляром класса исключения382383`Fault`384385. Если386387*methodresponse*388389истинно, может быть возвращено только одно значение, то есть390391*params*392393должен иметь длину 1.394395*encoding*396397, если указан, определяет кодировку, используемую в генерируемом XML; по умолчанию UTF-8. Значение398399[`None`](https://python-all.ru/3.0/library/constants.html#None)400401в Python не может использоваться в стандартном XML-RPC; чтобы разрешить его использование через расширение, передайте истинное значение для402403*allow\_none*404405.406407#### `[xmlrpc.client.loads]xmlrpc.client.loads(data[, use_datetime])`408409Преобразует XML-RPC запрос или ответ в объекты Python, возвращая410411`(params, methodname)`412413.414415*params*416417– кортеж аргументов;418419*methodname*420421– строка или422423`None`424425, если имя метода отсутствует в пакете. Если XML-RPC пакет представляет собой условие ошибки, эта функция возбуждает исключение426427`Fault`428429. Флаг430431*use\_datetime*432433можно использовать, чтобы значения даты/времени представлялись как объекты434435[`datetime.datetime`](https://python-all.ru/3.0/library/datetime.html#datetime.datetime)436437; по умолчанию он равен False.438439## Пример клиентского использования440441```python442# простая тестовая программа (из спецификации XML-RPC)443from xmlrpc.client import ServerProxy, Error444445# server = ServerProxy("http://localhost:8000") # локальный сервер446server = ServerProxy("http://betty.userland.com")447448print(server)449450try:451    print(server.examples.getStateName(41))452except Error as v:453    print("ERROR", v)454```455456Для доступа к XML-RPC серверу через прокси необходимо определить собственный transport. Следующий пример показывает, как это сделать:457458```python459import xmlrpc.client, http.client460461class ProxiedTransport(xmlrpc.client.Transport):462    def set_proxy(self, proxy):463        self.proxy = proxy464    def make_connection(self, host):465        self.realhost = host466        h = http.client.HTTP(self.proxy)467        return h468    def send_request(self, connection, handler, request_body):469        connection.putrequest("POST", 'http://%s%s' % (self.realhost, handler))470    def send_host(self, connection, host):471        connection.putheader('Host', self.realhost)472473p = ProxiedTransport()474p.set_proxy('proxy-server:8080')475server = xmlrpc.client.Server('http://time.xmlrpc.com/RPC2', transport=p)476print(server.currentTime.getCurrentTime())477```478479## Пример клиентского и серверного использования480481См. [*пример SimpleXMLRPCServer*](https://python-all.ru/3.0/library/xmlrpc.server.html#simplexmlrpcserver-example).482