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

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

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

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

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.7.4: Этот класс теперь включает TLS 1.3 ssl.SSLContext.post_handshake_auth для контекста по умолчанию или когда 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 «Простые ответы» больше не поддерживается.

В случае необходимости могут быть подняты следующие исключения:

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, заголовок Content-Length устанавливается в значение 0 для методов, которые ожидают тела (PUT, POST и PATCH). Если body — строка или объект типа байты, который также не является файлом, заголовок Content-Length устанавливается в его длину. Любой другой тип body (файлы и итерируемые объекты в целом) будет закодирован с помощью метода фрагментации, и вместо Content-Length будет автоматически установлен заголовок Transfer-Encoding.

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

Примечание

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

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

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

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

Примечание

Из-за спецификации кодирования с помощью метода фрагментации пустые фрагменты, генерируемые итерируемым объектом тела, будут проигнорированы кодировщиком фрагментов. Это делается для того, чтобы избежать преждевременного завершения чтения запроса целевым сервером из-за неправильной кодировки.

Введено в версии 3.6: Поддержка кодирования с использованием метода фрагментации. Добавлена параметр encode_chunked.

HTTPConnection.send(data)

Отправляет данные на сервер. Этот метод следует использовать напрямую только после вызова метода endheaders() и перед вызовом метода getresponse().

Объекты 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.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 True:
...     chunk = r1.read(200)  # 200 bytes
...     if not chunk:
...          break
...     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:

>>> # 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.