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

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

Request.full_url¶

Оригинальный URL, переданный конструктору.

Request.type¶

Схема URI.

Request.host¶

Авторитетная часть URI, обычно хост, но может также содержать порт, отделённый двоеточием.

Request.origin_req_host¶

Исходный хост запроса, без порта.

Request.selector¶

Путь URI. Если Request использует прокси, то selector будет полным URL, который передаётся прокси.

Request.data¶

Тело запроса (entity body) или None, если не указано.

Request.unverifiable¶

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

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

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

Request.has_header(header)¶

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

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.5.2. Объекты OpenerDirector¶OpenerDirector Objects

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=None[, timeout])¶

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

OpenerDirector.error(proto, *args)¶

Обрабатывает ошибку указанного протокола. Вызывает зарегистрированные обработчики ошибок для данного протокола с указанными аргументами (которые зависят от протокола). Протокол 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.5.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, для открытия которых нет зарегистрированного конкретного обработчика.

Этот метод, если он реализован, вызывается родительским родительский 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.5.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-ответа «перемещён навсегда».

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(), но вызывается для ответа «temporary redirect».

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

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

HTTPCookieProcessor.cookiejar¶

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

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

ProxyHandler.protocol_open(request)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

HTTPHandler.http_open(req)¶

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

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

HTTPSHandler.https_open(req)¶

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

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

FileHandler.file_open(req)¶

Открывает файл локально, если имя хоста отсутствует или равно 'localhost'.

Изменено в версии 3.2: Этот метод применим только для локальных имен хостов. Когда указано удаленное имя хоста, возбуждается URLError.

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

FTPHandler.ftp_open(req)¶

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

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

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

CacheFTPHandler.setTimeout(t)¶

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

CacheFTPHandler.setMaxConns(m)¶

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

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

UnknownHandler.unknown_open()¶

Возбуждает исключение URLError.

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

HTTPErrorProcessor.http_response()¶

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

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

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

HTTPErrorProcessor.https_response()¶

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

Поведение такое же, как у http_response().

20.5.21. Примеры¶Examples

Этот пример получает главную страницу python.org и отображает первые 300 байт этой страницы.

>>> import urllib.request
>>> f = urllib.request.urlopen('http://www.python.org/')
>>> print(f.read(300))
b'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">\n\n\n<html
xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">\n\n<head>\n
<meta http-equiv="content-type" content="text/html; charset=utf-8" />\n
<title>Python Programming '

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

В следующем документе W3C, http://www.w3.org/International/O-charset, перечислены различные способы, которыми (X)HTML- или XML-документ мог указать информацию о своей кодировке.

Поскольку на сайте python.org используется кодировка utf-8, указанная в его мета-теге, мы будем использовать ту же самую для декодирования объекта bytes.

>>> with urllib.request.urlopen('http://www.python.org/') as f:
...     print(f.read(100).decode('utf-8'))
...
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtm

Тот же результат можно получить и без использования менеджера контекста подхода.

>>> import urllib.request
>>> f = urllib.request.urlopen('http://www.python.org/')
>>> print(f.read(100).decode('utf-8'))
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtm

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

>>> import urllib.request
>>> req = urllib.request.Request(url='https://localhost/cgi-bin/test.cgi',
...                       data=b'This data is passed to stdin of the CGI')
>>> f = urllib.request.urlopen(req)
>>> print(f.read().decode('utf-8'))
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 urllib.request
# Создать OpenerDirector с поддержкой базовой HTTP-аутентификации...
auth_handler = urllib.request.HTTPBasicAuthHandler()
auth_handler.add_password(realm='PDQ Application',
                          uri='https://mahler:8092/site-updates.py',
                          user='klem',
                          passwd='kadidd!ehopper')
opener = urllib.request.build_opener(auth_handler)
# ...и установить его глобально, чтобы его можно было использовать с urlopen.
urllib.request.install_opener(opener)
urllib.request.urlopen('http://www.example.com/login.html')

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

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

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

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

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

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

import urllib.request
req = urllib.request.Request('http://www.example.com/')
req.add_header('Referer', 'http://www.python.org/')
r = urllib.request.urlopen(req)

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

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

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

Ниже приведён пример сеанса, в котором используется метод GET для получения URL, содержащего параметры:

>>> import urllib.request
>>> import urllib.parse
>>> params = urllib.parse.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
>>> f = urllib.request.urlopen("http://www.musi-cal.com/cgi-bin/query?%s" % params)
>>> print(f.read().decode('utf-8'))

В следующем примере вместо этого используется метод POST. Обратите внимание, что вывод params из urlencode кодируется в байты перед отправкой в urlopen в качестве data:

