http.client — клиент протокола HTTP

Объекты HTTPConnection

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

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

Отправляет запрос серверу, используя метод HTTP-запроса method и URI запроса url. Чтобы соответствовать требованиям RFC 2616 §5.1.2, переданный url должен быть абсолютным путём (за исключением случаев подключения к HTTP-прокси-серверу или использования методов OPTIONS или CONNECT).

Если указан body, заданные данные отправляются после завершения передачи заголовков. Это может быть str, объект, подобный байтам, открытый файловый объект или итерируемый объект, содержащий bytes. Если body — строка, она кодируется в ISO-8859-1, кодировку HTTP по умолчанию. Если это объект, подобный байтам, байты отправляются без изменений. Если это файловый объект, отправляется содержимое файла; такой файловый объект должен поддерживать как минимум метод read(). Если файловый объект является экземпляром io.TextIOBase, данные, возвращаемые методом read(), будут закодированы в ISO-8859-1; в противном случае данные, возвращаемые методом read(), отправляются без изменений. Если body — итерируемый объект, его элементы отправляются без изменений до исчерпания объекта.

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

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

Аргумент encode_chunked имеет значение только в том случае, если в headers указан Transfer-Encoding. Если 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

Примечание

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

Примечание

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

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

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

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

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

Поскольку для запроса HTTP CONNECT-туннеля используется HTTP/1.1, согласно RFC должен быть указан заголовок HTTP Host:, соответствующий форме полномочий цели запроса, заданной как адрес назначения запроса 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/1.1 обязательны заголовки HTTP Host:, поэтому они будут созданы и отправлены автоматически, если не указаны в аргументе 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 будет закодирован по частям, как указано в разделе 3.3.1 RFC 7230. Способ кодирования данных зависит от типа 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 больше нуля, сообщения будут выводиться в stdout по мере чтения и разбора ответа.

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.