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

Объекты HTTPConnection

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

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

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

Если указан параметр body, указанные данные отправляются после завершения заголовков. Это может быть str, объект, подобный байтам, открытый объект файла или итерируемый набор bytes. Если body — строка, она кодируется как ISO-8859-1, что является значением по умолчанию для HTTP. Если это объект, подобный байтам, байты отправляются как есть. Если это объект файла, содержимое файла отправляется; этот объект файла должен поддерживать метод 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 — строка или объект, подобный байтам, который также не является файлом, заголовок Content-Length устанавливается в его длину. Любой другой тип body (файлы и итерируемые объекты в общем случае) будут закодированы с помощью фрагментации, и вместо Content-Length автоматически будет установлен заголовок Transfer-Encoding.

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

Примечание

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

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

В версии 3.6: Если в headers не указаны ни Content-Length, ни Transfer-Encoding, объекты 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, а не адрес прокси-сервера).

Аргумент 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()

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

Вызывает событие отладки 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 PUT запросы очень похожи на 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

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