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

Объекты HTTPConnection

HTTPConnection имеют следующие методы:

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

Этот метод отправляет запрос на сервер с использованием HTTP метода method и URI запроса url. Переданный url должен быть абсолютным путем, в соответствии с RFC 2616 §5.1.2 (если не подключаетесь к HTTP-прокси-серверу или не используете методы OPTIONS или CONNECT).

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

Параметр headers должен быть отображением дополнительных HTTP-заголовков для отправки с запросом. Необходимо предоставить заголовок Host, чтобы соответствовать RFC 2616 §5.1.2 (если не подключаетесь к HTTP-прокси-серверу или не используете методы OPTIONS или CONNECT).

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

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

Например, для выполнения запроса GET к https://docs.python.org/3/:

>>> import http.client
>>> host = "docs.python.org"
>>> conn = http.client.HTTPSConnection(host)
>>> conn.request("GET", "/3/", headers={"Host": host})
>>> response = conn.getresponse()
>>> print(response.status, response.reason)
200 OK

Примечание

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

Изменено в версии 3.2: body теперь может быть итерируемым объектом.

Изменено в версии 3.6: Если ни Content-Length, ни Transfer-Encoding не заданы в headers, файлы и итерируемые 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-туннелирования. Это позволяет использовать соединение через прокси-сервер.

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

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

Поскольку для запроса HTTP CONNECT tunnelling используется HTTP/1.1, согласно RFC, должен быть предоставлен заголовок HTTP Host:, соответствующий форме authority целевого запроса, предоставленного в качестве пункта назначения для запроса CONNECT. Если заголовок HTTP Host: не задан с помощью аргумента headers, он генерируется и передаётся автоматически.

Например, чтобы туннелировать через 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.

Изменено в версии 3.12: Запросы HTTP CONNECT tunnelling используют протокол HTTP/1.1, обновлённый с протокола HTTP/1.0. Host: Заголовки HTTP обязательны для HTTP/1.1, поэтому один будет автоматически сгенерирован и передан, если не указан в аргументе headers.

HTTPConnection.get_proxy_response_headers()

Возвращает словарь с заголовками ответа, полученного от прокси-сервера на запрос CONNECT.

Если запрос CONNECT не был отправлен, метод возвращает None.

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

HTTPConnection.connect()

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

Вызывает событие отладки 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 с ненулевыми значениями.

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 реализует интерфейс буфера, кодирование приведет к одному куску. Если message_body является collections.abc.Iterable, каждая итерация message_body приведет к куску. Если message_body является объектом файла, каждый вызов .read() приведет к куску. Метод автоматически сигнализирует о завершении данных, закодированных кусками, сразу после message_body.

Примечание

Из-за спецификации кодирования кусками пустые куски, возвращаемые телом-итератором, будут игнорироваться кодировщиком кусков. Это необходимо для предотвращения преждевременного завершения чтения запроса целевым сервером из-за неправильного кодирования.

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

HTTPConnection.send(data)

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

Возбуждает событие аудита 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.getcode()

Устаревшее с версии 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 на стороне клиента очень похожи на запросы POST. Разница заключается только в серверной части, где HTTP-серверы разрешают создание ресурсов посредством запросов PUT. Следует отметить, что пользовательские HTTP-методы также обрабатываются в urllib.request.Request путем установки соответствующего атрибута метода. Вот пример сессии, использующей метод PUT:

>>> # This creates an HTTP request
>>> # 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

class http.client.HTTPMessage(email.message.Message)

Объект http.client.HTTPMessage содержит заголовки из HTTP-ответа. Он реализован с использованием класса email.message.Message.