20.6. urllib2 – расширяемая библиотека для открытия URL-адресов¶urllib2 – extensible library for opening URLs

20.6.1. Объекты Request¶Request Objects

Следующие методы описывают весь открытый интерфейс Request, и поэтому все они должны быть переопределены в подклассах.

Request.add_data(data)¶

Устанавливает данные Request в data. Этот параметр игнорируется всеми обработчиками, кроме HTTP-обработчиков, – там он должен быть байтовой строкой и изменит запрос на POST вместо GET.

Request.get_method()¶

Возвращает строку, указывающую метод HTTP-запроса. Это имеет смысл только для HTTP-запросов и в настоящее время всегда возвращает 'GET' или 'POST'.

Request.has_data()¶

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

Request.get_data()¶

Возвращает данные экземпляра.

Request.add_header(key, val)¶

Добавляет ещё один заголовок к запросу. В настоящее время заголовки игнорируются всеми обработчиками, кроме HTTP-обработчиков, где они добавляются в список заголовков, отправляемых серверу. Обратите внимание, что не может быть более одного заголовка с одним и тем же именем, и последующие вызовы перезапишут предыдущие в случае совпадения ключа. В настоящее время это не приводит к потере функциональности HTTP, поскольку все заголовки, имеющие смысл при многократном использовании, имеют (специфичный для заголовка) способ достижения той же функциональности с помощью только одного заголовка.

Request.add_unredirected_header(key, header)¶

Добавляет заголовок, который не будет добавлен в перенаправленный запрос.

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

Request.has_header(header)¶

Возвращает, имеет ли экземпляр указанный заголовок (проверяет как обычные, так и неперенаправленные).

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

Request.get_full_url()¶

Возвращает URL, переданный в конструктор.

Request.get_type()¶

Возвращает тип URL – также известный как схема.

Request.get_host()¶

Возвращает хост, к которому будет установлено соединение.

Request.get_selector()¶

Возвращает селектор – часть URL, которая отправляется серверу.

Request.get_header(header_name, default=None)¶

Возвращает значение указанного заголовка. Если заголовок отсутствует, возвращает значение по умолчанию.

Request.header_items()¶

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

Request.set_proxy(host, type)¶

Подготавливает запрос, подключаясь к прокси-серверу. host и type заменят соответствующие значения экземпляра, а selector экземпляра будет содержать исходный URL, переданный в конструктор.

Request.get_origin_req_host()¶

Возвращает хост запроса исходной транзакции, как определено в RFC 2965. См. документацию конструктора Request.

Request.is_unverifiable()¶

Возвращает, является ли запрос непроверяемым, как определено в RFC 2965. См. документацию конструктора Request.

20.6.2. Объекты OpenerDirector¶OpenerDirector Objects

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

OpenerDirector.add_handler(handler)¶

Обработчик должен быть экземпляром BaseHandler. Выполняется поиск следующих методов, и они добавляются в возможные цепочки (обратите внимание, что HTTP-ошибки являются особым случаем).

• protocol_open – сигнализирует, что обработчик умеет открывать URL протокола протокол.

• http_error_type – сигнализирует, что обработчик умеет обрабатывать HTTP-ошибки с кодом HTTP type.

• protocol_error – сигнализирует, что обработчик умеет обрабатывать ошибки от протокол (кроме http).

• protocol_request – сигнализирует, что обработчик умеет предварительно обрабатывать запросы протокол.

• protocol_response – сигнал о том, что обработчик умеет постобрабатывать ответы протокол.

OpenerDirector.open(url[, data][, timeout])¶

Открывает указанный url (может быть объектом запроса или строкой), опционально передавая указанные data. Аргументы, возвращаемые значения и исключения такие же, как у urlopen() (которая просто вызывает метод open() на текущем установленном глобальном OpenerDirector). Необязательный параметр timeout задаёт тайм-аут в секундах для блокирующих операций, таких как попытка соединения (если не указан, будет использоваться глобальная настройка тайм-аута по умолчанию). Функция тайм-аута фактически работает только для соединений HTTP, HTTPS и FTP.

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

