httplib — Клиент протокола HTTP

Исходный код: Lib/httplib.py

Этот модуль определяет классы, реализующие клиентскую часть протоколов HTTP и HTTPS. Обычно он не используется напрямую — модуль urllib использует его для обработки URL, использующих HTTP и HTTPS.

Модуль предоставляет следующие классы:

class httplib.HTTPConnection(host[, port[, strict[, timeout[, source_address]]]])

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

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

>>> h1 = httplib.HTTPConnection('www.cwi.nl')
>>> h2 = httplib.HTTPConnection('www.cwi.nl:80')
>>> h3 = httplib.HTTPConnection('www.cwi.nl', 80)
>>> h3 = httplib.HTTPConnection('www.cwi.nl', 80, timeout=10)

Добавлен в версии 2.0.

Изменён в версии 2.6: Добавлен параметр timeout.

Изменён в версии 2.7: Добавлен параметр source_address.

class httplib.HTTPSConnection(host[, port[, key_file[, cert_file[, strict[, timeout[, source_address[, context]]]]]]])

Подкласс HTTPConnection, использующий SSL для связи с защищёнными серверами. Порт по умолчанию — 443. Если задан параметр context, он должен быть объектом ssl.SSLContext, описывающим различные параметры SSL.

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

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

Добавлен в версии 2.0.

Изменён в версии 2.6: Добавлен параметр timeout.

Изменён в версии 2.7: Добавлен параметр source_address.

Изменён в версии 2.7.9: Добавлен параметр context.

Теперь этот класс по умолчанию выполняет все необходимые проверки сертификатов и имени хоста. Чтобы вернуться к предыдущему, не проверяющему, поведению, можно передать ssl._create_unverified_context() в параметр context.

class httplib.HTTPResponse(sock, debuglevel=0, strict=0)

Класс, объекты которого возвращаются при успешном подключении. Не создаётся пользователем напрямую.

Добавлен в версии 2.0.

class httplib.HTTPMessage

Объект HTTPMessage используется для хранения заголовков из HTTP-ответа. Он реализован с использованием класса mimetools.Message и предоставляет служебные функции для работы с HTTP-заголовками. Он не создаётся пользователем напрямую.

При возникновении соответствующих ошибок генерируются следующие исключения:

exception httplib.HTTPException

Базовый класс других исключений в этом модуле. Является подклассом Exception.

Добавлен в версии 2.0.

exception httplib.NotConnected

Подкласс HTTPException.

Добавлен в версии 2.0.

exception httplib.InvalidURL

Подкласс HTTPException, генерируется, если порт задан и является нечисловым или пустым.

Добавлен в версии 2.3.

exception httplib.UnknownProtocol

Подкласс HTTPException.

Добавлен в версии 2.0.

exception httplib.UnknownTransferEncoding

Подкласс HTTPException.

Добавлен в версии 2.0.

exception httplib.UnimplementedFileMode

Подкласс HTTPException.

Добавлен в версии 2.0.

exception httplib.IncompleteRead

Подкласс HTTPException.

Добавлен в версии 2.0.

exception httplib.ImproperConnectionState

Подкласс HTTPException.

Добавлен в версии 2.0.

exception httplib.CannotSendRequest

Подкласс ImproperConnectionState.

Добавлен в версии 2.0.

exception httplib.CannotSendHeader

Подкласс ImproperConnectionState.

Добавлен в версии 2.0.

exception httplib.ResponseNotReady

Подкласс ImproperConnectionState.

Добавлен в версии 2.0.

exception httplib.BadStatusLine

Подкласс HTTPException. Генерируется, если сервер отвечает HTTP-статусом, который нам не понятен.

Добавлен в версии 2.0.

В этом модуле определены следующие константы:

httplib.HTTP_PORT

Порт по умолчанию для протокола HTTP (всегда 80).

httplib.HTTPS_PORT

Порт по умолчанию для протокола HTTPS (всегда 443).

а также следующие константы для целочисленных кодов статуса:

httplib.responses

Этот словарь сопоставляет коды состояния HTTP 1.1 с именами W3C.

Пример: httplib.responses[httplib.NOT_FOUND] — это 'Not Found'.

