http.client
— Клиент протокола HTTP¶
Исходный код: Lib/http/client.py.
Этот модуль определяет классы, которые реализуют клиентскую часть протоколов HTTP и HTTPS. Обычно он не используется напрямую — модуль urllib.request
использует его для обработки URL, использующих HTTP и HTTPS.
См.также
Requests package рекомендуется для клиентского интерфейса 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: Был добавлен адрес_источника.
Изменено в версии 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
true).Изменено в версии 3.4: Параметр strict был удален. «Простые ответы» в стиле HTTP 0.9 больше не поддерживаются.
Изменено в версии 3.4.3: Теперь этот класс по умолчанию выполняет все необходимые проверки сертификата и имени хоста. Для возврата к предыдущему, непроверенному, поведению
ssl._create_unverified_context()
можно передать параметр context.Изменено в версии 3.8: Этот класс теперь позволяет использовать TLS 1.3
ssl.SSLContext.post_handshake_auth
для контекста по умолчанию или когда cert_file передается с пользовательским контекстом.Изменено в версии 3.10: Этот класс теперь отправляет расширение ALPN с индикатором протокола
http/1.1
, когда не задан контекст. Пользовательский контекст должен устанавливать протоколы ALPN с индикатором протоколаset_alpn_protocol()
.Не рекомендуется, начиная с версии 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-like object, открытый file object или итерабельностьbytes
. Если body является строкой, то она кодируется как ISO-8859-1, по умолчанию для HTTP. Если это байтоподобный объект, то байты отправляются как есть. Если это file object, отправляется содержимое файла; этот объект файла должен поддерживать, по крайней мере, методread()
. Если объект файла является экземпляромio.TextIOBase
, данные, возвращаемые методомread()
, будут закодированы как ISO-8859-1, иначе данные, возвращаемые методомread()
, будут отправлены как есть. Если body является итерабельным, то элементы итерабельного файла отправляются как есть до тех пор, пока итерабельный файл не будет исчерпан.Аргумент headers должен представлять собой отображение дополнительных HTTP-заголовков для отправки вместе с запросом.
Если headers не содержит ни Content-Length, ни Transfer-Encoding, но есть тело запроса, одно из этих полей заголовка будет добавлено автоматически. Если body имеет значение
None
, заголовок Content-Length устанавливается в значение0
для методов, которые ожидают тело (PUT
,POST
иPATCH
). Если body является строкой или байтоподобным объектом, который также не является file, заголовок Content-Length устанавливается на его длину. Любой другой тип body (файлы и итерабельные объекты в целом) будет закодирован в виде кусков, и вместо Content-Length автоматически будет установлен заголовок Transfer-Encoding.Аргумент encode_chunked имеет значение, только если Transfer-Encoding указан в headers. Если encode_chunked имеет значение
False
, объект HTTPConnection предполагает, что все кодирование обрабатывается вызывающим кодом. Если значениеTrue
, тело будет закодировано по частям.Примечание
В протокол HTTP версии 1.1 было добавлено кодирование передачи Chunked. Если не известно, что HTTP-сервер поддерживает HTTP 1.1, вызывающая сторона должна либо указать Content-Length, либо передать
str
или байтоподобный объект, не являющийся файлом, в качестве представления тела.Добавлено в версии 3.2: Теперь body может быть итерабельным.
Изменено в версии 3.6: Если в заголовках не заданы ни Content-Length, ни Transfer-Encoding, объекты file и iterable body теперь кодируются по частям. Был добавлен аргумент 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
()¶ Подключение к серверу, указанному при создании объекта. По умолчанию это вызывается автоматически при выполнении запроса, если у клиента еще нет соединения.
Вызывает auditing event
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 реализует buffer interface, то в результате кодирования будет получен один чанк. Если message_body являетсяcollections.abc.Iterable
, то каждая итерация message_body приведет к появлению чанка. Если message_body является file object, то каждый вызов.read()
приведет к появлению чанка. Метод автоматически сигнализирует о конце закодированных в чанк данных сразу после message_body.Примечание
В связи со спецификацией кодировки chunked, пустые куски, выдаваемые телом итератора, будут игнорироваться chunk-encoder’ом. Это делается для того, чтобы избежать преждевременного завершения чтения запроса целевым сервером из-за неправильного кодирования.
Добавлено в версии 3.6: Поддержка кодирования в виде кусков. Был добавлен параметр encode_chunked.
-
HTTPConnection.
send
(data)¶ Отправить данные на сервер. Этот метод следует использовать непосредственно только после вызова метода
endheaders()
и до вызоваgetresponse()
.Вызывает auditing event
http.client.send
с аргументамиself
,data
.
Объекты HTTPResponse¶
Экземпляр HTTPResponse
оборачивает ответ HTTP от сервера. Он предоставляет доступ к заголовкам запроса и телу сущности. Ответ является итерируемым объектом и может быть использован в операторе with.
Изменено в версии 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, возвращаются все значения, объединенные символами „, „. Если „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
, если поток закрыт.
Примеры¶
Вот пример сессии, в которой используется метод 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
путем установки соответствующего атрибута method. Вот пример сессии, показывающий, как отправить PUT
запрос, используя http.client:
>>> # This creates an HTTP message
>>> # 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
.