OpenerDirector.error(proto, argarg, [...]])¶

Обрабатывает ошибку указанного протокола. Вызывает зарегистрированные обработчики ошибок для данного протокола с указанными аргументами (зависящими от протокола). Протокол HTTP является особым случаем: для определения конкретного обработчика ошибок используется код ответа HTTP; обратитесь к методам http_error_*() классов обработчиков.

Возвращаемые значения и вызываемые исключения такие же, как у urlopen().

Объекты OpenerDirector открывают URL в три этапа:

Порядок вызова этих методов в каждом этапе определяется сортировкой экземпляров обработчиков.

1. Каждый обработчик, имеющий метод с именем protocol_request, вызывает этот метод для предварительной обработки запроса.

2. Обработчики с методом с именем вида protocol_open вызываются для обработки запроса. Этот этап завершается, когда обработчик возвращает не-None значение (т.е. ответ) или возбуждает исключение (обычно URLError). Исключения могут распространяться.

   На самом деле, описанный выше алгоритм сначала применяется к методам с именем default_open(). Если все такие методы возвращают None, алгоритм повторяется для методов с именем вида protocol_open. Если все такие методы возвращают None, алгоритм повторяется для методов с именем unknown_open().

   Обратите внимание, что реализация этих методов может включать вызовы методов open() и error() родительского экземпляра OpenerDirector.

3. Каждый обработчик, имеющий метод с именем protocol_response, вызывает этот метод для постобработки ответа.

20.6.3. Объекты BaseHandler¶BaseHandler Objects

Объекты BaseHandler предоставляют несколько методов, которые непосредственно полезны, а также другие методы, предназначенные для использования производными классами. Они предназначены для прямого использования:

BaseHandler.add_parent(director)¶

Добавляет директор в качестве родителя.

BaseHandler.close()¶

Удаляет всех родителей.

Следующие атрибуты и методы должны использоваться только классами, унаследованными от BaseHandler.

BaseHandler.parent¶

Действительный OpenerDirector, который можно использовать для открытия через другой протокол или для обработки ошибок.

BaseHandler.default_open(req)¶

Этот метод не определён в BaseHandler, но подклассы должны определить его, если хотят перехватывать все URL.

Этот метод, если он реализован, будет вызван родительским OpenerDirector. Он должен возвращать файлоподобный объект, как описано в возвращаемом значении open() из OpenerDirector, или None. Он должен возбуждать URLError, если только не произошло действительно исключительной ситуации (например, MemoryError не должно преобразовываться в URLError).

Этот метод будет вызван перед любым методом открытия, специфичным для протокола.

BaseHandler.protocol_open(req)

(«протокол» следует заменить на имя протокола.)

Этот метод не определён в BaseHandler, но подклассы должны определить его, если они хотят обрабатывать URL-адреса с указанным протоколом.

Если этот метод определён, он будет вызван родительским OpenerDirector. Возвращаемые значения должны быть такими же, как для default_open().

BaseHandler.unknown_open(req)¶

Этот метод не определён в BaseHandler, но подклассы должны определить его, если хотят перехватывать все URL, для которых нет зарегистрированного обработчика для открытия.

Если этот метод реализован, он будет вызван parent OpenerDirector. Возвращаемые значения должны быть такими же, как для default_open().

BaseHandler.http_error_default(req, fp, code, msg, hdrs)¶

Этот метод не определён в BaseHandler, но подклассы должны переопределить его, если они намерены обеспечить всеобъемлющую обработку для иначе необработанных HTTP-ошибок. Он будет автоматически вызван OpenerDirector при получении ошибки и обычно не должен вызываться в других обстоятельствах.

req будет объектом Request, fp будет файлоподобным объектом с телом HTTP-ошибки, code будет трёхзначным кодом ошибки, msg будет видимым пользователю пояснением кода, а hdrs будет объектом отображения, содержащим заголовки ошибки.

Возвращаемые значения и вызываемые исключения должны быть такими же, как у urlopen().

BaseHandler.http_error_nnn(req, fp, code, msg, hdrs)¶