>>> import urllib.request
>>> import urllib.parse
>>> data = urllib.parse.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
>>> data = data.encode('utf-8')
>>> request = urllib.request.Request("http://requestb.in/xrbl82xr")
>>> # добавление параметра charset в заголовок Content‑Type.
>>> request.add_header("Content-Type","application/x-www-form-urlencoded;charset=utf-8")
>>> f = urllib.request.urlopen(request, data)
>>> print(f.read().decode('utf-8'))

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

>>> import urllib.request
>>> proxies = {'http': 'http://proxy.example.com:8080/'}
>>> opener = urllib.request.FancyURLopener(proxies)
>>> f = opener.open("http://www.python.org")
>>> f.read().decode('utf-8')

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

>>> import urllib.request
>>> opener = urllib.request.FancyURLopener({})
>>> f = opener.open("http://www.python.org/")
>>> f.read().decode('utf-8')

20.5.22. Устаревший интерфейс¶Legacy interface

Следующие функции и классы перенесены из модуля Python 2 urllib (в отличие от urllib2). В будущем они могут стать устаревшими.

urllib.request.urlretrieve(url, filename=None, reporthook=None, data=None)¶

Копирует сетевой объект, заданный URL, в локальный файл, если это необходимо. Если URL указывает на локальный файл или существует валидная кешированная копия объекта, объект не копируется. Возвращает кортеж (filename, headers), где filename – это имя локального файла, в котором можно найти объект, а headers – то, что вернул метод info() объекта, возвращенного urlopen() (для удаленного объекта, возможно кешированного). Исключения те же, что и для urlopen().

Второй аргумент, если он задан, указывает, в какой файл копировать данные (если отсутствует, данные будут записаны во временный файл с автоматически сгенерированным именем). Третий аргумент, если он задан, – это функция-обработчик, которая будет вызвана один раз при установке сетевого соединения и затем после каждого прочитанного блока. Функция будет получать три аргумента: количество переданных блоков, размер блока в байтах и общий размер файла. Третий аргумент может быть -1 на старых FTP-серверах, которые не возвращают размер файла в ответ на запрос получения.

Если url использует идентификатор схемы http:, необязательный аргумент data может быть передан для указания запроса POST (обычно тип запроса – GET). Аргумент data должен быть объектом bytes в стандартном формате application/x-www-form-urlencoded; см. функцию urlencode() ниже.

urlretrieve() вызовет исключение ContentTooShortError, если обнаружит, что объём доступных данных меньше ожидаемого (то есть размера, указанного в заголовке Content-Length). Это может произойти, например, если загрузка была прервана.

Заголовок Content-Length рассматривается как нижняя граница: если есть больше данных для чтения, urlretrieve() читает больше данных, но если доступно меньше данных, он возбуждает исключение.

В этом случае загруженные данные всё ещё можно получить, они хранятся в атрибуте content экземпляра исключения.

Если заголовок Content-Length не был предоставлен, urlretrieve() не может проверить размер загруженных данных и просто возвращает их. В этом случае приходится предполагать, что загрузка прошла успешно.

urllib.request.urlcleanup()¶

Очищает кеш, который мог накопиться при предыдущих вызовах urlretrieve().

class urllib.request.URLopener(proxies=None, **x509)¶

Базовый класс для открытия и чтения URL. Если не требуется поддержка открытия объектов с использованием схем, отличных от http:, ftp: или file:, вероятно, стоит использовать FancyURLopener.

По умолчанию класс URLopener отправляет заголовок User-Agent со значением urllib/VVV, где VVV – это номер версии urllib. Приложения могут определить свой собственный заголовок User-Agent, создав подкласс URLopener или FancyURLopener и установив атрибут класса version в соответствующее строковое значение в определении подкласса.

Необязательный параметр proxies должен быть словарём, сопоставляющим имена схем с URL прокси, причём пустой словарь полностью отключает прокси. По умолчанию значение равно None; в этом случае будут использованы настройки прокси из окружения, если они присутствуют, как описано в определении urlopen() выше.

Дополнительные именованные параметры, собранные в x509, могут использоваться для аутентификации клиента при использовании схемы https:. Поддерживаются ключи key_file и cert_file для предоставления SSL-ключа и сертификата; оба необходимы для поддержки аутентификации клиента.

Объекты URLopener возбуждают исключение IOError, если сервер возвращает код ошибки.

open(fullurl, data=None)¶

Открывает fullurl, используя соответствующий протокол. Этот метод настраивает кеш и информацию о прокси, затем вызывает соответствующий метод open с его входными аргументами. Если схема не распознана, вызывается open_unknown(). Аргумент data имеет тот же смысл, что и аргумент data функции urlopen().

open_unknown(fullurl, data=None)¶

Переопределяемый интерфейс для открытия неизвестных типов URL.

