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

21.12.1. Объекты HTTPConnection¶HTTPConnection Objects

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

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

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

Если указан body, указанные данные отправляются после завершения заголовков. Он может быть строкой, байтоподобным объектом, открытым файловым объектом или итерируемым объектом из байтоподобных объектов. Если body – строка, она кодируется как ISO-8851-1, кодировка по умолчанию для HTTP. Если это байтоподобный объект, байты отправляются как есть. Если это файловый объект, отправляется содержимое файла; этот файловый объект должен поддерживать как минимум метод read(). Если у файлового объекта есть атрибут mode, данные, возвращаемые методом read(), будут закодированы как ISO-8851-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 устанавливается равным st_size, возвращаемому вызовом fstat. В противном случае заголовок Content-Length не добавляется.

Новое в версии 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 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()¶

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

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.

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

Экземпляр 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. Примеры¶Examples

Ниже приведён пример сеанса, использующего метод 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()  # Возвращает всё содержимое.
>>> # Следующий пример демонстрирует чтение данных по частям.
>>> conn.request("GET", "/")
>>> r1 = conn.getresponse()
>>> while not r1.closed:
...     print(r1.read(200)) # 200 байт
b'<!doctype html>\n<!--[if"...
...
>>> # Пример некорректного запроса
>>> 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:

>>> # Это создаёт HTTP-сообщение.
>>> # с содержимым BODY в качестве вложенного представления
>>> # для ресурса 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¶HTTPMessage Objects

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