`http.client.md`

384 строк · 30.3 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.7/library/http.client.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`http.client`](https://python-all.ru/3.7/library/http.client.html#module-http.client) – клиент протокола HTTP89**Исходный код:** [Lib/http/client.py](https://python-all.ru/src/3.7/Lib/http/client.py)1011---1213Этот модуль определяет классы, реализующие клиентскую часть протоколов HTTP и HTTPS. Обычно он не используется напрямую – модуль [`urllib.request`](https://python-all.ru/3.7/library/urllib.request.html#module-urllib.request) использует его для обработки URL, которые используют HTTP и HTTPS.1415> **См. также**16>17> Для высокоуровневого интерфейса HTTP-клиента рекомендуется [пакет Requests](https://python-all.ru/3.7/library/http.client.html).1819> **Примечание**20>21> Поддержка HTTPS доступна только при компиляции Python с поддержкой SSL (через модуль [`ssl`](https://python-all.ru/3.7/library/ssl.html#module-ssl)).2223Модуль предоставляет следующие классы:2425#### `class http.client.HTTPConnection(host, port=None, [timeout, ]source_address=None, blocksize=8192)`2627Экземпляр [`HTTPConnection`](https://python-all.ru/3.7/library/http.client.html#http.client.HTTPConnection) представляет одну транзакцию с HTTP-сервером. Его следует создавать, передавая хост и, опционально, номер порта. Если номер порта не передан, порт извлекается из строки хоста, если она имеет вид `host:port`, иначе используется порт HTTP по умолчанию (80). Если задан необязательный параметр *timeout*, блокирующие операции (например, попытки подключения) будут прерываться по истечении указанного количества секунд (если параметр не задан, используется глобальная настройка таймаута по умолчанию). Необязательный параметр *source\_address* может быть кортежем (хост, порт), используемым в качестве исходного адреса для HTTP-соединения. Необязательный параметр *blocksize* задаёт размер буфера в байтах для отправки тела сообщения в виде файлоподобного объекта.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Изменено в версии 3.7: Добавлен параметр *blocksize*.4344#### `class http.client.HTTPSConnection(host, port=None, key_file=None, cert_file=None, [timeout, ]source_address=None, *, context=None, check_hostname=None, blocksize=8192)`4546Подкласс [`HTTPConnection`](https://python-all.ru/3.7/library/http.client.html#http.client.HTTPConnection), использующий SSL для связи с защищёнными серверами. Порт по умолчанию – `443`. Если указан *context*, он должен быть экземпляром [`ssl.SSLContext`](https://python-all.ru/3.7/library/ssl.html#ssl.SSLContext), описывающим различные параметры SSL.4748Пожалуйста, прочитайте [Рекомендации по безопасности](https://python-all.ru/3.7/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.7/library/ssl.html#ssl.HAS_SNI) истинно).5354Изменено в версии 3.4: Параметр *strict* удалён. «Простые ответы» в стиле HTTP 0.9 больше не поддерживаются.5556Изменено в версии 3.4.3: Теперь этот класс по умолчанию выполняет все необходимые проверки сертификата и имени хоста. Чтобы вернуть прежнее непроверенное поведение, можно передать `ssl._create_unverified_context()` параметру *context*.5758Изменено в версии 3.7.4: Этот класс теперь включает TLS 1.3 [`ssl.SSLContext.post_handshake_auth`](https://python-all.ru/3.7/library/ssl.html#ssl.SSLContext.post_handshake_auth) для контекста *context* по умолчанию или при передаче *cert\_file* с пользовательским *context*.5960Устарело с версии 3.6: *key\_file* и *cert\_file* устарели в пользу *context*. Пожалуйста, используйте [`ssl.SSLContext.load_cert_chain()`](https://python-all.ru/3.7/library/ssl.html#ssl.SSLContext.load_cert_chain) вместо этого, или пусть [`ssl.create_default_context()`](https://python-all.ru/3.7/library/ssl.html#ssl.create_default_context) выберет доверенные сертификаты CA системы.6162Параметр *check\_hostname* также устарел; следует использовать атрибут [`ssl.SSLContext.check_hostname`](https://python-all.ru/3.7/library/ssl.html#ssl.SSLContext.check_hostname) объекта *context*.6364#### `class http.client.HTTPResponse(sock, debuglevel=0, method=None, url=None)`6566Класс, экземпляры которого возвращаются при успешном соединении. Не создаётся напрямую пользователем.6768Изменено в версии 3.4: Параметр *strict* удалён. «Простые ответы» в стиле HTTP 0.9 больше не поддерживаются.6970При необходимости генерируются следующие исключения:7172#### `exception http.client.HTTPException`7374Базовый класс остальных исключений в этом модуле. Является подклассом [`Exception`](https://python-all.ru/3.7/library/exceptions.html#Exception).7576#### `exception http.client.NotConnected`7778Подкласс [`HTTPException`](https://python-all.ru/3.7/library/http.client.html#http.client.HTTPException).7980#### `exception http.client.InvalidURL`8182Подкласс [`HTTPException`](https://python-all.ru/3.7/library/http.client.html#http.client.HTTPException), возбуждается, если указан порт, который не является числом или пуст.8384#### `exception http.client.UnknownProtocol`8586Подкласс [`HTTPException`](https://python-all.ru/3.7/library/http.client.html#http.client.HTTPException).8788#### `exception http.client.UnknownTransferEncoding`8990Подкласс [`HTTPException`](https://python-all.ru/3.7/library/http.client.html#http.client.HTTPException).9192#### `exception http.client.UnimplementedFileMode`9394Подкласс [`HTTPException`](https://python-all.ru/3.7/library/http.client.html#http.client.HTTPException).9596#### `exception http.client.IncompleteRead`9798Подкласс [`HTTPException`](https://python-all.ru/3.7/library/http.client.html#http.client.HTTPException).99100#### `exception http.client.ImproperConnectionState`101102Подкласс [`HTTPException`](https://python-all.ru/3.7/library/http.client.html#http.client.HTTPException).103104#### `exception http.client.CannotSendRequest`105106Подкласс [`ImproperConnectionState`](https://python-all.ru/3.7/library/http.client.html#http.client.ImproperConnectionState).107108#### `exception http.client.CannotSendHeader`109110Подкласс [`ImproperConnectionState`](https://python-all.ru/3.7/library/http.client.html#http.client.ImproperConnectionState).111112#### `exception http.client.ResponseNotReady`113114Подкласс [`ImproperConnectionState`](https://python-all.ru/3.7/library/http.client.html#http.client.ImproperConnectionState).115116#### `exception http.client.BadStatusLine`117118Подкласс [`HTTPException`](https://python-all.ru/3.7/library/http.client.html#http.client.HTTPException). Возбуждается, если сервер отвечает HTTP-кодом состояния, который не распознаётся.119120#### `exception http.client.LineTooLong`121122Подкласс [`HTTPException`](https://python-all.ru/3.7/library/http.client.html#http.client.HTTPException). Возбуждается, если от сервера по протоколу HTTP получена чрезмерно длинная строка.123124#### `exception http.client.RemoteDisconnected`125126Подкласс [`ConnectionResetError`](https://python-all.ru/3.7/library/exceptions.html#ConnectionResetError) и [`BadStatusLine`](https://python-all.ru/3.7/library/http.client.html#http.client.BadStatusLine). Возбуждается [`HTTPConnection.getresponse()`](https://python-all.ru/3.7/library/http.client.html#http.client.HTTPConnection.getresponse), когда при попытке чтения ответа из соединения не получено данных, что указывает на закрытие соединения удалённой стороной.127128Новое в версии 3.5: Ранее возбуждалось [`BadStatusLine`](https://python-all.ru/3.7/library/http.client.html#http.client.BadStatusLine)`('')`.129130Константы, определённые в этом модуле:131132#### `http.client.HTTP_PORT`133134Порт по умолчанию для протокола HTTP (всегда `80`).135136#### `http.client.HTTPS_PORT`137138Порт по умолчанию для протокола HTTPS (всегда `443`).139140#### `http.client.responses`141142Этот словарь сопоставляет коды состояния HTTP 1.1 с названиями W3C.143144Пример: `http.client.responses[http.client.NOT_FOUND]` – это `'Not Found'`.145146См. [коды состояния HTTP](https://python-all.ru/3.7/library/http.html#http-status-codes) для списка кодов состояния HTTP, доступных в этом модуле как константы.147148## Объекты HTTPConnection149150Экземпляры [`HTTPConnection`](https://python-all.ru/3.7/library/http.client.html#http.client.HTTPConnection) имеют следующие методы:151152#### `HTTPConnection.request(method, url, body=None, headers={}, *, encode_chunked=False)`153154Это отправляет запрос на сервер, используя метод HTTP *method* и селектор *url*.155156If *body* is specified, the specified data is sent after the headers are finished. It may be a [`str`](https://python-all.ru/3.7/library/stdtypes.html#str), a [bytes-like object](https://python-all.ru/3.7/glossary.html#term-bytes-like-object), an open [file object](https://python-all.ru/3.7/glossary.html#term-file-object), or an iterable of [`bytes`](https://python-all.ru/3.7/library/stdtypes.html#bytes). If *body* is a string, it is encoded as ISO-8859-1, the default for HTTP. If it is a bytes-like object, the bytes are sent as is. If it is a [file object](https://python-all.ru/3.7/glossary.html#term-file-object), the contents of the file is sent; this file object should support at least the `read()` method. If the file object is an instance of [`io.TextIOBase`](https://python-all.ru/3.7/library/io.html#io.TextIOBase), the data returned by the `read()` method will be encoded as ISO-8859-1, otherwise the data returned by `read()` is sent as is. If *body* is an iterable, the elements of the iterable are sent as is until the iterable is exhausted.157158Аргумент *headers* должен быть отображением дополнительных HTTP-заголовков, отправляемых с запросом.159160Если *headers* не содержит ни Content-Length, ни Transfer-Encoding, но есть тело запроса, одно из этих полей заголовка будет добавлено автоматически. Если *body* равно `None`, заголовок Content-Length устанавливается в `0` для методов, которые ожидают тело (`PUT`, `POST` и `PATCH`). Если *body* является строкой или байтоподобным объектом, который не является также [файлом](https://python-all.ru/3.7/glossary.html#term-file-object), заголовок Content-Length устанавливается в его длину. Любой другой тип *body* (файлы и итерируемые объекты в целом) будет передаваться по частям, и заголовок Transfer-Encoding будет установлен автоматически вместо Content-Length.161162Аргумент *encode\_chunked* актуален только в том случае, если в *headers* указан Transfer-Encoding. Если *encode\_chunked* равно `False`, объект HTTPConnection предполагает, что всё кодирование выполняется вызывающим кодом. Если равно `True`, тело будет закодировано по частям (chunked).163164> **Примечание**165>166> Фрагментированное кодирование передачи (chunked transfer encoding) было добавлено в протокол HTTP версии 1.1. Если неизвестно, что HTTP-сервер поддерживает HTTP 1.1, вызывающий код должен либо указать Content-Length, либо передать [`str`](https://python-all.ru/3.7/library/stdtypes.html#str) или байтоподобный объект, который не является файлом, в качестве представления тела.167168Новое в версии 3.2: *body* теперь может быть итерируемым объектом.169170Изменено в версии 3.6: Если в *headers* не установлены ни Content-Length, ни Transfer-Encoding, файловые и итерируемые объекты *body* теперь кодируются по частям (chunked). Был добавлен аргумент *encode\_chunked*. Для файловых объектов не предпринимается попыток определить Content-Length.171172#### `HTTPConnection.getresponse()`173174Должен вызываться после отправки запроса для получения ответа от сервера. Возвращает экземпляр [`HTTPResponse`](https://python-all.ru/3.7/library/http.client.html#http.client.HTTPResponse).175176> **Примечание**177>178> Обратите внимание: необходимо прочитать весь ответ, прежде чем отправлять новый запрос на сервер.179180Изменено в версии 3.5: Если возникло исключение [`ConnectionError`](https://python-all.ru/3.7/library/exceptions.html#ConnectionError) или его подкласс, объект [`HTTPConnection`](https://python-all.ru/3.7/library/http.client.html#http.client.HTTPConnection) будет готов к переподключению при отправке нового запроса.181182#### `HTTPConnection.set_debuglevel(level)`183184Устанавливает уровень отладки. Уровень отладки по умолчанию – `0`, что означает отсутствие вывода отладочной информации. Любое значение больше `0` приведет к выводу всей текущей отладочной информации в stdout. Значение `debuglevel` передается всем новым создаваемым объектам [`HTTPResponse`](https://python-all.ru/3.7/library/http.client.html#http.client.HTTPResponse).185186Новое в версии 3.1.187188#### `HTTPConnection.set_tunnel(host, port=None, headers=None)`189190Устанавливает хост и порт для HTTP Connect Tunnelling. Это позволяет пропускать соединение через прокси-сервер.191192Аргументы host и port задают конечную точку туннелированного соединения (т.е. адрес, включённый в запрос CONNECT, *а не* адрес прокси-сервера).193194Аргумент headers должен быть отображением дополнительных HTTP-заголовков, отправляемых вместе с запросом CONNECT.195196Например, чтобы пройти туннель через HTTPS-прокси-сервер, работающий локально на порту 8080, нужно передать адрес прокси конструктору [`HTTPSConnection`](https://python-all.ru/3.7/library/http.client.html#http.client.HTTPSConnection), а адрес хоста, который мы в конечном итоге хотим достичь, методу [`set_tunnel()`](https://python-all.ru/3.7/library/http.client.html#http.client.HTTPConnection.set_tunnel):197198```python199>>> import http.client200>>> conn = http.client.HTTPSConnection("localhost", 8080)201>>> conn.set_tunnel("www.python.org")202>>> conn.request("HEAD","/index.html")203```204205Новое в версии 3.2.206207#### `HTTPConnection.connect()`208209Подключается к серверу, указанному при создании объекта. По умолчанию этот метод вызывается автоматически при выполнении запроса, если у клиента ещё нет соединения.210211#### `HTTPConnection.close()`212213Закрывает соединение с сервером.214215#### `HTTPConnection.blocksize`216217Размер буфера в байтах для отправки тела сообщения в виде файла.218219Добавлено в версии 3.7.220221В качестве альтернативы использованию описанного выше метода `request()` вы также можете отправлять запрос пошагово, используя четыре функции, приведённые ниже.222223#### `HTTPConnection.putrequest(method, url, skip_host=False, skip_accept_encoding=False)`224225Этот вызов должен быть первым после установки соединения с сервером. Он отправляет на сервер строку, состоящую из строки *method*, строки *url* и версии HTTP (`HTTP/1.1`). Чтобы отключить автоматическую отправку заголовков `Host:` или `Accept-Encoding:` (например, для приёма дополнительных кодировок содержимого), укажите *skip\_host* или *skip\_accept\_encoding* со значением, отличным от False.226227#### `HTTPConnection.putheader(header, argument[, ...])`228229Отправляет заголовок в стиле [**RFC 822**](https://python-all.ru/3.7/library/http.client.html) на сервер. Он отправляет строку, состоящую из заголовка, двоеточия, пробела и первого аргумента. Если заданы дополнительные аргументы, отправляются строки продолжения, каждая из которых состоит из табуляции и аргумента.230231#### `HTTPConnection.endheaders(message_body=None, *, encode_chunked=False)`232233Отправляет пустую строку на сервер, сигнализируя об окончании заголовков. Необязательный аргумент *message\_body* можно использовать для передачи тела сообщения, связанного с запросом.234235Если *encode\_chunked* равно `True`, результат каждой итерации *message\_body* будет кодироваться по частям (chunk-encoded), как указано в [**RFC 7230**](https://python-all.ru/3.7/library/http.client.html), раздел 3.3.1. Способ кодирования данных зависит от типа *message\_body*. Если *message\_body* реализует [интерфейс буфера](https://python-all.ru/3.7/c-api/buffer.html#bufferobjects), кодирование даст один чанк. Если *message\_body* – это [`collections.abc.Iterable`](https://python-all.ru/3.7/library/collections.abc.html#collections.abc.Iterable), каждая итерация *message\_body* даст чанк. Если *message\_body* – это [файловый объект](https://python-all.ru/3.7/glossary.html#term-file-object), каждый вызов `.read()` даст чанк. Метод автоматически сигнализирует об окончании данных, закодированных чанками, сразу после *message\_body*.236237> **Примечание**238>239> В соответствии со спецификацией кодирования чанками, пустые чанки, полученные из тела-итератора, будут игнорироваться кодировщиком чанков. Это сделано для предотвращения преждевременного завершения чтения запроса целевым сервером из-за неверного кодирования.240241Новое в версии 3.6: Поддержка фрагментированного кодирования. Был добавлен параметр *encode\_chunked*.242243#### `HTTPConnection.send(data)`244245Отправляет данные на сервер. Это следует использовать напрямую только после вызова метода [`endheaders()`](https://python-all.ru/3.7/library/http.client.html#http.client.HTTPConnection.endheaders) и до вызова [`getresponse()`](https://python-all.ru/3.7/library/http.client.html#http.client.HTTPConnection.getresponse).246247## Объекты HTTPResponse248249Экземпляр [`HTTPResponse`](https://python-all.ru/3.7/library/http.client.html#http.client.HTTPResponse) оборачивает HTTP-ответ от сервера. Он предоставляет доступ к заголовкам запроса и телу сущности. Ответ является итерируемым объектом и может использоваться в операторе with.250251Изменено в версии 3.5: Теперь реализован интерфейс [`io.BufferedIOBase`](https://python-all.ru/3.7/library/io.html#io.BufferedIOBase) и поддерживаются все его операции чтения.252253#### `HTTPResponse.read([amt])`254255Читает и возвращает тело ответа, или до следующих *amt* байт.256257#### `HTTPResponse.readinto(b)`258259Читает до следующих len(b) байт тела ответа в буфер *b*. Возвращает количество прочитанных байт.260261Новое в версии 3.3.262263#### `HTTPResponse.getheader(name, default=None)`264265Возвращает значение заголовка *name* или *default*, если нет заголовка, соответствующего *name*. Если существует более одного заголовка с именем *name*, возвращает все значения, объединённые через ', '. Если 'default' является любым итерируемым объектом, отличным от одной строки, его элементы аналогично возвращаются объединёнными запятыми.266267#### `HTTPResponse.getheaders()`268269Возвращает список кортежей (заголовок, значение).270271#### `HTTPResponse.fileno()`272273Возвращает `fileno` базового сокета.274275#### `HTTPResponse.msg`276277Экземпляр `http.client.HTTPMessage`, содержащий заголовки ответа. `http.client.HTTPMessage` является подклассом [`email.message.Message`](https://python-all.ru/3.7/library/email.compat32-message.html#email.message.Message).278279#### `HTTPResponse.version`280281Версия протокола HTTP, используемая сервером. 10 для HTTP/1.0, 11 для HTTP/1.1.282283#### `HTTPResponse.status`284285Код состояния, возвращаемый сервером.286287#### `HTTPResponse.reason`288289Фраза причины, возвращаемая сервером.290291#### `HTTPResponse.debuglevel`292293Отладочная привязка. Если [`debuglevel`](https://python-all.ru/3.7/library/http.client.html#http.client.HTTPResponse.debuglevel) больше нуля, сообщения будут выводиться в stdout по мере чтения и разбора ответа.294295#### `HTTPResponse.closed`296297Равно `True`, если поток закрыт.298299## Примеры300301Вот пример сеанса, в котором используется метод `GET`:302303```python304>>> import http.client305>>> conn = http.client.HTTPSConnection("www.python.org")306>>> conn.request("GET", "/")307>>> r1 = conn.getresponse()308>>> print(r1.status, r1.reason)309200 OK310>>> data1 = r1.read()  # Возвращает всё содержимое.311>>> # Следующий пример демонстрирует чтение данных по частям.312>>> conn.request("GET", "/")313>>> r1 = conn.getresponse()314>>> while True:315...     chunk = r1.read(200)  # 200 байт316...     if not chunk:317...          break318...     print(repr(chunk))319b'<!doctype html>\n<!--[if"...320...321>>> # Пример некорректного запроса322>>> conn = http.client.HTTPSConnection("docs.python.org")323>>> conn.request("GET", "/parrot.spam")324>>> r2 = conn.getresponse()325>>> print(r2.status, r2.reason)326404 Not Found327>>> data2 = r2.read()328>>> conn.close()329```330331Вот пример сеанса, в котором используется метод `HEAD`. Обратите внимание, что метод `HEAD` никогда не возвращает данные.332333```python334>>> import http.client335>>> conn = http.client.HTTPSConnection("www.python.org")336>>> conn.request("HEAD", "/")337>>> res = conn.getresponse()338>>> print(res.status, res.reason)339200 OK340>>> data = res.read()341>>> print(len(data))3420343>>> data == b''344True345```346347Ниже приведён пример сеанса, показывающий, как отправлять `POST` запросы:348349```python350>>> import http.client, urllib.parse351>>> params = urllib.parse.urlencode({'@number': 12524, '@type': 'issue', '@action': 'show'})352>>> headers = {"Content-type": "application/x-www-form-urlencoded",353...            "Accept": "text/plain"}354>>> conn = http.client.HTTPConnection("bugs.python.org")355>>> conn.request("POST", "", params, headers)356>>> response = conn.getresponse()357>>> print(response.status, response.reason)358302 Found359>>> data = response.read()360>>> data361b'Redirecting to <a href="http://bugs.python.org/issue12524">http://bugs.python.org/issue12524</a>'362>>> conn.close()363```364365Клиентские `HTTP PUT`-запросы очень похожи на `POST`-запросы. Разница заключается только на стороне сервера, где HTTP-сервер разрешает создавать ресурсы с помощью `PUT`-запроса. Следует отметить, что пользовательские HTTP-методы также обрабатываются в [`urllib.request.Request`](https://python-all.ru/3.7/library/urllib.request.html#urllib.request.Request) путём установки соответствующего атрибута method. Ниже приведён пример сеанса, показывающий, как отправить `PUT`-запрос с помощью http.client:366367```python368>>> # Это создаёт HTTP-сообщение.369>>> # с содержимым BODY в качестве вложенного представления370>>> # для ресурса http://localhost:8080/file371...372>>> import http.client373>>> BODY = "***filecontents***"374>>> conn = http.client.HTTPConnection("localhost", 8080)375>>> conn.request("PUT", "/file", BODY)376>>> response = conn.getresponse()377>>> print(response.status, response.reason)378200, OK379```380381## Объекты HTTPMessage382383Экземпляр `http.client.HTTPMessage` содержит заголовки из HTTP ответа. Он реализован с помощью класса [`email.message.Message`](https://python-all.ru/3.7/library/email.compat32-message.html#email.message.Message).384