retrieve(url, filename=None, reporthook=None, data=None)¶

Извлекает содержимое url и помещает его в filename. Возвращаемое значение – это кортеж, состоящий из локального имени файла и либо объекта email.message.Message, содержащего заголовки ответа (для удаленных URL), либо None (для локальных URL). Вызывающий код затем должен открыть и прочитать содержимое filename. Если filename не указан и URL ссылается на локальный файл, возвращается исходное имя файла. Если URL не локальный и filename не указан, имя файла – результат вызова tempfile.mktemp() с суффиксом, соответствующим суффиксу последнего компонента пути входного URL. Если указан reporthook, он должен быть функцией, принимающей три числовых параметра. Она будет вызываться после каждого чтения блока данных из сети. reporthook игнорируется для локальных URL.

Если url использует идентификатор схемы http:, необязательный аргумент data может быть передан для указания запроса POST (обычно тип запроса – GET). Аргумент data должен быть в стандартном формате application/x-www-form-urlencoded; см. функцию urlencode() ниже.

version¶

Переменная, задающая пользовательский агент объекта opener. Чтобы заставить urllib сообщать серверам, что он использует определённый пользовательский агент, задайте эту переменную в подклассе как переменную класса или в конструкторе перед вызовом конструктора базового класса.

class urllib.request.FancyURLopener(...)¶

FancyURLopener является подклассом URLopener, предоставляющим стандартную обработку следующих кодов ответа HTTP: 301, 302, 303, 307 и 401. Для перечисленных выше кодов 30x заголовок Location используется для получения фактического URL. Для кода 401 (требуется аутентификация) выполняется базовая HTTP-аутентификация. Для кодов 30x рекурсия ограничена значением атрибута maxtries, по умолчанию равным 10.

Для всех остальных кодов ответа вызывается метод http_error_default(), который можно переопределить в подклассах для соответствующей обработки ошибки.

Примечание

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

Параметры конструктора такие же, как и для URLopener.

Примечание

При выполнении базовой аутентификации экземпляр FancyURLopener вызывает свой метод prompt_user_passwd(). Реализация по умолчанию запрашивает у пользователя необходимые сведения на управляющем терминале. При необходимости подкласс может переопределить этот метод, чтобы обеспечить более подходящее поведение.

Класс FancyURLopener предоставляет один дополнительный метод, который следует переопределить для обеспечения соответствующего поведения:

prompt_user_passwd(host, realm)¶

Возвращает информацию, необходимую для аутентификации пользователя на указанном хосте в заданной области безопасности. Возвращаемое значение должно быть кортежем, (user, password), который можно использовать для базовой аутентификации.

Реализация запрашивает эту информацию на терминале; приложение должно переопределить этот метод, чтобы использовать подходящую модель взаимодействия в локальной среде.

20.5.23. urllib.request Ограничения¶urllib.request Restrictions

• В настоящее время поддерживаются только следующие протоколы: HTTP (версии 0.9 и 1.0), FTP и локальные файлы.

• Функция кэширования urlretrieve() отключена до тех пор, пока кто-нибудь не найдет время реализовать правильную обработку заголовков с временем истечения.

• Должна быть функция для проверки, находится ли определённый URL в кэше.

• Для обратной совместимости, если URL указывает на локальный файл, но файл не удаётся открыть, URL интерпретируется заново с использованием протокола FTP. Это иногда может приводить к запутанным сообщениям об ошибках.

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

• Данные, возвращаемые urlopen() или urlretrieve(), представляют собой необработанные данные, возвращаемые сервером. Это могут быть бинарные данные (например, изображение), обычный текст или, скажем, HTML. Протокол HTTP предоставляет информацию о типе в заголовке ответа, которую можно узнать, посмотрев на заголовок Content-Type. Если возвращаемые данные являются HTML, можно использовать модуль html.parser для его разбора.

• Код, работающий с протоколом FTP, не может различить файл и каталог. Это может привести к неожиданному поведению при попытке чтения URL, указывающего на недоступный файл. Если URL заканчивается на /, считается, что он ссылается на каталог, и обработка будет соответствующей. Но если попытка чтения файла приводит к ошибке 550 (означающей, что URL не найден или недоступен, часто по причинам прав доступа), то путь обрабатывается как каталог, чтобы учесть случай, когда в URL указан каталог, но завершающий / опущен. Это может привести к вводящим в заблуждение результатам при попытке получить файл, права на чтение которого делают его недоступным; код FTP попытается его прочитать, получит ошибку 550, а затем выполнит листинг каталога для недоступного файла. Если требуется тонкий контроль, рассмотрите возможность использования модуля ftplib, создания подкласса FancyURLopener или изменения _urlopener в соответствии с вашими потребностями.