Добавлена в версии 2.5.

1. Объекты HTTPConnection

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

HTTPConnection.request(method, url[, body[, headers]])

Это отправит запрос на сервер, используя HTTP-метод запроса method и селектор url. Если аргумент body присутствует, он должен быть строкой данных, которые будут отправлены после завершения заголовков. В качестве альтернативы, это может быть открытый объект файла, в котором отправляется содержимое файла; этот объект файла должен поддерживать методы fileno() и read(). Аргумент headers должен быть отображением дополнительных HTTP-заголовков для отправки с запросом.

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

Изменено в версии 2.6: body может быть объектом файла.

HTTPConnection.getresponse()

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

Примечание

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

HTTPConnection.set_debuglevel(level)

Установите уровень отладки (количество выводимых сообщений отладки). По умолчанию уровень отладки равен 0, что означает, что сообщения отладки не выводятся.

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

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

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

Добавлена в версии 2.7.

HTTPConnection.connect()

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

HTTPConnection.close()

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

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

HTTPConnection.putrequest(request, selector[, skip_host[, skip_accept_encoding]])

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

Изменено в версии 2.4: Добавлен аргумент skip_accept_encoding.

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

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

HTTPConnection.endheaders(message_body=None)

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

Изменено в версии 2.7: Добавлен message_body.

HTTPConnection.send(data)

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

2. Объекты HTTPResponse

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

HTTPResponse.read([amt])

Считывает и возвращает тело ответа или до следующих amt байтов.

HTTPResponse.getheader(name[, default])

Получить содержимое заголовка name или default, если соответствующего заголовка нет.

HTTPResponse.getheaders()

Возвращает список кортежей (заголовок, значение).

Добавлена в версии 2.4.

HTTPResponse.fileno()

Возвращает fileno основного сокета.

HTTPResponse.msg

Экземпляр mimetools.Message, содержащий заголовки ответа.

HTTPResponse.version

Версия протокола HTTP, используемая сервером. 10 для HTTP/1.0, 11 для HTTP/1.1.

HTTPResponse.status

Код состояния, возвращённый сервером.

HTTPResponse.reason

Фраза причины, возвращенная сервером.

3. Примеры

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

>>> import httplib
>>> conn = httplib.HTTPSConnection("www.python.org")
>>> conn.request("GET", "/")
>>> r1 = conn.getresponse()
>>> print r1.status, r1.reason
200 OK
>>> data1 = r1.read()
>>> conn.request("GET", "/")
>>> r2 = conn.getresponse()
>>> print r2.status, r2.reason
404 Not Found
>>> data2 = r2.read()
>>> conn.close()

Вот пример сеанса, использующего метод HEAD. Обратите внимание, что метод HEAD никогда не возвращает данные.

>>> import httplib
>>> conn = httplib.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 == ''
True

Вот пример сеанса, демонстрирующего, как выполнять POST запросы:

>>> import httplib, urllib
>>> params = urllib.urlencode({'@number': 12524, '@type': 'issue', '@action': 'show'})
>>> headers = {"Content-type": "application/x-www-form-urlencoded",
...            "Accept": "text/plain"}
>>> conn = httplib.HTTPConnection("bugs.python.org")
>>> conn.request("POST", "", params, headers)
>>> response = conn.getresponse()
>>> print response.status, response.reason
302 Found
>>> data = response.read()
>>> data
'Redirecting to <a href="http://bugs.python.org/issue12524">http://bugs.python.org/issue12524</a>'
>>> conn.close()

Клиентские HTTP PUT запросы очень похожи на POST запросы. Разница заключается только в серверной части, где HTTP-сервер позволит создавать ресурсы посредством запроса PUT. Вот пример сеанса, демонстрирующего, как выполнить запрос PUT с помощью httplib:

>>> # This creates an HTTP message
>>> # with the content of BODY as the enclosed representation
>>> # for the resource http://localhost:8080/foobar
...
>>> import httplib
>>> BODY = "***filecontents***"
>>> conn = httplib.HTTPConnection("localhost", 8080)
>>> conn.request("PUT", "/file", BODY)
>>> response = conn.getresponse()
>>> print response.status, response.reason
200, OK