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.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="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.