20.10. http.client – клиент протокола HTTP¶http.client – HTTP protocol client

20.10.1. HTTPConnection Objects¶

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

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

Это отправляет запрос на сервер, используя метод HTTP-запроса method и селектор url. Если аргумент body присутствует, он должен быть строкой или объектом bytes с данными для отправки после завершения заголовков. Строки кодируются как ISO-8859-1, кодировка по умолчанию для HTTP. Для использования других кодировок передавайте объект bytes. Заголовок Content-Length устанавливается равным длине строки.

Аргумент body также может быть открытым файловым объектом, и в этом случае отправляется содержимое файла; этот файловый объект должен поддерживать методы fileno() и read(). Заголовок Content-Length автоматически устанавливается равным длине файла, полученной через stat. Аргумент body также может быть итерируемым объектом, и в этом случае заголовок Content-Length должен быть указан явно.

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

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

HTTPConnection.getresponse()¶

Должен вызываться после отправки запроса для получения ответа от сервера. Возвращает экземпляр HTTPResponse.

Примечание

Обратите внимание: необходимо прочитать весь ответ, прежде чем отправлять новый запрос на сервер.

HTTPConnection.set_debuglevel(level)¶

Устанавливает уровень отладки. Уровень отладки по умолчанию равен 0, то есть отладочный вывод не производится. Любое значение больше 0 приведёт к выводу всех текущих определённых отладочных сообщений в stdout. debuglevel передаётся всем новым создаваемым объектам HTTPResponse.

Новое в версии 3.1.

HTTPConnection.set_tunnel(host, port=None, headers=None)¶

Устанавливает хост и порт для HTTP-туннелирования через CONNECT. Обычно используется, когда требуется подключение HTTPS через прокси-сервер.

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

Новое в версии 3.2.

HTTPConnection.connect()¶

Подключается к серверу, указанному при создании объекта.

HTTPConnection.close()¶

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

В качестве альтернативы описанному выше методу request() можно отправлять запрос пошагово, используя четыре функции ниже.

HTTPConnection.putrequest(request, selector, skip_host=False, skip_accept_encoding=False)¶

Это должен быть первый вызов после установки соединения с сервером. Он отправляет серверу строку, состоящую из строки request, строки selector и версии HTTP (HTTP/1.1). Чтобы отключить автоматическую отправку заголовков Host: или Accept-Encoding: (например, для поддержки дополнительных кодировок содержимого), укажите skip_host или skip_accept_encoding со значениями, отличными от False.

HTTPConnection.putheader(header, argument[, ...])¶

Отправляет заголовок в стиле RFC 822 на сервер. Он отправляет строку, состоящую из заголовка, двоеточия, пробела и первого аргумента. Если заданы дополнительные аргументы, отправляются строки продолжения, каждая из которых состоит из табуляции и аргумента.

HTTPConnection.endheaders(message_body=None)¶

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

HTTPConnection.send(data)¶

Send data to the server. This should be used directly only after the endheaders() method has been called and before getresponse() is called.

20.10.2. Объекты HTTPResponse¶HTTPResponse Objects

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

HTTPResponse.read([amt])¶

Читает и возвращает тело ответа, или до следующих amt байт.

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

20.10.3. Примеры¶Examples

Ниже приведён пример сеанса, использующего метод GET:

>>> import http.client
>>> conn = http.client.HTTPConnection("www.python.org")
>>> conn.request("GET", "/index.html")
>>> r1 = conn.getresponse()
>>> print(r1.status, r1.reason)
200 OK
>>> data1 = r1.read()  # Возвращает всё содержимое.
>>> # Следующий пример демонстрирует чтение данных по частям.
>>> conn.request("GET", "/index.html")
>>> r1 = conn.getresponse()
>>> while not r1.closed:
...     print(r1.read(200)) # 200 байт
b'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"...
...
>>> # Пример некорректного запроса
>>> 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.HTTPConnection("www.python.org")
>>> conn.request("HEAD","/index.html")
>>> 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. Вот пример сеанса, показывающий, как выполнить запрос PUT с помощью http.client:

>>> # Это создаёт HTTP-сообщение.
>>> # с содержимым BODY в качестве вложенного представления
>>> # для ресурса http://localhost:8080/foobar
...
>>> import http.client
>>> BODY = "***filecontents***"
>>> conn = http.client.HTTPConnection("localhost", 8080)
>>> conn.request("PUT", "/file", BODY)
>>> response = conn.getresponse()
>>> print(resp.status, response.reason)
200, OK

20.10.4. Объекты HTTPMessage¶HTTPMessage Objects

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