21.6.1. Объекты запросов¶Request Objects

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

Request.full_url¶

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

Изменено в версии 3.4.

Request.full_url – это свойство с сеттером, геттером и делитером. При получении full_url возвращает оригинальный URL запроса вместе с фрагментом, если он присутствовал.

Request.type¶

Схема URI.

Request.host¶

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

Request.origin_req_host¶

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

Request.selector¶

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

Request.data¶

Тело сущности запроса или None, если не задано.

Изменено в версии 3.4: Изменение значения Request.data теперь удаляет заголовок “Content-Length” , если он был ранее установлен или вычислен.

Request.unverifiable¶

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

Request.method¶

HTTP-метод запроса. По умолчанию его значение равно None, что означает, что get_method() выполнит обычное вычисление метода. Значение можно задать (тем самым переопределив вычисление по умолчанию в get_method()), либо установив значение по умолчанию на уровне класса в подклассе Request, либо передав значение в конструктор Request через аргумент method.

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

Изменено в версии 3.4: Теперь значение по умолчанию можно задавать в подклассах; ранее его можно было установить только через аргумент конструктора.

Request.get_method()¶

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

Изменено в версии 3.3: get_method теперь учитывает значение Request.method.

Request.add_header(key, val)¶

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

Request.add_unredirected_header(key, header)¶

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

Request.has_header(header)¶

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

Request.remove_header(header)¶

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

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

Request.get_full_url()¶

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

Изменено в версии 3.4.

Возвращает Request.full_url

Request.set_proxy(host, type)¶

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

Request.get_header(header_name, default=None)¶

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

Request.header_items()¶

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

21.6.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(), вызывает этот метод для постобработки ответа.

21.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().

21.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(), но вызывается для ответа «временное перенаправление».

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

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

HTTPCookieProcessor.cookiejar¶

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

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

ProxyHandler.protocol_open(request)

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

21.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 не имеет соответствующей пары пользователь/пароль.

21.6.8. Объекты HTTPPasswordMgrWithPriorAuth¶HTTPPasswordMgrWithPriorAuth Objects

Этот менеджер паролей расширяет HTTPPasswordMgrWithDefaultRealm, чтобы поддерживать отслеживание URI, для которых учётные данные аутентификации должны всегда отправляться.

HTTPPasswordMgrWithPriorAuth.add_password(realm, uri, user, passwd, is_authenticated=False)¶

realm, uri, user, passwd – как и для HTTPPasswordMgr.add_password(). is_authenticated устанавливает начальное значение флага is_authenticated для указанного URI или списка URI. Если is_authenticated указан как True, realm игнорируется.

HTTPPasswordMgr.find_user_password(realm, authuri)

То же, что и для объектов HTTPPasswordMgrWithDefaultRealm

HTTPPasswordMgrWithPriorAuth.update_authenticated(self, uri, is_authenticated=False)¶

Обновляет флаг is_authenticated для указанного uri или списка URI.

HTTPPasswordMgrWithPriorAuth.is_authenticated(self, authuri)¶

Возвращает текущее состояние флага is_authenticated для указанного URI.

21.6.9. Объекты 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" – нет).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

HTTPHandler.http_open(req)¶

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

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

HTTPSHandler.https_open(req)¶

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

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

FileHandler.file_open(req)¶

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

Изменено в версии 3.2: Этот метод применим только для локальных имен хоста. Если указано удаленное имя хоста, возникает исключение URLError.

21.6.18. Объекты DataHandler¶DataHandler Objects

DataHandler.data_open(req)¶

Читает data URL. Такой URL содержит контент, закодированный в самом URL. Синтаксис data URL описан в RFC 2397. Данная реализация игнорирует пробелы в data URL, закодированных в base64, поэтому URL может быть перенесен в любом исходном файле, откуда он взят. Но хотя некоторые браузеры не обращают внимания на отсутствие дополнения в конце URL в base64, эта реализация в таком случае возбудит исключение ValueError.

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

FTPHandler.ftp_open(req)¶

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

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

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

CacheFTPHandler.setTimeout(t)¶

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

CacheFTPHandler.setMaxConns(m)¶

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

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

UnknownHandler.unknown_open()¶

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

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

HTTPErrorProcessor.http_response()¶

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

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

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

HTTPErrorProcessor.https_response()¶

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

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

21.6.23. Примеры¶Examples

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

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

>>> import urllib.request
>>> with urllib.request.urlopen('http://www.python.org/') as f:
...     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, https://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')
>>> with urllib.request.urlopen(req) as f:
...     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)

Вот пример выполнения запроса PUT с помощью Request:

import urllib.request
DATA = b'some data'
req = urllib.request.Request(url='http://localhost:8080', data=DATA,method='PUT')
with urllib.request.urlopen(req) as f:
    pass
print(f.status)
print(f.reason)

Использование базовой 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/')
# Настроить значение заголовка User-Agent по умолчанию:
req.add_header('User-Agent', 'urllib-example/0.1 (Contact: . . .)')
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 и Host) добавляются, когда Request передаётся в urlopen() (или OpenerDirector.open()).

Вот пример сеанса, в котором используется метод GET для получения URL с параметрами:

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

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

>>> import urllib.request
>>> import urllib.parse
>>> data = urllib.parse.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
>>> data = data.encode('ascii')
>>> with urllib.request.urlopen("http://requestb.in/xrbl82xr", data) as f:
...     print(f.read().decode('utf-8'))
...

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

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

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

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

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

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

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

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

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

Следующий пример иллюстрирует наиболее распространённый сценарий использования:

>>> import urllib.request
>>> local_filename, headers = urllib.request.urlretrieve('http://python.org/')
>>> html = open(local_filename)
>>> html.close()

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

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

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

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

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

urllib.request.urlcleanup()¶

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

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

Устарело с версии 3.3.

Базовый класс для открытия и чтения 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 возбуждают исключение OSError, если сервер возвращает код ошибки.

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, это должна быть функция, принимающая три числовых параметра: номер чанка, максимальный размер читаемых чанков и общий размер загрузки (-1, если неизвестен). Она будет вызвана один раз в начале и после каждого чтения чанка данных из сети. Для локальных URL параметр reporthook игнорируется.

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

version¶

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

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

Устарело с версии 3.3.

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), который можно использовать для базовой аутентификации.

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

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

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

  Изменено в версии 3.4: Добавлена поддержка data-URL.

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

• Должна быть функция для проверки, находится ли определённый 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 в соответствии со своими потребностями.