nnn должен быть трёхзначным HTTP-кодом ошибки. Этот метод также не определён в BaseHandler, но будет вызван, если он существует, на экземпляре подкласса, когда возникает HTTP-ошибка с кодом nnn.

Подклассы должны переопределить этот метод для обработки конкретных HTTP-ошибок.

Аргументы, возвращаемые значения и вызываемые исключения должны быть такими же, как для http_error_default().

BaseHandler.protocol_request(req)

(«протокол» следует заменить на имя протокола.)

Этот метод не определён в BaseHandler, но подклассы должны определить его, если они хотят предварительно обрабатывать запросы указанного протокола.

Если этот метод определён, он будет вызван родительским OpenerDirector. req будет объектом Request. Возвращаемое значение должно быть объектом Request.

BaseHandler.protocol_response(req, response)

(«протокол» следует заменить на имя протокола.)

Этот метод не определён в BaseHandler, но подклассы должны определить его, если они хотят выполнять постобработку ответов указанного протокола.

Этот метод, если он определён, будет вызван родительским OpenerDirector. req будет объектом Request. response будет объектом, реализующим тот же интерфейс, что и возвращаемое значение urlopen(). Возвращаемое значение должно реализовывать тот же интерфейс, что и возвращаемое значение urlopen().

20.6.4. Объекты HTTPRedirectHandler¶HTTPRedirectHandler Objects

HTTPRedirectHandler.redirect_request(req, fp, code, msg, hdrs, newurl)¶

Возвращает Request или None в ответ на перенаправление. Этот метод вызывается реализациями по умолчанию методов http_error_30*(), когда от сервера получено перенаправление. Если перенаправление должно произойти, верните новый Request, чтобы позволить http_error_30*() выполнить перенаправление на newurl. В противном случае возбудите HTTPError, если никакой другой обработчик не должен пытаться обработать этот URL, или верните None, если вы не можете, но другой обработчик может.

Примечание

Реализация по умолчанию этого метода не следует строго RFC 2616, который говорит, что ответы 301 и 302 на запросы POST не должны автоматически перенаправляться без подтверждения пользователем. В действительности браузеры разрешают автоматическое перенаправление таких ответов, меняя POST на GET, и реализация по умолчанию воспроизводит такое поведение.

HTTPRedirectHandler.http_error_301(req, fp, code, msg, hdrs)¶

Перенаправляет на URL Location: или URI:. Этот метод вызывается родительским OpenerDirector при получении HTTP-ответа «Moved Permanently».

HTTPRedirectHandler.http_error_302(req, fp, code, msg, hdrs)¶

То же, что и http_error_301(), но вызывается для ответа «Found».

HTTPRedirectHandler.http_error_303(req, fp, code, msg, hdrs)¶

То же, что и http_error_301(), но вызывается для ответа «See Other».

HTTPRedirectHandler.http_error_307(req, fp, code, msg, hdrs)¶

То же, что и http_error_301(), но вызывается для ответа «временное перенаправление».

20.6.5. Объекты HTTPCookieProcessor¶HTTPCookieProcessor Objects

Экземпляры HTTPCookieProcessor имеют один атрибут:

HTTPCookieProcessor.cookiejar¶

cookielib.CookieJar, в котором хранятся куки.

20.6.6. Объекты ProxyHandler¶ProxyHandler Objects

ProxyHandler.protocol_open(request)

(«протокол» следует заменить на имя протокола.)

Объект ProxyHandler будет иметь метод protocol_open для каждого протокол, для которого есть прокси в словаре proxies, переданном в конструктор. Метод будет изменять запросы для прохождения через прокси, вызывая request.set_proxy(), и вызывать следующий обработчик в цепочке для непосредственного выполнения протокола.

20.6.7. Объекты HTTPPasswordMgr¶HTTPPasswordMgr Objects

Эти методы доступны у объектов HTTPPasswordMgr и HTTPPasswordMgrWithDefaultRealm.

HTTPPasswordMgr.add_password(realm, uri, user, passwd)¶

uri может быть как одним URI, так и последовательностью URI. realm, user и passwd должны быть строками. В результате (user, passwd) будет использоваться в качестве токенов аутентификации, когда запрашивается аутентификация для realm и супер-URI любого из заданных URI.

