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-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 устанавливается в st_size, возвращаемое вызовом 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 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(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)¶

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

HTTPConnection.send(data)¶

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

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.