urllib2 — расширяемая библиотека для открытия URL-адресов

Модуль urllib2 определяет функции и классы, которые помогают открывать URL-адреса (в основном HTTP) в сложном мире — базовая и дайджест-аутентификация, перенаправления, куки и многое другое.

Модуль urllib2 определяет следующие функции:

urllib2.urlopen(url[, data[, timeout[, cafile[, capath[, cadefault[, context]]]]])

Открывает URL-адрес url, который может быть строкой или объектом Request.

data может быть строкой, определяющей дополнительные данные для отправки серверу, или None если такие данные не нужны. В настоящее время запросы HTTP являются единственными, которые используют data; HTTP-запрос будет POST вместо GET, когда параметр data указан. data должен быть буфером в стандартном формате application/x-www-form-urlencoded. Функция urllib.urlencode() принимает отображение или последовательность пар из двух элементов и возвращает строку в этом формате. Модуль urllib2 отправляет HTTP/1.1 запросы с включенным заголовком Connection:close.

Необязательный параметр timeout задаёт таймаут в секундах для блокирующих операций, таких как попытка подключения (если не указан, используется глобальный значение таймаута по умолчанию). Это фактически работает только для соединений HTTP, HTTPS и FTP.

Если задан параметр context, он должен быть экземпляром ssl.SSLContext, описывающим различные параметры SSL. Дополнительные сведения см. в HTTPSConnection.

Необязательные параметры cafile и capath задают набор доверенных сертификатов CA для HTTPS-запросов. cafile должен указывать на один файл, содержащий набор сертификатов CA, а capath — на каталог файлов хешированных сертификатов. Более подробную информацию можно найти в ssl.SSLContext.load_verify_locations().

Параметр cadefault игнорируется.

Эта функция возвращает объект, подобный файлу, с тремя дополнительными методами:

• geturl() — возвращает URL ресурса, полученного, обычно используется для определения, было ли выполнено перенаправление
• info() — возвращает мета-информацию страницы, такую как заголовки, в виде экземпляра mimetools.Message (см. Быстрое справочное руководство по HTTP-заголовкам)
• getcode() — возвращает код HTTP-статуса ответа.

При ошибках генерирует исключение URLError.

Обратите внимание, что None может быть возвращено, если ни один обработчик не обрабатывает запрос (хотя установленный по умолчанию глобальный OpenerDirector использует UnknownHandler, чтобы гарантировать, что это никогда не произойдёт).

Кроме того, если обнаружены настройки прокси (например, при установке переменной среды *_proxy, такой как http_proxy), по умолчанию устанавливается ProxyHandler, который обеспечивает обработку запросов через прокси.

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

Изменено в версии 2.7.9: Добавлены параметры cafile, capath, cadefault и context.

urllib2.install_opener(opener)

Устанавливает экземпляр OpenerDirector в качестве глобального открывателя по умолчанию. Установка открывателя необходима только в том случае, если вы хотите, чтобы urlopen использовал этот открывателя; в противном случае просто вызовите OpenerDirector.open() вместо urlopen(). Код не проверяет наличие реального OpenerDirector, и любой класс с соответствующим интерфейсом будет работать.

urllib2.build_opener([handler, ...])

Возвращает экземпляр OpenerDirector, который объединяет обработчики в заданном порядке. handler могут быть экземплярами BaseHandler или подклассами BaseHandler (в этом случае должен быть возможен вызов конструктора без параметров). Экземпляры следующих классов будут перед handler, если только handler не содержат их, экземпляры или подклассы: ProxyHandler (если обнаружены настройки прокси), UnknownHandler, HTTPHandler, HTTPDefaultErrorHandler, HTTPRedirectHandler, FTPHandler, FileHandler, HTTPErrorProcessor.

Если в установке Python есть поддержка SSL (т. е., если модуль ssl может быть импортирован), также будет добавлен HTTPSHandler.

Начиная с Python 2.3, подкласс BaseHandler также может изменить свойство handler_order для изменения своего положения в списке обработчиков.

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

exception urllib2.URLError

Обработчики генерируют это исключение (или производные исключения) при возникновении проблемы. Это подкласс IOError.

reason

Причина ошибки. Это может быть строка сообщения или другой экземпляр исключения (socket.error для удалённых URL-адресов, OSError для локальных URL-адресов).

exception urllib2.HTTPError

Несмотря на то, что это исключение (подкласс URLError), HTTPError также может функционировать как возвращаемое значение, подобное файлу, без исключений (то же, что и возвращаемое значение urlopen()). Это полезно при обработке необычных HTTP-ошибок, например запросов для аутентификации.

code

Код HTTP-статуса, как определено в RFC 2616. Это числовое значение соответствует значению, найденному в словаре кодов, как в BaseHTTPServer.BaseHTTPRequestHandler.responses.

reason

Причина ошибки. Это может быть строка сообщения или другой экземпляр исключения.

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

class urllib2.Request(url[, data][, headers][, origin_req_host][, unverifiable])

Этот класс является абстракцией запроса к URL.

url должен быть строкой, содержащей допустимый URL.

data может быть строкой, определяющей дополнительные данные для отправки на сервер, или None если такие данные не нужны. В настоящее время запросы HTTP — единственные, использующие data; запрос HTTP будет POST, а не GET, когда параметр data предоставлен. data должен быть буфером в стандартном формате application/x-www-form-urlencoded. Функция urllib.urlencode() принимает отображение или последовательность пар 2-х элементов и возвращает строку в этом формате.

headers должен быть словарем, и будет обрабатываться так, как будто вызов add_header() был сделан с каждым ключом и значением в качестве аргументов. Это часто используется для «подмены» заголовка User-Agent, который используется браузером для идентификации себя — некоторые HTTP-серверы разрешают запросы только от распространённых браузеров, а не от скриптов. Например, Mozilla Firefox может идентифицировать себя как "Mozilla/5.0 (X11; U; Linux i686) Gecko/20071127 Firefox/2.0.0.11", в то время как строка пользователя агента по умолчанию urllib2 составляет "Python-urllib/2.6" (в Python 2.6).

Два последних аргумента интересны только для корректной обработки сторонних HTTP-куки:

origin_req_host должен быть host запроса исходной транзакции, как определено в RFC 2965. По умолчанию значение cookielib.request_host(self). Это имя хоста или IP-адрес исходного запроса, инициированного пользователем. Например, если запрос направлен на изображение в HTML-документе, то это должен быть host запроса страницы, содержащей изображение.

unverifiable должно указывать, является ли запрос недостоверным, как определено в RFC 2965. По умолчанию значение False. Недостоверный запрос — это запрос, URL которого пользователь не имел возможности подтвердить. Например, если запрос направлен на изображение в HTML-документе, и пользователь не имел возможности подтвердить автоматическую загрузку изображения, это должно быть true.

class urllib2.OpenerDirector

Класс OpenerDirector открывает URL с помощью цепочки BaseHandler. Он управляет цепочкой обработчиков и восстановлением после ошибок.

class urllib2.BaseHandler

Это базовый класс для всех зарегистрированных обработчиков — и обрабатывает только простые механизмы регистрации.

class urllib2.HTTPDefaultErrorHandler

Класс, определяющий обработчик по умолчанию для ответов HTTP с ошибками; все ответы преобразуются в исключения HTTPError.

class urllib2.HTTPRedirectHandler

Класс для обработки перенаправлений.

class urllib2.HTTPCookieProcessor([cookiejar])

Класс для обработки HTTP-куки.

class urllib2.ProxyHandler([proxies])

Принуждает запросы проходить через прокси. Если задан proxies, он должен быть словарем, сопоставляющим имена протоколов с URL-адресами прокси. По умолчанию список прокси считывается из переменных окружения <protocol>_proxy. Если переменные окружения прокси не установлены, в среде Windows настройки прокси получаются из раздела Настройки интернета реестра, а в среде Mac OS X информация о прокси извлекается из фреймворка конфигурации системы OS X.

Чтобы отключить автоматическое обнаружение прокси, передайте пустой словарь.

Примечание

HTTP_PROXY будет проигнорирован, если установлена переменная REQUEST_METHOD; см. документацию по getproxies().

class urllib2.HTTPPasswordMgr

Сохраняет базу данных соответствий (realm, uri) -> (user, password).

class urllib2.HTTPPasswordMgrWithDefaultRealm

Сохраняет базу данных соответствий (realm, uri) -> (user, password). Сфера None рассматривается как универсальная, которая проверяется, если не подходит ни одна другая сфера.

class urllib2.AbstractBasicAuthHandler([password_mgr])

Это миксин-класс, который помогает с аутентификацией HTTP, как к удалённому хосту, так и к прокси. password_mgr, если задан, должен быть совместим с HTTPPasswordMgr; для получения информации об интерфейсе, который необходимо поддерживать, см. раздел HTTPPasswordMgr Objects.

class urllib2.HTTPBasicAuthHandler([password_mgr])

Обрабатывает аутентификацию с удалённым хостом. password_mgr, если задан, должен быть совместим с HTTPPasswordMgr; для получения информации об интерфейсе, который необходимо поддерживать, см. раздел HTTPPasswordMgr Objects.

class urllib2.ProxyBasicAuthHandler([password_mgr])

Обрабатывает аутентификацию с прокси. password_mgr, если задан, должен быть совместим с HTTPPasswordMgr; для получения информации об интерфейсе, который необходимо поддерживать, см. раздел HTTPPasswordMgr Objects.

class urllib2.AbstractDigestAuthHandler([password_mgr])

Это миксин-класс, который помогает с аутентификацией HTTP, как к удалённому хосту, так и к прокси. password_mgr, если задан, должен быть совместим с HTTPPasswordMgr; для получения информации об интерфейсе, который необходимо поддерживать, см. раздел HTTPPasswordMgr Objects.

class urllib2.HTTPDigestAuthHandler([password_mgr])

Обрабатывает аутентификацию с удалённым хостом. password_mgr, если задан, должен быть совместим с HTTPPasswordMgr; для получения информации об интерфейсе, который необходимо поддерживать, см. раздел HTTPPasswordMgr Objects.

class urllib2.ProxyDigestAuthHandler([password_mgr])

Обрабатывает аутентификацию с прокси. password_mgr, если задан, должен быть совместим с HTTPPasswordMgr; для получения информации об интерфейсе, который необходимо поддерживать, см. раздел HTTPPasswordMgr Objects.

class urllib2.HTTPHandler

Класс для обработки открытия HTTP-URL.

class urllib2.HTTPSHandler([debuglevel[, context]])

Класс для обработки открытия HTTPS-URL. context имеет то же значение, что и для httplib.HTTPSConnection.

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

class urllib2.FileHandler

Открывает локальные файлы.

class urllib2.FTPHandler

Открывает FTP-URL.

class urllib2.CacheFTPHandler

Открывает FTP-URL, сохраняя кэш открытых FTP-соединений для минимизации задержек.

class urllib2.UnknownHandler

Универсальный класс для обработки неизвестных URL.

class urllib2.HTTPErrorProcessor

Обрабатывает HTTP-отклики с ошибками.

1. Объекты запросов

Следующие методы описывают весь публичный интерфейс 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 заменят значения экземпляра, а селектор экземпляра будет исходным URL, указанным в конструкторе.

Request.get_origin_req_host()

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

Request.is_unverifiable()

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

2. Объекты OpenerDirector

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

OpenerDirector.add_handler(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[, arg[, ...]])

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

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

Объекты OpenerDirector открывают URL-адреса в трех этапах:

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

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

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

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

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

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

3. Объекты BaseHandler

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 — объектом типа «поток» (file-like object) с телом 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().

4. Объекты HTTPRedirectHandler

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

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

Примечание

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

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

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

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

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

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

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

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

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

5. Объекты HTTPCookieProcessor

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

HTTPCookieProcessor.cookiejar

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

6. Объекты ProxyHandler

ProxyHandler.protocol_open(request)

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

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

7. Объекты HTTPPasswordMgr

Эти методы доступны для объектов 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 будет просмотрен realm None, если у заданного realm нет соответствующего имени пользователя/пароля.

8. Объекты AbstractBasicAuthHandler

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

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

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

9. Объекты HTTPBasicAuthHandler

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

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

10. Объекты ProxyBasicAuthHandler

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

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

11. Объекты AbstractDigestAuthHandler

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

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

12. Объекты HTTPDigestAuthHandler

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

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

13. Объекты ProxyDigestAuthHandler

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

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

14. Объекты HTTPHandler

HTTPHandler.http_open(req)

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

15. Объекты HTTPSHandler

HTTPSHandler.https_open(req)

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

16. Объекты FileHandler

FileHandler.file_open(req)

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

17. Объекты FTPHandler

FTPHandler.ftp_open(req)

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

18. Объекты CacheFTPHandler

CacheFTPHandler — это объекты FTPHandler с дополнительными методами:

CacheFTPHandler.setTimeout(t)

Установить таймаут подключений на t секунд.

CacheFTPHandler.setMaxConns(m)

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

19. Объекты UnknownHandler

UnknownHandler.unknown_open()

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

20. Объекты HTTPErrorProcessor

HTTPErrorProcessor.http_response()

Обработать HTTP-ответы об ошибках.

Для кодов ошибок 200 объект ответа возвращается сразу.

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

HTTPErrorProcessor.https_response()

Обработать HTTPS-ответы об ошибках.

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

21. Примеры

Помимо примеров ниже, дополнительные примеры приведены в 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 и считываем возвращаемые данные. Обратите внимание, что этот пример будет работать только в том случае, если установка Python поддерживает SSL.

>>> 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

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

import urllib2
# Create an OpenerDirector with support for Basic HTTP Authentication...
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)
# ...and install it globally so it can be used with 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)
# This time, rather than install the OpenerDirector, we use it directly:
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/')
# Customize the default User-Agent header value:
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()).