HTTPPasswordMgr.find_user_password(realm, authuri)¶

Получает имя пользователя/пароль для заданных realm и URI, если они есть. Этот метод вернёт (None, None), если нет соответствующей пары пользователь/пароль.

Для объектов HTTPPasswordMgrWithDefaultRealm область None будет проверена, если заданная realm не имеет соответствующей пары пользователь/пароль.

20.6.8. Объекты AbstractBasicAuthHandler¶AbstractBasicAuthHandler Objects

AbstractBasicAuthHandler.http_error_auth_reqed(authreq, host, req, headers)¶

Обрабатывает запрос аутентификации, получая пару пользователь/пароль и повторяя запрос. authreq должен быть именем заголовка, в котором содержится информация о realm в запросе, host указывает URL и путь для аутентификации, req должен быть (неудачным) объектом Request, а headers – заголовками ошибки.

host – это либо authority (например, "python.org"), либо URL, содержащий компонент authority (например, "http://python.org/"). В любом случае, authority не должен содержать компонент userinfo (поэтому "python.org" и "python.org:80" подходят, а "joe:password@python.org" – нет).

20.6.9. Объекты HTTPBasicAuthHandler¶HTTPBasicAuthHandler Objects

HTTPBasicAuthHandler.http_error_401(req, fp, code, msg, hdrs)¶

Повторяет запрос с информацией аутентификации, если она доступна.

20.6.10. Объекты ProxyBasicAuthHandler¶ProxyBasicAuthHandler Objects

ProxyBasicAuthHandler.http_error_407(req, fp, code, msg, hdrs)¶

Повторяет запрос с информацией аутентификации, если она доступна.

20.6.11. Объекты AbstractDigestAuthHandler¶AbstractDigestAuthHandler Objects

AbstractDigestAuthHandler.http_error_auth_reqed(authreq, host, req, headers)¶

authreq должен быть именем заголовка, в котором содержится информация о realm в запросе, host должен быть хостом для аутентификации, req должен быть (неудачным) объектом Request, а headers – заголовками ошибки.

20.6.12. Объекты HTTPDigestAuthHandler¶HTTPDigestAuthHandler Objects

HTTPDigestAuthHandler.http_error_401(req, fp, code, msg, hdrs)¶

Повторяет запрос с информацией аутентификации, если она доступна.

20.6.13. Объекты ProxyDigestAuthHandler¶ProxyDigestAuthHandler Objects

ProxyDigestAuthHandler.http_error_407(req, fp, code, msg, hdrs)¶

Повторяет запрос с информацией аутентификации, если она доступна.

20.6.14. Объекты HTTPHandler¶HTTPHandler Objects

HTTPHandler.http_open(req)¶

Отправляет HTTP-запрос, который может быть GET или POST, в зависимости от req.has_data().

20.6.15. Объекты HTTPSHandler¶HTTPSHandler Objects

HTTPSHandler.https_open(req)¶

Отправляет HTTPS-запрос, который может быть GET или POST, в зависимости от req.has_data().

20.6.16. Объекты FileHandler¶FileHandler Objects

FileHandler.file_open(req)¶

Если имя хоста не указано или имя хоста равно 'localhost', файл открывается локально. В противном случае протокол меняется на ftp, и открытие повторяется с помощью parent.

20.6.17. Объекты FTPHandler¶FTPHandler Objects

FTPHandler.ftp_open(req)¶

Открывает FTP-файл, указанный req. Вход всегда выполняется с пустыми именем пользователя и паролем.

20.6.18. Объекты CacheFTPHandler¶CacheFTPHandler Objects

Объекты CacheFTPHandler являются объектами FTPHandler со следующими дополнительными методами:

CacheFTPHandler.setTimeout(t)¶

Устанавливает тайм-аут соединений равным t секунд.

CacheFTPHandler.setMaxConns(m)¶

Устанавливает максимальное количество кэшированных соединений равным m.

20.6.19. Объекты UnknownHandler¶UnknownHandler Objects

UnknownHandler.unknown_open()¶

