Объекты запроса¶

Следующие методы описывают открытый интерфейс 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)¶

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

Request.get_header(header_name, default=None)¶

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

Request.header_items()¶

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

Объекты OpenerDirector¶

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

OpenerDirector.add_handler(handler)¶

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

• <protocol>_open() — сигнализирует о том, что обработчик знает, как открывать URL-адреса протокола.

  Смотрите BaseHandler.<protocol>_open() для получения дополнительной информации.

• http_error_<type>() — сигнализируйте о том, что обработчик знает, как обрабатывать ошибки HTTP, с помощью кода ошибки HTTP type.

  Смотрите BaseHandler.http_error_<nnn>() для получения дополнительной информации.

• <protocol>_error() — сигнализирует о том, что обработчик знает, как обрабатывать ошибки из (не-http) протокола.

• <protocol>_request() — сигнализирует о том, что обработчик знает, как предварительно обрабатывать запросы по протоколу.

  Смотрите BaseHandler.<protocol>_request() для получения дополнительной информации.

• <protocol>_response() — сигнализирует о том, что обработчик знает, как выполнять постобработку ответов по протоколу.

  Смотрите BaseHandler.<protocol>_response() для получения дополнительной информации.

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

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

OpenerDirector.error(proto, *args)¶

Обработать ошибку данного протокола. При этом будут вызваны зарегистрированные обработчики ошибок для данного протокола с заданными аргументами (которые зависят от протокола). Протокол HTTP - это особый случай, который использует код ответа HTTP для определения конкретного обработчика ошибок; обратитесь к методам http_error_<type>() классов обработчиков.

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

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

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

1. Каждый обработчик с методом, названным как <protocol>_request(), вызывает этот метод для предварительной обработки запроса.

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

   Фактически, описанный выше алгоритм сначала опробуется для методов с именем default_open(). Если все такие методы возвращают значение None, алгоритм повторяется для методов с именем <protocol>_open(). Если все такие методы возвращают None, алгоритм повторяется для методов с именем unknown_open().

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

3. Каждый обработчик с методом, названным как <protocol>_response(), вызывает этот метод для последующей обработки ответа.

Объекты базового обработчика¶

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

Объекты HTTPRedirectHandler¶

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

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

То же, что и http_error_301(), но требует ответа «посмотреть другое».

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

Аналогично http_error_301(), но вызывается для ответа «временное перенаправление». Это не позволяет изменить метод запроса с POST на GET.

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

Аналогично http_error_301(), но вызывается для ответа «постоянное перенаправление». Это не позволяет изменить метод запроса с POST на GET.

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

Объекты HTTPCookieProcessor¶

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

HTTPCookieProcessor.cookiejar¶

http.cookiejar.CookieJar, в котором хранятся файлы cookie.

Объекты обработчика прокси-сервера¶

ProxyHandler.<protocol>_open(request)

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

Объекты HTTPPasswordMgr¶

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

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

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

HTTPPasswordMgr.find_user_password(realm, authuri)¶

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

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

Объекты HTTPPasswordMgrWithPriorAuth¶

Этот менеджер паролей расширяет 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 игнорируется.

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

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

Объекты HTTPBasicAuthHandler¶

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

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

Объекты ProxyBasicAuthHandler¶

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

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

Объекты AbstractDigestAuthHandler¶

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

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

Объекты HTTPDigestAuthHandler¶

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

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

Объекты ProxyDigestAuthHandler¶

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

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

Объекты HttpHandler¶

HTTPHandler.http_open(req)¶

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

Объекты Httphandler¶

HTTPSHandler.https_open(req)¶

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

Объекты обработчика файлов¶

FileHandler.file_open(req)¶

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

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

Объекты обработчика данных¶

DataHandler.data_open(req)¶

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

Объекты обработчика FTPH¶

FTPHandler.ftp_open(req)¶

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

Объекты CacheFTPHandler¶

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

CacheFTPHandler.setTimeout(t)¶

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

CacheFTPHandler.setMaxConns(m)¶

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

Неизвестные объекты-обработчики¶

UnknownHandler.unknown_open()¶

Создайте исключение URLError.

Объекты HTTPErrorProcessor¶

HTTPErrorProcessor.http_response(request, response)¶

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

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

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

HTTPErrorProcessor.https_response(request, response)¶

Обрабатывайте ответы на ошибки HTTPS.

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

Примеры¶

В дополнение к приведенным ниже примерам, другие примеры приведены в разделе КАК получить доступ к Интернет-ресурсам с помощью Пакета urllib.

В этом примере мы получаем главную страницу 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 в string, как только определит или угадает соответствующую кодировку.

В следующем документе 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

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

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

Устаревший интерфейс¶

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

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

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

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

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

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

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

Если заголовок 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().

Этот метод всегда заключает fullurl в кавычки, используя quote().

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

Если в 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. Для 30-кратных кодов ответа, перечисленных выше, для получения фактического URL-адреса используется заголовок Location. Для 401-кратного кода ответа (требуется аутентификация) выполняется обычная HTTP-аутентификация. Для 30-кратных кодов ответа рекурсия ограничена значением атрибута 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), который может использоваться для базовой аутентификации.

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

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

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

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

• Функция кэширования 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 в соответствии с вашими потребностями.