> **Источник:** https://python-all.ru/3.5/library/http.client.html > > «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor. --- # 21.12. [`http.client`](https://python-all.ru/3.5/library/http.client.html#module-http.client) – клиент протокола HTTP **Исходный код:** [Lib/http/client.py](https://python-all.ru/src/3.5/Lib/http/client.py) --- Этот модуль определяет классы, реализующие клиентскую часть протоколов HTTP и HTTPS. Обычно он не используется напрямую – модуль [`urllib.request`](https://python-all.ru/3.5/library/urllib.request.html#module-urllib.request) использует его для обработки URL, которые используют HTTP и HTTPS. > **См. также** > > Для высокоуровневого интерфейса HTTP-клиента рекомендуется [пакет Requests](https://python-all.ru/3.5/library/http.client.html). > **Примечание** > > Поддержка HTTPS доступна только при компиляции Python с поддержкой SSL (через модуль [`ssl`](https://python-all.ru/3.5/library/ssl.html#module-ssl)). Модуль предоставляет следующие классы: #### `class http.client.HTTPConnection(host, port=None, [timeout, ]source_address=None)` Экземпляр [`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-соединения. Например, следующие вызовы создают экземпляры, подключающиеся к одному и тому же серверу по одному и тому же хосту и порту: ```python >>> h1 = http.client.HTTPConnection('www.python.org') >>> h2 = http.client.HTTPConnection('www.python.org:80') >>> h3 = http.client.HTTPConnection('www.python.org', 80) >>> h4 = http.client.HTTPConnection('www.python.org', 80, timeout=10) ``` Изменено в версии 3.2: Добавлен параметр *source\_address*. Изменено в версии 3.4: Параметр *strict* был удалён. Ответы в стиле HTTP 0.9 («простые ответы») больше не поддерживаются. #### `class http.client.HTTPSConnection(host, port=None, key_file=None, cert_file=None, [timeout, ]source_address=None, *, context=None, check_hostname=None)` Подкласс [`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. *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*. Пожалуйста, прочитайте [Рекомендации по безопасности](https://python-all.ru/3.5/library/ssl.html#ssl-security) для получения дополнительной информации о лучших практиках. Изменено в версии 3.2: Добавлены *source\_address*, *context* и *check\_hostname*. Изменено в версии 3.2: Теперь этот класс поддерживает виртуальные хосты HTTPS (если [`ssl.HAS_SNI`](https://python-all.ru/3.5/library/ssl.html#ssl.HAS_SNI) истинно). Изменено в версии 3.4: Параметр *strict* удалён. «Простые ответы» в стиле HTTP 0.9 больше не поддерживаются. Изменено в версии 3.4.3: Теперь этот класс по умолчанию выполняет все необходимые проверки сертификата и имени хоста. Чтобы вернуть прежнее непроверенное поведение, можно передать `ssl._create_unverified_context()` параметру *context*. #### `class http.client.HTTPResponse(sock, debuglevel=0, method=None, url=None)` Класс, экземпляры которого возвращаются при успешном соединении. Не создаётся напрямую пользователем. Изменено в версии 3.4: Параметр *strict* удалён. «Простые ответы» в стиле HTTP 0.9 больше не поддерживаются. При необходимости генерируются следующие исключения: #### `exception http.client.HTTPException` Базовый класс остальных исключений в этом модуле. Является подклассом [`Exception`](https://python-all.ru/3.5/library/exceptions.html#Exception). #### `exception http.client.NotConnected` Подкласс [`HTTPException`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPException). #### `exception http.client.InvalidURL` Подкласс [`HTTPException`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPException), возбуждается, если указан порт, который не является числом или пуст. #### `exception http.client.UnknownProtocol` Подкласс [`HTTPException`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPException). #### `exception http.client.UnknownTransferEncoding` Подкласс [`HTTPException`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPException). #### `exception http.client.UnimplementedFileMode` Подкласс [`HTTPException`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPException). #### `exception http.client.IncompleteRead` Подкласс [`HTTPException`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPException). #### `exception http.client.ImproperConnectionState` Подкласс [`HTTPException`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPException). #### `exception http.client.CannotSendRequest` Подкласс [`ImproperConnectionState`](https://python-all.ru/3.5/library/http.client.html#http.client.ImproperConnectionState). #### `exception http.client.CannotSendHeader` Подкласс [`ImproperConnectionState`](https://python-all.ru/3.5/library/http.client.html#http.client.ImproperConnectionState). #### `exception http.client.ResponseNotReady` Подкласс [`ImproperConnectionState`](https://python-all.ru/3.5/library/http.client.html#http.client.ImproperConnectionState). #### `exception http.client.BadStatusLine` Подкласс [`HTTPException`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPException). Возбуждается, если сервер отвечает HTTP-кодом состояния, который не распознаётся. #### `exception http.client.LineTooLong` Подкласс [`HTTPException`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPException). Возбуждается, если от сервера по протоколу HTTP получена чрезмерно длинная строка. #### `exception http.client.RemoteDisconnected` Подкласс [`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), когда при попытке чтения ответа из соединения не получено данных, что указывает на закрытие соединения удалённой стороной. Новое в версии 3.5: Ранее возбуждалось [`BadStatusLine`](https://python-all.ru/3.5/library/http.client.html#http.client.BadStatusLine)`('')`. Константы, определённые в этом модуле: #### `http.client.HTTP_PORT` Порт по умолчанию для протокола HTTP (всегда `80`). #### `http.client.HTTPS_PORT` Порт по умолчанию для протокола HTTPS (всегда `443`). #### `http.client.responses` Этот словарь сопоставляет коды состояния HTTP 1.1 с названиями W3C. Пример: `http.client.responses[http.client.NOT_FOUND]` – это `'Not Found'`. См. [коды состояния HTTP](https://python-all.ru/3.5/library/http.html#http-status-codes) для списка кодов состояния HTTP, доступных в этом модуле как константы. ## 21.12.1. Объекты HTTPConnection Экземпляры [`HTTPConnection`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPConnection) имеют следующие методы: #### `HTTPConnection.request(method, url, body=None, headers={})` Это отправляет запрос на сервер, используя метод HTTP *method* и селектор *url*. Если указан *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* – итератор, его элементы отправляются как есть, пока итератор не будет исчерпан. Аргумент *headers* должен быть отображением дополнительных HTTP-заголовков, отправляемых вместе с запросом. Если *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 не добавляется. Новое в версии 3.2: *body* теперь может быть итерируемым объектом. #### `HTTPConnection.getresponse()` Должен вызываться после отправки запроса для получения ответа от сервера. Возвращает экземпляр [`HTTPResponse`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPResponse). > **Примечание** > > Обратите внимание: необходимо прочитать весь ответ, прежде чем отправлять новый запрос на сервер. Изменено в версии 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) будет готов к переподключению при отправке нового запроса. #### `HTTPConnection.set_debuglevel(level)` Устанавливает уровень отладки. Уровень отладки по умолчанию – `0`, что означает отсутствие вывода отладочной информации. Любое значение больше `0` приведет к выводу всей текущей отладочной информации в stdout. Значение `debuglevel` передается всем новым создаваемым объектам [`HTTPResponse`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPResponse). Новое в версии 3.1. #### `HTTPConnection.set_tunnel(host, port=None, headers=None)` Устанавливает хост и порт для HTTP Connect Tunnelling. Это позволяет пропускать соединение через прокси-сервер. Аргументы host и port задают конечную точку туннелированного соединения (т.е. адрес, включённый в запрос CONNECT, *а не* адрес прокси-сервера). Аргумент headers должен быть отображением дополнительных HTTP-заголовков, отправляемых вместе с запросом CONNECT. Например, чтобы пройти туннель через 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): ```python >>> import http.client >>> conn = http.client.HTTPSConnection("localhost", 8080) >>> conn.set_tunnel("www.python.org") >>> conn.request("HEAD","/index.html") ``` Новое в версии 3.2. #### `HTTPConnection.connect()` Подключается к серверу, указанному при создании объекта. По умолчанию этот метод вызывается автоматически при выполнении запроса, если у клиента ещё нет соединения. #### `HTTPConnection.close()` Закрывает соединение с сервером. В качестве альтернативы использованию описанного выше метода `request()` вы также можете отправлять запрос пошагово, используя четыре функции, приведённые ниже. #### `HTTPConnection.putrequest(method, url, skip_host=False, skip_accept_encoding=False)` Этот вызов должен быть первым после установки соединения с сервером. Он отправляет на сервер строку, состоящую из строки *method*, строки *url* и версии HTTP (`HTTP/1.1`). Чтобы отключить автоматическую отправку заголовков `Host:` или `Accept-Encoding:` (например, для приёма дополнительных кодировок содержимого), укажите *skip\_host* или *skip\_accept\_encoding* со значением, отличным от False. #### `HTTPConnection.putheader(header, argument[, ...])` Отправляет заголовок в стиле [**RFC 822**](https://python-all.ru/3.5/library/http.client.html) на сервер. Он отправляет строку, состоящую из заголовка, двоеточия, пробела и первого аргумента. Если заданы дополнительные аргументы, отправляются строки продолжения, каждая из которых состоит из табуляции и аргумента. #### `HTTPConnection.endheaders(message_body=None)` Отправляет пустую строку серверу, сигнализируя об окончании заголовков. Необязательный аргумент *message\_body* можно использовать для передачи тела сообщения, связанного с запросом. Тело сообщения будет отправлено в том же пакете, что и заголовки, если оно является строкой; в противном случае оно отправляется в отдельном пакете. #### `HTTPConnection.send(data)` Отправляет данные на сервер. Это следует использовать напрямую только после вызова метода [`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). ## 21.12.2. Объекты HTTPResponse Экземпляр [`HTTPResponse`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPResponse) оборачивает HTTP-ответ от сервера. Он предоставляет доступ к заголовкам запроса и телу сущности. Ответ является итерируемым объектом и может использоваться в операторе with. Изменено в версии 3.5: Теперь реализован интерфейс [`io.BufferedIOBase`](https://python-all.ru/3.5/library/io.html#io.BufferedIOBase) и поддерживаются все его операции чтения. #### `HTTPResponse.read([amt])` Читает и возвращает тело ответа, или до следующих *amt* байт. #### `HTTPResponse.readinto(b)` Читает до следующих len(b) байт тела ответа в буфер *b*. Возвращает количество прочитанных байт. Новое в версии 3.3. #### `HTTPResponse.getheader(name, default=None)` Возвращает значение заголовка *name* или *default*, если нет заголовка, соответствующего *name*. Если существует более одного заголовка с именем *name*, возвращает все значения, объединённые через ', '. Если 'default' является любым итерируемым объектом, отличным от одной строки, его элементы аналогично возвращаются объединёнными запятыми. #### `HTTPResponse.getheaders()` Возвращает список кортежей (заголовок, значение). #### `HTTPResponse.fileno()` Возвращает `fileno` базового сокета. #### `HTTPResponse.msg` Экземпляр `http.client.HTTPMessage`, содержащий заголовки ответа. `http.client.HTTPMessage` является подклассом [`email.message.Message`](https://python-all.ru/3.5/library/email.message.html#email.message.Message). #### `HTTPResponse.version` Версия протокола HTTP, используемая сервером. 10 для HTTP/1.0, 11 для HTTP/1.1. #### `HTTPResponse.status` Код состояния, возвращаемый сервером. #### `HTTPResponse.reason` Фраза причины, возвращаемая сервером. #### `HTTPResponse.debuglevel` Отладочная привязка. Если [`debuglevel`](https://python-all.ru/3.5/library/http.client.html#http.client.HTTPResponse.debuglevel) больше нуля, сообщения будут выводиться в stdout по мере чтения и разбора ответа. #### `HTTPResponse.closed` Равно `True`, если поток закрыт. ## 21.12.3. Примеры Вот пример сеанса, в котором используется метод `GET`: ```python >>> import http.client >>> conn = http.client.HTTPSConnection("www.python.org") >>> conn.request("GET", "/") >>> r1 = conn.getresponse() >>> print(r1.status, r1.reason) 200 OK >>> data1 = r1.read() # Возвращает всё содержимое. >>> # Следующий пример демонстрирует чтение данных по частям. >>> conn.request("GET", "/") >>> r1 = conn.getresponse() >>> while not r1.closed: ... print(r1.read(200)) # 200 байт b'\n