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

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

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

Request.get_header(header_name, default=None)¶

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

Request.header_items()¶

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

Объекты OpenerDirector¶

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

OpenerDirector.add_handler(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 (который может быть объектом запроса или строкой), по желанию передавая заданные data. Аргументы, возвращаемые значения и вызываемые исключения те же, что и в 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(). Эта стадия заканчивается, когда обработчик либо возвращает незначение None (т.е. ответ), либо вызывает исключение (обычно URLError). Исключениям разрешено распространяться.

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

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

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

Объекты BaseHandler¶

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

BaseHandler.add_parent(director)¶

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

BaseHandler.close()¶

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

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

BaseHandler.parent¶

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

BaseHandler.default_open(req)¶

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

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

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

BaseHandler.<protocol>_open(req)

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

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

BaseHandler.unknown_open(req)¶

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

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

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

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

req будет объектом Request, fp будет файлоподобным объектом с телом ошибки 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 „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(), но вызывает ответ «увидеть другое».

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

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

Объекты HTTPCookieProcessor¶

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

HTTPCookieProcessor.cookiejar¶

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

Объекты ProxyHandler¶

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 любого из заданных URI.

HTTPPasswordMgr.find_user_password(realm, authuri)¶

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

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

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

Объекты HTTPSHandler¶

HTTPSHandler.https_open(req)¶

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

Объекты FileHandler¶

FileHandler.file_open(req)¶

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

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

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

DataHandler.data_open(req)¶

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

Объекты FTPHandler¶

FTPHandler.ftp_open(req)¶

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

Объекты CacheFTPHandler¶

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

CacheFTPHandler.setTimeout(t)¶

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

CacheFTPHandler.setMaxConns(m)¶

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

Объекты UnknownHandler¶

UnknownHandler.unknown_open()¶

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

Объекты HTTPErrorProcessor¶

HTTPErrorProcessor.http_response(request, response)¶

Обработка ответов на ошибки HTTP.

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

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

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

В следующем примере мы отправляем поток данных на stdin 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 как data:

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

Второй аргумент, если он присутствует, указывает местоположение файла для копирования (если отсутствует, то местоположение будет tempfile со сгенерированным именем). Третий аргумент, если он присутствует, представляет собой вызываемую переменную, которая будет вызываться один раз при установлении сетевого соединения и один раз после каждого прочитанного блока. Этой вызываемой программе будут переданы три аргумента: количество переданных блоков, размер блока в байтах и общий размер файла. Третий аргумент может быть -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().

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