http.client — Клиент протокола HTTP¶

Объекты HTTPConnection¶

Экземпляры HTTPConnection имеют следующие методы:

HTTPConnection.request(method, url, body=None, headers={}, *, encode_chunked=False)¶

Это отправит запрос на сервер, используя метод запроса HTTP method и селектор url.

Если указано body, указанные данные отправляются после завершения заголовков. Это может быть str, bytes-like object, открытый file object или итерабельность bytes. Если body является строкой, то она кодируется как ISO-8859-1, по умолчанию для HTTP. Если это байтоподобный объект, то байты отправляются как есть. Если это file object, отправляется содержимое файла; этот объект файла должен поддерживать, по крайней мере, метод read(). Если объект файла является экземпляром io.TextIOBase, данные, возвращаемые методом read(), будут закодированы как ISO-8859-1, иначе данные, возвращаемые методом read(), будут отправлены как есть. Если body является итерабельным, то элементы итерабельного файла отправляются как есть до тех пор, пока итерабельный файл не будет исчерпан.

Аргумент headers должен представлять собой отображение дополнительных HTTP-заголовков для отправки вместе с запросом.

Если headers не содержит ни Content-Length, ни Transfer-Encoding, но есть тело запроса, одно из этих полей заголовка будет добавлено автоматически. Если body имеет значение None, заголовок Content-Length устанавливается в значение 0 для методов, которые ожидают тело (PUT, POST и PATCH). Если body является строкой или байтоподобным объектом, который также не является file, заголовок Content-Length устанавливается на его длину. Любой другой тип body (файлы и итерабельные объекты в целом) будет закодирован в виде кусков, и вместо Content-Length автоматически будет установлен заголовок Transfer-Encoding.

Аргумент encode_chunked имеет значение, только если Transfer-Encoding указан в headers. Если encode_chunked имеет значение False, объект HTTPConnection предполагает, что все кодирование обрабатывается вызывающим кодом. Если значение True, тело будет закодировано по частям.

Примечание

В протокол HTTP версии 1.1 было добавлено кодирование передачи Chunked. Если не известно, что HTTP-сервер поддерживает HTTP 1.1, вызывающая сторона должна либо указать Content-Length, либо передать str или байтоподобный объект, не являющийся файлом, в качестве представления тела.

Добавлено в версии 3.2: Теперь body может быть итерабельным.

Изменено в версии 3.6: Если в заголовках не заданы ни Content-Length, ни Transfer-Encoding, объекты file и iterable body теперь кодируются по частям. Был добавлен аргумент encode_chunked. Не предпринимается попытка определить Content-Length для файловых объектов.

HTTPConnection.getresponse()¶

Вызывается после отправки запроса для получения ответа от сервера. Возвращает экземпляр HTTPResponse.

Примечание

Обратите внимание, что вы должны прочитать весь ответ, прежде чем отправлять новый запрос на сервер.

Изменено в версии 3.5: Если поднят ConnectionError или подкласс, объект HTTPConnection будет готов к переподключению при отправке нового запроса.

HTTPConnection.set_debuglevel(level)¶

Установите уровень отладки. По умолчанию уровень отладки равен 0, что означает, что отладочный вывод не печатается. Любое значение, превышающее 0, приведет к тому, что весь определенный в данный момент отладочный вывод будет выведен в stdout. Значение debuglevel передается всем новым создаваемым объектам HTTPResponse.

Добавлено в версии 3.1.

HTTPConnection.set_tunnel(host, port=None, headers=None)¶

Установите хост и порт для HTTP Connect Tunnelling. Это позволяет запускать соединение через прокси-сервер.

Аргументы host и port указывают конечную точку туннелированного соединения (т.е. адрес, включенный в запрос CONNECT, не адрес прокси-сервера).

Аргумент headers должен представлять собой отображение дополнительных HTTP-заголовков для отправки с запросом CONNECT.

Например, для туннелирования через HTTPS прокси-сервер, работающий локально на порту 8080, мы передадим адрес прокси-сервера в конструктор HTTPSConnection, а адрес хоста, до которого мы хотим добраться, в метод set_tunnel():

>>> import http.client
>>> conn = http.client.HTTPSConnection("localhost", 8080)
>>> conn.set_tunnel("www.python.org")
>>> conn.request("HEAD","/index.html")

Добавлено в версии 3.2.

HTTPConnection.connect()¶

Подключение к серверу, указанному при создании объекта. По умолчанию это вызывается автоматически при выполнении запроса, если у клиента еще нет соединения.

Вызывает auditing event http.client.connect с аргументами self, host, port.

HTTPConnection.close()¶

Закройте соединение с сервером.

HTTPConnection.blocksize¶

Размер буфера в байтах для отправки файлоподобного тела сообщения.

Добавлено в версии 3.7.

В качестве альтернативы использованию метода 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. Отправляет на сервер строку, состоящую из заголовка, двоеточия, пробела и первого аргумента. Если указано больше аргументов, отправляются продолженные строки, каждая из которых состоит из табуляции и аргумента.

HTTPConnection.endheaders(message_body=None, *, encode_chunked=False)¶

Отправляет пустую строку на сервер, сигнализируя о завершении заголовков. Необязательный аргумент message_body может быть использован для передачи тела сообщения, связанного с запросом.

