urllib.request — Расширяемая библиотека для открытия URL-адресов

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

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

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

• http_error_<type>() — указывает, что обработчик умеет обрабатывать HTTP-ошибки с HTTP-кодом ошибки type.

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

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

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

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

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

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

Примечание

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

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

Перенаправление на Location: или URI: URL. Этот метод вызывается родительским OpenerDirector при получении ответа HTTP '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(), но вызывается для ответа 'temporary redirect'. Не позволяет изменять метод запроса с POST на GET.

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

То же, что и http_error_301(), но вызывается для ответа 'permanent redirect'. Не позволяет изменять метод запроса с POST на GET.

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

Объекты HTTPCookieProcessor

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

HTTPCookieProcessor.cookiejar

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

Объекты ProxyHandler

ProxyHandler.<protocol>_open(request)

ProxyHandler будет иметь метод <protocol>_open() для каждого protocol, для которого в словаре 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)

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

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

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

DataHandler.data_open(req)

Прочитать URL-адрес данных. Такой URL содержит закодированное содержимое самого URL. Синтаксис URL-адресов данных указан в RFC 2397. Эта реализация игнорирует пробелы в URL-адресах данных, закодированных в base64, поэтому URL может быть обернут в любом исходном файле. Однако, хотя некоторые браузеры не обращают внимания на отсутствие завершающей части в base64-кодированных URL-адресах данных, эта реализация возбудит 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 возвращает объект байтов. Это связано с тем, что urlopen не может автоматически определить кодировку потока байтов, полученного от HTTP-сервера. Как правило, программа декодирует возвращённый объект байтов в строку после определения или угадывания соответствующей кодировки.

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

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

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

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

Использование аутентификации Basic 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. Обратите внимание, что выходные данные params из 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. Возвращает кортеж (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 экземпляра исключения.

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

urllib.request.urlcleanup()

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

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

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

Базовый класс для открытия и чтения URL-адресов. Если вам не нужно открывать объекты, используя схемы, отличные от http:, 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

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

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

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