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

Исходный код: Lib/http/client.py

Модуль определяет классы, реализующие клиентскую сторону протоколов HTTP и HTTPS. Он обычно не используется непосредственно, его использует модуль urllib.request, чтобы работать с URL, используемые в HTTP и HTTPS.

См.также

Пакет requests рекомендуется для высокоуровневого интерфейса клиента HTTP.

Примечание

Поддержка HTTPS доступна только если Python был собран с поддержкой SSL (через модуль ssl).

Модуль предоставляет следующие классы:

class http.client.HTTPConnection(host, port=None, [timeout, ]source_address=None, blocksize=8192)¶

HTTPConnection сущность представляет одну транзакцию с HTTP-сервером. Необходимо создать экземпляр, передав ему хост и дополнительный номер порта. Если никакой номер порта не передан, порт извлечен от хозяина строка, если у него есть форма host:port, еще дефолт, порт HTTP (80) является используемый. Если задан дополнительный параметр timeout, то по истечении этого периода времени будет истекать время ожидания блокирующих операций (например, попыток подключения) (если он не задан, то по умолчанию устанавливается глобальное время ожидания используемый). Необязательным параметром source_address может быть кортеж (хост, порт) для использования в качестве адреса источника, из которого устанавливается HTTP-соединение. Необязательный параметр blocksize задает размер буфера в байтах для отправки тела сообщения в виде файла.

Например, при следующих вызовах создаются все сущности, которые подключаются к серверу на одном хосте и порту:

>>> h1 = http.client.HTTPConnection('www.python.org')
>>> h2 = http.client.HTTPConnection('www.python.org:80')
>>> h3 = http.client.HTTPConnection('www.python.org', 80)
>>> h4 = http.client.HTTPConnection('www.python.org', 80, timeout=10)

Изменено в версии 3.2: source_address был добавлен.

Изменено в версии 3.4: Параметр strict удален. HTTP 0.9 «Простые ответы» больше не поддерживаются.

Изменено в версии 3.7: blocksize добавлен параметр.

class http.client.HTTPSConnection(host, port=None, key_file=None, cert_file=None, [timeout, ]source_address=None, *, context=None, check_hostname=None, blocksize=8192)¶

Подкласс HTTPConnection, использующий SSL для связи с защищенными серверами. Порт по умолчанию - 443. Если задан параметр context, он должен быть ssl.SSLContext сущность, описывающим различные параметры SSL.

Пожалуйста, прочитайте Соображения безопасности для получения дополнительной информации о лучших практиках.

Изменено в версии 3.2: source_address, context и check_hostname были добавлены.

Изменено в версии 3.2: Этот класс теперь поддерживает виртуальных хозяев HTTPS, если возможный (то есть, если ssl.HAS_SNI верен).

Изменено в версии 3.4: Параметр strict удален. HTTP 0.9 «Простые ответы» больше не поддерживаются.

Изменено в версии 3.4.3: Теперь этот класс выполняет все необходимые проверки сертификатов и имен узлов по умолчанию. Чтобы вернуться к предыдущему, непроверенному, поведение, ssl._create_unverified_context() может быть передан к параметру context.

Изменено в версии 3.8: Теперь этот класс включает TLS 1.3 ssl.SSLContext.post_handshake_auth для context по умолчанию или при передаче cert_file с пользовательским context.

Не рекомендуется, начиная с версии 3.6: key_file и cert_file обесцениваются в пользу context. Пожалуйста, используйте ssl.SSLContext.load_cert_chain() или позволь ssl.create_default_context() выбрать доверенный ЦС системы сертификации для вас.

Параметр check_hostname также устарел; ssl.SSLContext.check_hostname атрибут context должен быть используемый вместо этого.

class http.client.HTTPResponse(sock, debuglevel=0, method=None, url=None)¶: Класс, сущности которого - возвращенный на успешную связь. Не создан пользователем непосредственно.

Изменено в версии 3.4: Параметр strict удален. Стиль HTTP 0.9 «Простые ответы» больше не поддерживается.

Модуль предоставляет следующую функцию:

http.client.parse_headers(fp)¶

Анализ заголовков из указателя файла fp, представляющего HTTP- запрос/ответ. Файл должен быть устройством чтения BufferedIOBase (т.е. не текстом) и должен содержать допустимый заголовок стиля RFC 2822.

Эта функция возвращает сущность http.client.HTTPMessage, который держит поля заголовка, но никакой полезный груз (то же как HTTPResponse.msg и http.server.BaseHTTPRequestHandler.headers). После возврата указатель файла fp готов к чтению тела HTTP.

Примечание

parse_headers() не анализирует начальную строку HTTP-сообщения; он только анализирует Name: value строки. Файл должен быть готов для чтения этих строк поля, поэтому первая строка должна быть использована перед вызовом функции.

При необходимости возникают следующие исключения:

exception http.client.HTTPException¶: Базовый класс других исключений в этом модуле. Это подкласс Exception.

exception http.client.NotConnected¶: Подкласс HTTPException.

exception http.client.InvalidURL¶: Подкласс HTTPException, возникает, если порт задан и является нечисловым или пустым.

exception http.client.UnknownProtocol¶: Подкласс HTTPException.

exception http.client.UnknownTransferEncoding¶: Подкласс HTTPException.

exception http.client.UnimplementedFileMode¶: Подкласс HTTPException.

exception http.client.IncompleteRead¶: Подкласс HTTPException.

exception http.client.ImproperConnectionState¶: Подкласс HTTPException.

