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

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

Новое в версии 3.1.

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

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

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

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