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

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

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

Аргумент encode_chunked имеет значение только в том случае, если в 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, вызывающий сервер должен либо указать длину содержимого, либо передать 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, приведет к тому, что все отладочные выходные данные, определенные в данный момент, будут выводиться в стандартный вывод. debuglevel передается всем новым HTTPResponse созданным объектам.

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

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

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

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

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

Например, для туннелирования через прокси-сервер 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.

Примечание

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

Изменено в версии 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 больше нуля, сообщения будут выводиться в стандартный вывод по мере считывания и анализа ответа.

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 путем установки соответствующего атрибута method. Вот пример сеанса, в котором используется метод 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

Объекты HTTP-сообщений¶

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

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