Вызывает исключение URLError.

20.6.20. Объекты HTTPErrorProcessor¶HTTPErrorProcessor Objects

HTTPErrorProcessor.http_response()¶

Обрабатывает ошибочные HTTP-ответы.

Для кода 200 объект ответа возвращается немедленно.

Для кодов ошибок, отличных от 200, задача просто передаётся методам-обработчикам protocol_error_code через OpenerDirector.error(). В конечном итоге urllib2.HTTPDefaultErrorHandler возбудит HTTPError, если ни один другой обработчик не обработает ошибку.

HTTPErrorProcessor.https_response()¶

Обрабатывает ошибочные HTTPS-ответы.

Поведение аналогично http_response().

20.6.21. Примеры¶Examples

В дополнение к приведённым ниже примерам, больше примеров приведено в HOWTO Fetch Internet Resources Using urllib2.

В этом примере загружается главная страница python.org и выводятся первые 100 байт её содержимого:

>>> import urllib2
>>> f = urllib2.urlopen('http://www.python.org/')
>>> print f.read(100)
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<?xml-stylesheet href="./css/ht2html

Здесь мы отправляем поток данных на stdin CGI и читаем данные, которые он возвращает. Обратите внимание: этот пример работает только при наличии поддержки SSL в установке Python.

>>> import urllib2
>>> req = urllib2.Request(url='https://localhost/cgi-bin/test.cgi',
...                       data='This data is passed to stdin of the CGI')
>>> f = urllib2.urlopen(req)
>>> print f.read()
Got Data: "This data is passed to stdin of the CGI"

Код образца CGI, использованного в приведённом выше примере:

#!/usr/bin/env python
import sys
data = sys.stdin.read()
print 'Content-type: text-plain\n\nGot Data: "%s"' % data

Использование базовой HTTP-аутентификации:

import urllib2
# Создать OpenerDirector с поддержкой базовой HTTP-аутентификации...
auth_handler = urllib2.HTTPBasicAuthHandler()
auth_handler.add_password(realm='PDQ Application',
                          uri='https://mahler:8092/site-updates.py',
                          user='klem',
                          passwd='kadidd!ehopper')
opener = urllib2.build_opener(auth_handler)
# ...и установить его глобально, чтобы его можно было использовать с urlopen.
urllib2.install_opener(opener)
urllib2.urlopen('http://www.example.com/login.html')

build_opener() предоставляет множество обработчиков по умолчанию, включая ProxyHandler. По умолчанию ProxyHandler использует переменные окружения с именами <scheme>_proxy, где <scheme> – это схема URL. Например, переменная окружения http_proxy читается для получения URL HTTP-прокси.

В этом примере стандартный ProxyHandler заменяется на тот, который использует программно заданные URL прокси, а также добавляется поддержка авторизации прокси с помощью ProxyBasicAuthHandler.

proxy_handler = urllib2.ProxyHandler({'http': 'http://www.example.com:3128/'})
proxy_auth_handler = urllib2.ProxyBasicAuthHandler()
proxy_auth_handler.add_password('realm', 'host', 'username', 'password')

opener = urllib2.build_opener(proxy_handler, proxy_auth_handler)
# На этот раз, вместо установки OpenerDirector, используется напрямую:
opener.open('http://www.example.com/login.html')

Добавление HTTP-заголовков:

Используйте аргумент headers конструктора Request или:

import urllib2
req = urllib2.Request('http://www.example.com/')
req.add_header('Referer', 'http://www.python.org/')
# Настроить значение заголовка User-Agent по умолчанию:
req.add_header('User-Agent', 'urllib-example/0.1 (Contact: . . .)')
r = urllib2.urlopen(req)

OpenerDirector автоматически добавляет заголовок User-Agent к каждому запросу Request. Чтобы изменить это:

import urllib2
opener = urllib2.build_opener()
opener.addheaders = [('User-agent', 'Mozilla/5.0')]
opener.open('http://www.example.com/')

Также помните, что несколько стандартных заголовков (Content-Length, Content-Type и Host) добавляются, когда Request передаётся в urlopen() (или OpenerDirector.open()).