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.

Параметры key_file и cert_file устарели, используйте ssl.SSLContext.load_cert_chain() вместо них или позвольте ssl.create_default_context() выбрать доверенные сертификаты CA вашей системы. Параметр check_hostname также устарел; вместо него следует использовать атрибут ssl.SSLContext.check_hostname объекта context.

Для получения дополнительной информации о лучших практиках ознакомьтесь с Учётом безопасности.

Изменено в версии 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.

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 в виде констант.

1. Объекты HTTPConnection

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

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

Это отправит запрос на сервер, используя метод HTTP-запроса method и селектор url.

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

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

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

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

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()

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

В качестве альтернативы использованию метода 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)

Отправить пустую строку на сервер, сигнализируя об окончании заголовков. Необязательный аргумент message_body можно использовать для передачи тела сообщения, связанного с запросом. Тело сообщения будет отправлено в том же пакете, что и заголовки сообщения, если оно является строкой, в противном случае оно отправляется в отдельном пакете.

HTTPConnection.send(data)

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

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

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

4. Объекты HTTPMessage

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