Если encode_chunked имеет значение True, результат каждой итерации message_body будет закодирован по частям, как указано в RFC 7230, раздел 3.3.1. Способ кодирования данных зависит от типа message_body. Если message_body реализует buffer interface, то в результате кодирования будет получен один чанк. Если message_body является collections.abc.Iterable, то каждая итерация message_body приведет к появлению чанка. Если message_body является file object, то каждый вызов .read() приведет к появлению чанка. Метод автоматически сигнализирует о конце закодированных в чанк данных сразу после message_body.

Примечание

В связи со спецификацией кодировки chunked, пустые куски, выдаваемые телом итератора, будут игнорироваться chunk-encoder’ом. Это делается для того, чтобы избежать преждевременного завершения чтения запроса целевым сервером из-за неправильного кодирования.

Добавлено в версии 3.6: Поддержка кодирования в виде кусков. Был добавлен параметр encode_chunked.

HTTPConnection.send(data)¶

Отправить данные на сервер. Этот метод следует использовать непосредственно только после вызова метода endheaders() и до вызова getresponse().

Вызывает auditing event http.client.send с аргументами self, data.

Объекты HTTPResponse¶

Экземпляр HTTPResponse оборачивает ответ HTTP от сервера. Он предоставляет доступ к заголовкам запроса и телу сущности. Ответ является итерируемым объектом и может быть использован в операторе with.

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.

HTTPResponse.version¶

Версия протокола HTTP, используемая сервером. 10 для HTTP/1.0, 11 для HTTP/1.1.

HTTPResponse.url¶

URL полученного ресурса, обычно используется для определения того, было ли выполнено перенаправление.

HTTPResponse.headers¶

Заголовки ответа в виде экземпляра email.message.EmailMessage.

HTTPResponse.status¶

Код состояния, возвращаемый сервером.

HTTPResponse.reason¶

Фраза причины, возвращенная сервером.

HTTPResponse.debuglevel¶

Отладочный крючок. Если debuglevel больше нуля, сообщения будут выводиться в stdout по мере чтения и разбора ответа.

HTTPResponse.closed¶

Имеет значение True, если поток закрыт.

HTTPResponse.geturl()¶

Не рекомендуется, начиная с версии 3.9: Утратил силу в пользу url.

HTTPResponse.info()¶

Не рекомендуется, начиная с версии 3.9: Утратил силу в пользу headers.

HTTPResponse.getstatus()¶

Не рекомендуется, начиная с версии 3.9: Утратил силу в пользу status.

Примеры¶

Вот пример сессии, в которой используется метод GET:

>>> 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()  # This will return entire content.
>>> # The following example demonstrates reading data in chunks.
>>> conn.request("GET", "/")
>>> r1 = conn.getresponse()
>>> while chunk := r1.read(200):
...     print(repr(chunk))
b'<!doctype html>\n<!--[if"...
...
>>> # Example of an invalid request
>>> conn = http.client.HTTPSConnection("docs.python.org")
>>> conn.request("GET", "/parrot.spam")
>>> r2 = conn.getresponse()
>>> print(r2.status, r2.reason)
404 Not Found
>>> data2 = r2.read()
>>> conn.close()

Вот пример сессии, в которой используется метод HEAD. Обратите внимание, что метод HEAD никогда не возвращает никаких данных.

>>> import http.client
>>> conn = http.client.HTTPSConnection("www.python.org")
>>> conn.request("HEAD", "/")
>>> res = conn.getresponse()
>>> print(res.status, res.reason)
200 OK
>>> data = res.read()
>>> print(len(data))
0
>>> data == b''
True

Вот пример сеанса, который показывает, как POST запросов:

>>> import http.client, urllib.parse
>>> params = urllib.parse.urlencode({'@number': 12524, '@type': 'issue', '@action': 'show'})
>>> headers = {"Content-type": "application/x-www-form-urlencoded",
...            "Accept": "text/plain"}
>>> conn = http.client.HTTPConnection("bugs.python.org")
>>> conn.request("POST", "", params, headers)
>>> response = conn.getresponse()
>>> print(response.status, response.reason)
302 Found
>>> data = response.read()
>>> data
b'Redirecting to <a href="https://bugs.python.org/issue12524">https://bugs.python.org/issue12524</a>'
>>> conn.close()

Запросы HTTP PUT на стороне клиента очень похожи на запросы POST. Разница заключается только на стороне сервера, где HTTP-сервер позволяет создавать ресурсы с помощью запроса PUT. Следует отметить, что пользовательские методы HTTP также обрабатываются в urllib.request.Request путем установки соответствующего атрибута method. Вот пример сессии, показывающий, как отправить PUT запрос, используя http.client:

>>> # This creates an HTTP message
>>> # with the content of BODY as the enclosed representation
>>> # for the resource http://localhost:8080/file
...
>>> import http.client
>>> BODY = "***filecontents***"
>>> conn = http.client.HTTPConnection("localhost", 8080)
>>> conn.request("PUT", "/file", BODY)
>>> response = conn.getresponse()
>>> print(response.status, response.reason)
200, OK

Объекты HTTPMessage¶

Экземпляр http.client.HTTPMessage содержит заголовки из ответа HTTP. Он реализуется с помощью класса email.message.Message.