`http.client.md`

352 строк · 26.7 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.5/library/http.client.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 21.12. [`http.client`](https://python-all.ru/3.5/library/http.client.html#module-http.client) – клиент протокола HTTP89**Исходный код:** [Lib/http/client.py](https://python-all.ru/src/3.5/Lib/http/client.py)1011---1213Этот модуль определяет классы, реализующие клиентскую часть протоколов HTTP и HTTPS. Обычно он не используется напрямую – модуль [`urllib.request`](https://python-all.ru/3.5/library/urllib.request.html#module-urllib.request) использует его для обработки URL, которые используют HTTP и HTTPS.1415> **См. также**16>17> Для высокоуровневого интерфейса HTTP-клиента рекомендуется [пакет Requests](https://python-all.ru/3.5/library/http.client.html).1819> **Примечание**20>21> Поддержка HTTPS доступна только при компиляции Python с поддержкой SSL (через модуль [`ssl`](https://python-all.ru/3.5/library/ssl.html#module-ssl)).2223Модуль предоставляет следующие классы:2425#### `class http.client.HTTPConnection(host, port=None, [timeout, ]source_address=None)`2627Экземпляр [`HTTPConnection`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPConnection) представляет одну транзакцию с HTTP-сервером. Экземпляр должен быть создан с указанием хоста и необязательного номера порта. Если номер порта не передан, порт извлекается из строки хоста, если она имеет вид `host:port`, в противном случае используется порт HTTP по умолчанию (80). Если указан необязательный параметр *timeout*, блокирующие операции (например, попытки подключения) будут завершаться по истечении указанного количества секунд (если параметр не задан, используется глобальная настройка таймаута по умолчанию). Необязательный параметр *source\_address* может быть кортежем (host, port), который используется в качестве исходного адреса для HTTP-соединения.2829Например, следующие вызовы создают экземпляры, подключающиеся к одному и тому же серверу по одному и тому же хосту и порту:3031```python32>>> h1 = http.client.HTTPConnection('www.python.org')33>>> h2 = http.client.HTTPConnection('www.python.org:80')34>>> h3 = http.client.HTTPConnection('www.python.org', 80)35>>> h4 = http.client.HTTPConnection('www.python.org', 80, timeout=10)36```3738Изменено в версии 3.2: Добавлен параметр *source\_address*.3940Изменено в версии 3.4: Параметр *strict* был удалён. Ответы в стиле HTTP 0.9 («простые ответы») больше не поддерживаются.4142#### `class http.client.HTTPSConnection(host, port=None, key_file=None, cert_file=None, [timeout, ]source_address=None, *, context=None, check_hostname=None)`4344Подкласс [`HTTPConnection`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPConnection), использующий SSL для связи с защищёнными серверами. Порт по умолчанию – `443`. Если указан *context*, он должен быть экземпляром [`ssl.SSLContext`](https://python-all.ru/3.5/library/ssl.html#ssl.SSLContext), описывающим различные параметры SSL.4546*key\_file* и *cert\_file* устарели; используйте [`ssl.SSLContext.load_cert_chain()`](https://python-all.ru/3.5/library/ssl.html#ssl.SSLContext.load_cert_chain) или позвольте [`ssl.create_default_context()`](https://python-all.ru/3.5/library/ssl.html#ssl.create_default_context) выбрать доверенные сертификаты ЦС вашей системы. Параметр *check\_hostname* также устарел; вместо него следует использовать атрибут [`ssl.SSLContext.check_hostname`](https://python-all.ru/3.5/library/ssl.html#ssl.SSLContext.check_hostname) объекта *context*.4748Пожалуйста, прочитайте [Рекомендации по безопасности](https://python-all.ru/3.5/library/ssl.html#ssl-security) для получения дополнительной информации о лучших практиках.4950Изменено в версии 3.2: Добавлены *source\_address*, *context* и *check\_hostname*.5152Изменено в версии 3.2: Теперь этот класс поддерживает виртуальные хосты HTTPS (если [`ssl.HAS_SNI`](https://python-all.ru/3.5/library/ssl.html#ssl.HAS_SNI) истинно).5354Изменено в версии 3.4: Параметр *strict* удалён. «Простые ответы» в стиле HTTP 0.9 больше не поддерживаются.5556Изменено в версии 3.4.3: Теперь этот класс по умолчанию выполняет все необходимые проверки сертификата и имени хоста. Чтобы вернуть прежнее непроверенное поведение, можно передать `ssl._create_unverified_context()` параметру *context*.5758#### `class http.client.HTTPResponse(sock, debuglevel=0, method=None, url=None)`5960Класс, экземпляры которого возвращаются при успешном соединении. Не создаётся напрямую пользователем.6162Изменено в версии 3.4: Параметр *strict* удалён. «Простые ответы» в стиле HTTP 0.9 больше не поддерживаются.6364При необходимости генерируются следующие исключения:6566#### `exception http.client.HTTPException`6768Базовый класс остальных исключений в этом модуле. Является подклассом [`Exception`](https://python-all.ru/3.5/library/exceptions.html#Exception).6970#### `exception http.client.NotConnected`7172Подкласс [`HTTPException`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPException).7374#### `exception http.client.InvalidURL`7576Подкласс [`HTTPException`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPException), возбуждается, если указан порт, который не является числом или пуст.7778#### `exception http.client.UnknownProtocol`7980Подкласс [`HTTPException`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPException).8182#### `exception http.client.UnknownTransferEncoding`8384Подкласс [`HTTPException`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPException).8586#### `exception http.client.UnimplementedFileMode`8788Подкласс [`HTTPException`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPException).8990#### `exception http.client.IncompleteRead`9192Подкласс [`HTTPException`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPException).9394#### `exception http.client.ImproperConnectionState`9596Подкласс [`HTTPException`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPException).9798#### `exception http.client.CannotSendRequest`99100Подкласс [`ImproperConnectionState`](https://python-all.ru/3.5/library/http.client.html#http.client.ImproperConnectionState).101102#### `exception http.client.CannotSendHeader`103104Подкласс [`ImproperConnectionState`](https://python-all.ru/3.5/library/http.client.html#http.client.ImproperConnectionState).105106#### `exception http.client.ResponseNotReady`107108Подкласс [`ImproperConnectionState`](https://python-all.ru/3.5/library/http.client.html#http.client.ImproperConnectionState).109110#### `exception http.client.BadStatusLine`111112Подкласс [`HTTPException`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPException). Возбуждается, если сервер отвечает HTTP-кодом состояния, который не распознаётся.113114#### `exception http.client.LineTooLong`115116Подкласс [`HTTPException`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPException). Возбуждается, если от сервера по протоколу HTTP получена чрезмерно длинная строка.117118#### `exception http.client.RemoteDisconnected`119120Подкласс [`ConnectionResetError`](https://python-all.ru/3.5/library/exceptions.html#ConnectionResetError) и [`BadStatusLine`](https://python-all.ru/3.5/library/http.client.html#http.client.BadStatusLine). Возбуждается [`HTTPConnection.getresponse()`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPConnection.getresponse), когда при попытке чтения ответа из соединения не получено данных, что указывает на закрытие соединения удалённой стороной.121122Новое в версии 3.5: Ранее возбуждалось [`BadStatusLine`](https://python-all.ru/3.5/library/http.client.html#http.client.BadStatusLine)`('')`.123124Константы, определённые в этом модуле:125126#### `http.client.HTTP_PORT`127128Порт по умолчанию для протокола HTTP (всегда `80`).129130#### `http.client.HTTPS_PORT`131132Порт по умолчанию для протокола HTTPS (всегда `443`).133134#### `http.client.responses`135136Этот словарь сопоставляет коды состояния HTTP 1.1 с названиями W3C.137138Пример: `http.client.responses[http.client.NOT_FOUND]` – это `'Not Found'`.139140См. [коды состояния HTTP](https://python-all.ru/3.5/library/http.html#http-status-codes) для списка кодов состояния HTTP, доступных в этом модуле как константы.141142## 21.12.1. Объекты HTTPConnection143144Экземпляры [`HTTPConnection`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPConnection) имеют следующие методы:145146#### `HTTPConnection.request(method, url, body=None, headers={})`147148Это отправляет запрос на сервер, используя метод HTTP *method* и селектор *url*.149150Если указан *body*, указанные данные отправляются после заголовков. Это может быть строка, [байтоподобный объект](https://python-all.ru/3.5/glossary.html#term-bytes-like-object), открытый [файловый объект](https://python-all.ru/3.5/glossary.html#term-file-object) или итератор из [байтоподобных объектов](https://python-all.ru/3.5/glossary.html#term-bytes-like-object). Если *body* – строка, она кодируется как ISO-8859-1, стандартная для HTTP. Если это байтоподобный объект, байты отправляются как есть. Если это [файловый объект](https://python-all.ru/3.5/glossary.html#term-file-object), отправляется содержимое файла; этот файловый объект должен поддерживать как минимум метод `read()`. Если файловый объект имеет атрибут `mode`, данные, возвращаемые методом `read()`, будут закодированы как ISO-8859-1, если атрибут `mode` не содержит подстроку `b`, в противном случае данные, возвращаемые `read()`, отправляются как есть. Если *body* – итератор, его элементы отправляются как есть, пока итератор не будет исчерпан.151152Аргумент *headers* должен быть отображением дополнительных HTTP-заголовков, отправляемых вместе с запросом.153154Если *headers* не содержит элемента Content-Length, он добавляется автоматически, если это возможно. Если *body* равен `None`, заголовок Content-Length устанавливается в `0` для методов, ожидающих тело (`PUT`, `POST` и `PATCH`). Если *body* – строка или байтовый объект, заголовок Content-Length устанавливается в его длину. Если *body* – [файловый объект](https://python-all.ru/3.5/glossary.html#term-file-object) и можно вызвать [`fstat()`](https://python-all.ru/3.5/library/os.html#os.fstat) для результата его метода `fileno()`, то заголовок Content-Length устанавливается в `st_size`, возвращаемое вызовом `fstat`. В противном случае заголовок Content-Length не добавляется.155156Новое в версии 3.2: *body* теперь может быть итерируемым объектом.157158#### `HTTPConnection.getresponse()`159160Должен вызываться после отправки запроса для получения ответа от сервера. Возвращает экземпляр [`HTTPResponse`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPResponse).161162> **Примечание**163>164> Обратите внимание: необходимо прочитать весь ответ, прежде чем отправлять новый запрос на сервер.165166Изменено в версии 3.5: Если возникло исключение [`ConnectionError`](https://python-all.ru/3.5/library/exceptions.html#ConnectionError) или его подкласс, объект [`HTTPConnection`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPConnection) будет готов к переподключению при отправке нового запроса.167168#### `HTTPConnection.set_debuglevel(level)`169170Устанавливает уровень отладки. Уровень отладки по умолчанию – `0`, что означает отсутствие вывода отладочной информации. Любое значение больше `0` приведет к выводу всей текущей отладочной информации в stdout. Значение `debuglevel` передается всем новым создаваемым объектам [`HTTPResponse`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPResponse).171172Новое в версии 3.1.173174#### `HTTPConnection.set_tunnel(host, port=None, headers=None)`175176Устанавливает хост и порт для HTTP Connect Tunnelling. Это позволяет пропускать соединение через прокси-сервер.177178Аргументы host и port задают конечную точку туннелированного соединения (т.е. адрес, включённый в запрос CONNECT, *а не* адрес прокси-сервера).179180Аргумент headers должен быть отображением дополнительных HTTP-заголовков, отправляемых вместе с запросом CONNECT.181182Например, чтобы пройти туннель через HTTPS-прокси-сервер, работающий локально на порту 8080, нужно передать адрес прокси конструктору [`HTTPSConnection`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPSConnection), а адрес хоста, который мы в конечном итоге хотим достичь, методу [`set_tunnel()`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPConnection.set_tunnel):183184```python185>>> import http.client186>>> conn = http.client.HTTPSConnection("localhost", 8080)187>>> conn.set_tunnel("www.python.org")188>>> conn.request("HEAD","/index.html")189```190191Новое в версии 3.2.192193#### `HTTPConnection.connect()`194195Подключается к серверу, указанному при создании объекта. По умолчанию этот метод вызывается автоматически при выполнении запроса, если у клиента ещё нет соединения.196197#### `HTTPConnection.close()`198199Закрывает соединение с сервером.200201В качестве альтернативы использованию описанного выше метода `request()` вы также можете отправлять запрос пошагово, используя четыре функции, приведённые ниже.202203#### `HTTPConnection.putrequest(method, url, skip_host=False, skip_accept_encoding=False)`204205Этот вызов должен быть первым после установки соединения с сервером. Он отправляет на сервер строку, состоящую из строки *method*, строки *url* и версии HTTP (`HTTP/1.1`). Чтобы отключить автоматическую отправку заголовков `Host:` или `Accept-Encoding:` (например, для приёма дополнительных кодировок содержимого), укажите *skip\_host* или *skip\_accept\_encoding* со значением, отличным от False.206207#### `HTTPConnection.putheader(header, argument[, ...])`208209Отправляет заголовок в стиле [**RFC 822**](https://python-all.ru/3.5/library/http.client.html) на сервер. Он отправляет строку, состоящую из заголовка, двоеточия, пробела и первого аргумента. Если заданы дополнительные аргументы, отправляются строки продолжения, каждая из которых состоит из табуляции и аргумента.210211#### `HTTPConnection.endheaders(message_body=None)`212213Отправляет пустую строку серверу, сигнализируя об окончании заголовков. Необязательный аргумент *message\_body* можно использовать для передачи тела сообщения, связанного с запросом. Тело сообщения будет отправлено в том же пакете, что и заголовки, если оно является строкой; в противном случае оно отправляется в отдельном пакете.214215#### `HTTPConnection.send(data)`216217Отправляет данные на сервер. Это следует использовать напрямую только после вызова метода [`endheaders()`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPConnection.endheaders) и до вызова [`getresponse()`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPConnection.getresponse).218219## 21.12.2. Объекты HTTPResponse220221Экземпляр [`HTTPResponse`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPResponse) оборачивает HTTP-ответ от сервера. Он предоставляет доступ к заголовкам запроса и телу сущности. Ответ является итерируемым объектом и может использоваться в операторе with.222223Изменено в версии 3.5: Теперь реализован интерфейс [`io.BufferedIOBase`](https://python-all.ru/3.5/library/io.html#io.BufferedIOBase) и поддерживаются все его операции чтения.224225#### `HTTPResponse.read([amt])`226227Читает и возвращает тело ответа, или до следующих *amt* байт.228229#### `HTTPResponse.readinto(b)`230231Читает до следующих len(b) байт тела ответа в буфер *b*. Возвращает количество прочитанных байт.232233Новое в версии 3.3.234235#### `HTTPResponse.getheader(name, default=None)`236237Возвращает значение заголовка *name* или *default*, если нет заголовка, соответствующего *name*. Если существует более одного заголовка с именем *name*, возвращает все значения, объединённые через ', '. Если 'default' является любым итерируемым объектом, отличным от одной строки, его элементы аналогично возвращаются объединёнными запятыми.238239#### `HTTPResponse.getheaders()`240241Возвращает список кортежей (заголовок, значение).242243#### `HTTPResponse.fileno()`244245Возвращает `fileno` базового сокета.246247#### `HTTPResponse.msg`248249Экземпляр `http.client.HTTPMessage`, содержащий заголовки ответа. `http.client.HTTPMessage` является подклассом [`email.message.Message`](https://python-all.ru/3.5/library/email.message.html#email.message.Message).250251#### `HTTPResponse.version`252253Версия протокола HTTP, используемая сервером. 10 для HTTP/1.0, 11 для HTTP/1.1.254255#### `HTTPResponse.status`256257Код состояния, возвращаемый сервером.258259#### `HTTPResponse.reason`260261Фраза причины, возвращаемая сервером.262263#### `HTTPResponse.debuglevel`264265Отладочная привязка. Если [`debuglevel`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPResponse.debuglevel) больше нуля, сообщения будут выводиться в stdout по мере чтения и разбора ответа.266267#### `HTTPResponse.closed`268269Равно `True`, если поток закрыт.270271## 21.12.3. Примеры272273Вот пример сеанса, в котором используется метод `GET`:274275```python276>>> import http.client277>>> conn = http.client.HTTPSConnection("www.python.org")278>>> conn.request("GET", "/")279>>> r1 = conn.getresponse()280>>> print(r1.status, r1.reason)281200 OK282>>> data1 = r1.read()  # Возвращает всё содержимое.283>>> # Следующий пример демонстрирует чтение данных по частям.284>>> conn.request("GET", "/")285>>> r1 = conn.getresponse()286>>> while not r1.closed:287...     print(r1.read(200))  # 200 байт288b'<!doctype html>\n<!--[if"...289...290>>> # Пример некорректного запроса291>>> conn.request("GET", "/parrot.spam")292>>> r2 = conn.getresponse()293>>> print(r2.status, r2.reason)294404 Not Found295>>> data2 = r2.read()296>>> conn.close()297```298299Вот пример сеанса, в котором используется метод `HEAD`. Обратите внимание, что метод `HEAD` никогда не возвращает данные.300301```python302>>> import http.client303>>> conn = http.client.HTTPSConnection("www.python.org")304>>> conn.request("HEAD", "/")305>>> res = conn.getresponse()306>>> print(res.status, res.reason)307200 OK308>>> data = res.read()309>>> print(len(data))3100311>>> data == b''312True313```314315Ниже приведён пример сеанса, показывающий, как отправлять `POST` запросы:316317```python318>>> import http.client, urllib.parse319>>> params = urllib.parse.urlencode({'@number': 12524, '@type': 'issue', '@action': 'show'})320>>> headers = {"Content-type": "application/x-www-form-urlencoded",321...            "Accept": "text/plain"}322>>> conn = http.client.HTTPConnection("bugs.python.org")323>>> conn.request("POST", "", params, headers)324>>> response = conn.getresponse()325>>> print(response.status, response.reason)326302 Found327>>> data = response.read()328>>> data329b'Redirecting to <a href="http://bugs.python.org/issue12524">http://bugs.python.org/issue12524</a>'330>>> conn.close()331```332333Клиентские `HTTP PUT`-запросы очень похожи на `POST`-запросы. Разница заключается только на стороне сервера, где HTTP-сервер позволяет создавать ресурсы через `PUT`-запрос. Следует отметить, что пользовательские HTTP-методы также обрабатываются в [`urllib.request.Request`](https://python-all.ru/3.5/library/urllib.request.html#urllib.request.Request) путём передачи соответствующего атрибута method. Ниже приведён пример сеанса работы, показывающий, как выполнить `PUT`-запрос с помощью http.client:334335```python336>>> # Это создаёт HTTP-сообщение.337>>> # с содержимым BODY в качестве вложенного представления338>>> # для ресурса http://localhost:8080/file339...340>>> import http.client341>>> BODY = "***filecontents***"342>>> conn = http.client.HTTPConnection("localhost", 8080)343>>> conn.request("PUT", "/file", BODY)344>>> response = conn.getresponse()345>>> print(response.status, response.reason)346200, OK347```348349## 21.12.4. Объекты HTTPMessage350351Экземпляр `http.client.HTTPMessage` содержит заголовки из HTTP ответа. Он реализован с помощью класса [`email.message.Message`](https://python-all.ru/3.5/library/email.message.html#email.message.Message).352