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 (файлы и итерируемые объекты в целом) будут закодированы с помощью метода chunking, и вместо Content-Length будет автоматически установлен заголовок Transfer-Encoding.

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

Примечание

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

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

Изменено в версии 3.6: Если ни Content-Length, ни Transfer-Encoding не заданы в headers, объекты body типа файл и итерируемый объект теперь закодированы с помощью метода chunking. Добавлен аргумент 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()

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

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

Примечание

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

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

HTTPConnection.send(data)

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

Объекты 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.status

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

HTTPResponse.reason

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

HTTPResponse.debuglevel

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

HTTPResponse.closed

Будет True, если поток закрыт.

Примеры

Вот пример сеанса, использующего метод 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="http://bugs.python.org/issue12524">http://bugs.python.org/issue12524</a>'
>>> conn.close()

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