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)

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

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

>>> 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 «Простые ответы» больше не поддерживаются.

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

Подкласс 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.6: key_file и cert_file устарели и заменены на context. Используйте ssl.SSLContext.load_cert_chain() вместо этого, или позвольте ssl.create_default_context() выбрать доверенные сертификаты CA системы.

Параметр 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-коды состояния.

21.12.1. Объекты 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, тело будет закодировано блоками.

Примечание

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

В версии 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()

Закрывает соединение с сервером.

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

Примечание

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

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

HTTPConnection.send(data)

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

21.12.2. Объекты 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, если поток закрыт.

21.12.3. Примеры

Вот пример сессии, использующей метод 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 not r1.closed:
...     print(r1.read(200))  # 200 bytes
b'<!doctype html>\n<!--[if"...
...
>>> # Example of an invalid request
>>> 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 путем отправки соответствующего атрибута +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

21.12.4. Объекты HTTPMessage

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