http.client – клиент протокола HTTP¶http.client – HTTP protocol client

Объекты HTTPConnection¶HTTPConnection Objects

Экземпляры HTTPConnection имеют следующие методы:

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

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

If body is specified, the specified data is sent after the headers are finished. It may be a str, a bytes-like object, an open file object, or an iterable of bytes. If body is a string, it is encoded as ISO-8859-1, the default for HTTP. If it is a bytes-like object, the bytes are sent as is. If it is a file object, the contents of the file is sent; this file object should support at least the read() method. If the file object is an instance of io.TextIOBase, the data returned by the read() method will be encoded as ISO-8859-1, otherwise the data returned by read() is sent as is. If body is an iterable, the elements of the iterable are sent as is until the iterable is exhausted.

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

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

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

Примечание

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

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

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

Аргументы host и port задают конечную точку туннелированного соединения (т.е. адрес, включённый в запрос 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 со значением, отличным от False.

HTTPConnection.putheader(header, argument[, ...])¶

Отправляет заголовок в стиле RFC 822 на сервер. Он отправляет строку, состоящую из заголовка, двоеточия, пробела и первого аргумента. Если заданы дополнительные аргументы, отправляются строки продолжения, каждая из которых состоит из табуляции и аргумента.

HTTPConnection.endheaders(message_body=None, *, encode_chunked=False)¶

Отправляет пустую строку на сервер, сигнализируя об окончании заголовков. Необязательный аргумент message_body можно использовать для передачи тела сообщения, связанного с запросом.

Если encode_chunked равно True, результат каждой итерации message_body будет кодироваться по частям (chunk-encoded), как указано в 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 Objects

Экземпляр 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.

Примеры¶Examples

Вот пример сеанса, в котором используется метод 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()  # Возвращает всё содержимое.
>>> # Следующий пример демонстрирует чтение данных по частям.
>>> conn.request("GET", "/")
>>> r1 = conn.getresponse()
>>> while chunk := r1.read(200):
...     print(repr(chunk))
b'<!doctype html>\n<!--[if"...
...
>>> # Пример некорректного запроса
>>> 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:

>>> # Это создаёт HTTP-запрос
>>> # с содержимым BODY в качестве вложенного представления
>>> # для ресурса 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¶HTTPMessage Objects

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