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

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

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

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

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

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

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

Поскольку для туннелирования HTTP CONNECT используется HTTP/1.1, согласно RFC 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 больше нуля, сообщения будут выводиться в стандартный вывод по мере чтения и разбора ответа.

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

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

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