exception http.client.CannotSendRequest¶: Подкласс ImproperConnectionState.

exception http.client.CannotSendHeader¶: Подкласс ImproperConnectionState.

exception http.client.ResponseNotReady¶: Подкласс ImproperConnectionState.

exception http.client.BadStatusLine¶: Подкласс HTTPException. Поднятый, если сервер отвечает статусом HTTP код, который мы не понимаем.

exception http.client.LineTooLong¶: Подкласс HTTPException. Возникает при получении чрезмерно длинной строки в протоколе HTTP с сервера.

exception http.client.RemoteDisconnected¶: Подкласс ConnectionResetError и BadStatusLine. Возникает в HTTPConnection.getresponse(), когда попытка чтения ответа не приводит к считыванию данных из соединения, что указывает на то, что удаленный конец закрыл соединение.

Добавлено в версии 3.5: Ранее был поднят BadStatusLine('').

Константы, определенные в этом модуле:

http.client.HTTP_PORT¶: Порт по умолчанию для протокола HTTP (всегда 80).

http.client.HTTPS_PORT¶: Порт по умолчанию для протокола HTTPS (всегда 443).

http.client.responses¶

Этот словарь наносит на карту статус HTTP 1.1 коды к именам W3C.

Пример: http.client.responses[http.client.NOT_FOUND] есть 'Not Found'.

Список Статус HTTP коды состояния HTTP, доступных в этом модуле в качестве констант, см. в разделе коды.

Объекты HTTPConnection¶

HTTPConnection сущности имеют следующие методы:

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

Запрос будет отправлен на сервер с помощью HTTP-запроса method и селектора url.

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

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

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

Аргумент encode_chunked только релевантен, если кодирование передачи определено в headers. Если encode_chunked - False, объект HTTPConnection предполагает, что весь кодировка обработан запросом код. Если это будет True, тело будет чанк-кодированный.

Примечание

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

Добавлено в версии 3.2: Теперь body может быть итерабельной.

Изменено в версии 3.6: Если ни довольная длина, ни кодирование передачи не установлены в headers, файл и повторяемые объекты body - теперь чанк-кодированный. Добавлен аргумент encode_chunked. Попытка определения длины содержимого для файловых объектов не выполняется.

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()¶: Подключение к серверу, указанному при создании объекта. По умолчанию это вызывается автоматически при выполнении запроса, если у клиента еще нет подключения.

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 реализует buffer interface, кодировка приведет к одному чанк. Если message_body является collections.abc.Iterable, каждая итерация message_body приведет к чанк. Если message_body является файловым объектом, каждый вызов .read() приведет к чанк. Метод автоматически сигнализирует об окончании чанк-кодированный данных сразу после message_body.

Примечание

Due to the chunked encoding specification, empty chunks выданные телом итератора будут игнорироваться чанк-encoder. Это должно избежать преждевременного завершения прочитанного из запроса целевого сервера из-за уродливого кодировка.

Добавлено в версии 3.6: Частичная поддержка кодировка. Добавлен параметр encode_chunked.

HTTPConnection.send(data)¶: Отправка данных на сервер. Это должно быть используемый непосредственно только после того, как метод endheaders() назвали и прежде чем вызовется getresponse().

Объекты HTTPResponse¶

HTTPResponse сущность обертывает ответ HTTP от сервера. Он обеспечивает доступ к заголовкам запросов и телу объекта. Ответ - повторяемый объект и может быть используемый в с инструкция.

Изменено в версии 3.5: Интерфейс io.BufferedIOBase теперь реализован, и поддерживаются все его операции чтения.

HTTPResponse.read([amt])¶: Считывает и возвращает текст ответа или до следующих amt байт.

HTTPResponse.readinto(b)¶: Считывает до следующего len(b) байта тела ответа в буфер b. Возвращает число считанных байт.

Добавлено в версии 3.3.

HTTPResponse.getheader(name, default=None)¶: Возвращает значение заголовка name, или default, если заголовок не соответствует name. Если имеется несколько заголовков с именем name, возвращает все значения, соединенные „,“. Если „дефолт“ - кто- либо повторяемый кроме единственного строка, его элементы - аналогично возвращенный, к которому присоединяются запятые.

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.status¶: Состояние код возвращенный по серверу.

HTTPResponse.reason¶: Причина фразы возвращенный по серверу.

HTTPResponse.debuglevel¶: Отладочный хук. Если debuglevel больше нуля, сообщения будут распечатаны в stdout по мере чтения и анализа ответа.

HTTPResponse.closed¶: Является True, если поток закрыт.

Примеры¶

Вот пример сеанса, в котором используется метод 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="http://bugs.python.org/issue12524">http://bugs.python.org/issue12524</a>'
>>> conn.close()

Сторона клиента запросы HTTP PUT очень похожа на запросы POST. Разница заключается только в стороне сервера, где HTTP-сервер позволяет создавать ресурсы с помощью запроса PUT. Следует отметить, что пользовательские методы HTTP также обрабатываются в urllib.request.Request путем установки соответствующего метода атрибут. Вот пример сеанса, в котором показано, как отправить запрос PUT с помощью http.client:

>>> # Создание сообщение 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¶

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

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

Объекты HTTPConnection¶

Объекты HTTPResponse¶

Примеры¶

Объекты HTTPMessage¶

Содержание

Предыдущий раздел

Следующий раздел

Эта страница

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

Объекты HTTPConnection¶

Объекты HTTPResponse¶

Примеры¶

Объекты HTTPMessage¶

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