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

Объекты HTTPConnection¶HTTPConnection Objects

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

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

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

Примечание

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

Примечание

Обратите внимание, что необходимо полностью прочитать ответ или вызвать close(), если getresponse() вызвал исключение, отличное от ConnectionError, прежде чем можно будет отправить новый запрос на сервер.

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

Изменено в версии 3.6: Если в headers не установлены ни Content-Length, ни Transfer-Encoding, файловые и итерируемые объекты body теперь кодируются по частям (chunked). Был добавлен аргумент encode_chunked. Для файловых объектов не предпринимается попыток определить Content-Length.

HTTPConnection.getresponse()¶

Должен вызываться после отправки запроса для получения ответа от сервера. Возвращает экземпляр HTTPResponse.

Изменено в версии 3.5: Если возникло исключение ConnectionError или его подкласс, объект HTTPConnection будет готов к переподключению при отправке нового запроса.

Обратите внимание, что это не относится к OSError, вызванным нижележащим сокетом. Вместо этого вызывающий код отвечает за вызов close() на существующем соединении.

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.

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

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

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