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

Исходный код: Lib/urllib/request.py

Модуль urllib.request определяет функции и классы, которые помогают открывать URL-адреса (в основном HTTP) в сложном мире — базовая и дайджест-аутентификация, перенаправления, куки и многое другое.

Модуль urllib.request определяет следующие функции:

urllib.request.urlopen(url, data=None, [timeout, ]*, cafile=None, capath=None, cadefault=False, context=None)

Открыть URL url, который может быть либо строкой, либо объектом Request.

data должен быть объектом типа bytes, определяющим дополнительные данные, которые должны быть отправлены на сервер, или None если такие данные не нужны. data также может быть итерируемым объектом, и в этом случае значение Content-Length должно быть указано в заголовках. В настоящее время HTTP-запросы — единственные, которые используют data; HTTP-запрос будет POST, а не GET, когда параметр data предоставлен.

data должен быть буфером в стандартном формате application/x-www-form-urlencoded. Функция urllib.parse.urlencode() принимает отображение или последовательность пар 2-х кортежей и возвращает строку ASCII текста в этом формате. Она должна быть закодирована в байты перед использованием в качестве параметра data.

Модуль urllib.request использует HTTP/1.1 и включает заголовок Connection:close в своих HTTP-запросах.

Необязательный параметр timeout задаёт таймаут в секундах для блокирующих операций, таких как попытка подключения (если не указан, используется глобальная настройка таймаута по умолчанию). Это действительно работает только для подключений HTTP, HTTPS и FTP.

Если указан параметр context, он должен быть экземпляром ssl.SSLContext, описывающим различные параметры SSL. Подробнее см. в HTTPSConnection.

Необязательные параметры cafile и capath задают набор доверенных сертификатов CA для HTTPS-запросов. cafile должен указывать на один файл, содержащий набор сертификатов CA, а capath — на каталог файлов хешированных сертификатов. Дополнительную информацию можно найти в ssl.SSLContext.load_verify_locations().

Параметр cadefault игнорируется.

Эта функция всегда возвращает объект, который может работать как менеджер контекста и имеет методы, такие как

• geturl() — возвращает URL ресурса, полученного, обычно используется для определения, было ли выполнено перенаправление
• info() — возвращает метаданные страницы, такие как заголовки, в виде объекта email.message_from_string() (см. Быстрый справочник по HTTP-заголовкам)
• getcode() — возвращает HTTP-код состояния ответа.

Для HTTP и HTTPS URL эта функция возвращает объект http.client.HTTPResponse с небольшими изменениями. В дополнение к трём новым методам выше, атрибут msg содержит ту же информацию, что и атрибут reason — фразу причины, возвращаемую сервером — вместо заголовков ответа, как указано в документации для HTTPResponse.

Для FTP, файловых и данных URL и запросов, явно обрабатываемых устаревшими классами URLopener и FancyURLopener, эта функция возвращает объект urllib.response.addinfourl.

Возбуждает URLError при ошибках протокола.

Обратите внимание, что None может быть возвращён, если ни один обработчик не обрабатывает запрос (хотя установленный по умолчанию глобальный OpenerDirector использует UnknownHandler, чтобы гарантировать, что этого никогда не произойдёт).

Кроме того, если обнаружены настройки прокси (например, при установке переменной окружения *_proxy , такой как http_proxy), ProxyHandler устанавливается по умолчанию и обеспечивает обработку запросов через прокси.

Устаревшая функция urllib.urlopen из Python 2.6 и ранее прекратила своё существование; urllib.request.urlopen() соответствует старой urllib2.urlopen. Обработка прокси, которая выполнялась путём передачи словаря параметров в urllib.urlopen, может быть получена с помощью объектов ProxyHandler.

Изменено в версии 3.2: Добавлены cafile и capath.

Изменено в версии 3.2: Теперь поддерживаются виртуальные хосты HTTPS, если это возможно (то есть, если ssl.HAS_SNI истинно).

Добавлена в версии 3.2: data может быть итерируемым объектом.

Изменено в версии 3.3: Добавлен cadefault.

Изменено в версии 3.4.3: Добавлен context.

urllib.request.install_opener(opener)

Установить экземпляр OpenerDirector в качестве глобального обработчика по умолчанию. Установка обработчика необходима только в том случае, если вы хотите, чтобы urlopen использовал этот обработчик; в противном случае просто вызовите OpenerDirector.open() вместо urlopen(). Код не проверяет наличие реального OpenerDirector, и любой класс с соответствующим интерфейсом будет работать.

urllib.request.build_opener([handler, ...])

Возвращает экземпляр OpenerDirector, который связывает обработчики в заданном порядке. handlerы могут быть либо экземплярами BaseHandler, либо подклассами BaseHandler (в этом случае должен быть возможен вызов конструктора без параметров). Экземпляры следующих классов будут перед handlerами, если только handlerы не содержат их, экземпляры или подклассы: ProxyHandler (если обнаружены настройки прокси), UnknownHandler, HTTPHandler, HTTPDefaultErrorHandler, HTTPRedirectHandler, FTPHandler, FileHandler, HTTPErrorProcessor.

Если в установке Python есть поддержка SSL (т.е., если модуль ssl может быть импортирован), HTTPSHandler также будет добавлен.

Подкласс BaseHandler также может изменить свой атрибут handler_order для изменения своего положения в списке обработчиков.

urllib.request.pathname2url(path)

Преобразовать путь path из локального синтаксиса пути в форму, используемую в компоненте пути URL. Это не создаёт полный URL. Значение возврата уже будет закодировано с использованием функции quote().

urllib.request.url2pathname(path)

Преобразовать компонент пути path из процентно-кодированного URL в локальный синтаксис пути. Эта функция не принимает полный URL. Эта функция использует unquote() для декодирования path.

urllib.request.getproxies()

Эта вспомогательная функция возвращает словарь сопоставлений схемы с URL-адресом прокси-сервера. Она ищет переменные среды с именами <scheme>_proxy, не учитывая регистр, для всех операционных систем, а если не находит, то ищет информацию о прокси из настроек системы Mac OSX для Mac OS X и системного реестра Windows для Windows. Если существуют переменные среды как в нижнем, так и в верхнем регистре (и они отличаются), то предпочтительнее используется переменная в нижнем регистре.

Примечание

Если установлена переменная среды REQUEST_METHOD, что обычно указывает на то, что ваш скрипт выполняется в среде CGI, то переменная среды HTTP_PROXY (верхний регистр _PROXY) будет проигнорирована. Это происходит потому, что эта переменная может быть внедрена клиентом с помощью HTTP-заголовка «Proxy:». Если вам нужно использовать HTTP-прокси в среде CGI, используйте ProxyHandler явно или убедитесь, что имя переменной находится в нижнем регистре (или, по крайней мере, имеет суффикс _proxy).

Предоставлены следующие классы:

class urllib.request.Request(url, data=None, headers={}, origin_req_host=None, unverifiable=False, method=None)

Этот класс является абстракцией запроса к URL.

url должен быть строкой, содержащей допустимый URL.

data должен быть объектом типа bytes, задающим дополнительные данные для отправки на сервер, или None, если такие данные не нужны. В настоящее время HTTP-запросы — единственные, использующие data; HTTP-запрос будет POST вместо GET, когда параметр data предоставлен. data должен быть буфером в стандартном формате application/x-www-form-urlencoded. Функция urllib.parse.urlencode() принимает отображение или последовательность пар из 2-х кортежей и возвращает строку ASCII в этом формате. Она должна быть закодирована в bytes перед использованием в качестве параметра data.

headers должен быть словарем и будет обрабатываться так, как будто была вызвана функция add_header() с каждым ключом и значением в качестве аргументов. Это часто используется для «подмены» значения заголовка User-Agent, который используется браузером для идентификации — некоторые HTTP-серверы допускают только запросы, поступающие от обычных браузеров, а не от скриптов. Например, Mozilla Firefox может идентифицировать себя как "Mozilla/5.0 (X11; U; Linux i686) Gecko/20071127 Firefox/2.0.0.11", в то время как у urllib стандартное значение user-agent — "Python-urllib/2.6" (в Python 2.6).

Пример использования заголовка Content-Type с аргументом data — отправка словаря, например, {"Content-Type": "application/x-www-form-urlencoded"}.

Два последних аргумента важны только для правильной обработки сторонних HTTP-куков:

origin_req_host должен быть host запроса первоначальной транзакции, как определено в RFC 2965. По умолчанию он равен http.cookiejar.request_host(self). Это имя хоста или IP-адрес исходного запроса, инициированного пользователем. Например, если запрос относится к изображению в HTML-документе, то это должен быть host запроса на страницу, содержащую изображение.

unverifiable должно указывать, является ли запрос недостоверным, как определено в RFC 2965. По умолчанию оно равно False. Недостоверный запрос — это запрос, URL которого пользователь не мог одобрить. Например, если запрос относится к изображению в HTML-документе, и у пользователя не было возможности одобрить автоматическую загрузку изображения, это должно быть true.

method должна быть строкой, указывающей метод HTTP-запроса, который будет использоваться (например, 'HEAD'). Если указано, его значение хранится в атрибуте method и используется get_method(). Подклассы могут указывать метод по умолчанию, задав атрибут method в самом классе.

Изменено в версии 3.3: Аргумент Request.method добавлен в класс Request.

Изменено в версии 3.4: Значение Request.method по умолчанию может быть указано на уровне класса.

class urllib.request.OpenerDirector

Класс OpenerDirector открывает URL-адреса через цепочку BaseHandler. Он управляет объединением обработчиков и восстановлением после ошибок.

class urllib.request.BaseHandler

Это базовый класс для всех зарегистрированных обработчиков — и обрабатывает только простые механизмы регистрации.

class urllib.request.HTTPDefaultErrorHandler

Класс, определяющий обработчик по умолчанию для HTTP-ответов с ошибками; все ответы преобразуются в исключения HTTPError.

class urllib.request.HTTPRedirectHandler

Класс для обработки перенаправлений.

class urllib.request.HTTPCookieProcessor(cookiejar=None)

Класс для обработки HTTP-куков.

class urllib.request.ProxyHandler(proxies=None)

Вызывает запросы через прокси. Если задано proxies, это должен быть словарь, сопоставляющий имена протоколов с URL-адресами прокси. По умолчанию список прокси считывается из переменных среды <protocol>_proxy. Если переменные среды прокси не установлены, то в среде Windows настройки прокси извлекаются из раздела параметров интернета реестра, а в среде Mac OS X информация о прокси извлекается из фреймворка конфигурации системы Mac OS X.

Для отключения автоматического обнаружения прокси передайте пустой словарь.

Переменная среды no_proxy может использоваться для указания хостов, которые не должны достигаться через прокси; если она установлена, то должна содержать список хостов, разделенных запятыми, необязательно с добавлением :port, например, cern.ch,ncsa.uiuc.edu,some.host:8080.

Примечание

HTTP_PROXY будет проигнорирован, если установлена переменная REQUEST_METHOD; см. документацию по getproxies().

class urllib.request.HTTPPasswordMgr

Хранение базы данных сопоставлений (realm, uri) -> (user, password).

class urllib.request.HTTPPasswordMgrWithDefaultRealm

Хранение базы данных сопоставлений (realm, uri) -> (user, password). Сфера None рассматривается как всеобъемлющая и проверяется, если другие сферы не подходят.

class urllib.request.HTTPPasswordMgrWithPriorAuth

Вариант HTTPPasswordMgrWithDefaultRealm, также имеющий базу данных сопоставлений uri -> is_authenticated. Может использоваться обработчиком BasicAuth для определения того, когда следует немедленно отправить учетные данные аутентификации, вместо ожидания ответа 401.

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

class urllib.request.AbstractBasicAuthHandler(password_mgr=None)

Это миксин-класс, который помогает с HTTP-аутентификацией, как к удалённому хосту, так и к прокси. Если задано password_mgr, оно должно быть совместимо с HTTPPasswordMgr; см. раздел Объекты HTTPPasswordMgr для получения информации о поддерживаемом интерфейсе. Если passwd_mgr также предоставляет методы is_authenticated и update_authenticated (см. Объекты HTTPPasswordMgrWithPriorAuth), то обработчик будет использовать результат is_authenticated для данного URI, чтобы определить, следует ли отправлять учетные данные аутентификации вместе с запросом. Если is_authenticated возвращает True для URI, то учетные данные отправляются. Если is_authenticated — False, то учетные данные не отправляются, и если получен ответ 401, запрос повторно отправляется с учетными данными аутентификации. Если аутентификация успешна, то вызывается update_authenticated для установки is_authenticated True для URI, чтобы последующие запросы к URI или его супер-URI автоматически включали учетные данные аутентификации.

Новое в версии 3.5: Поддержка is_authenticated добавлена.

class urllib.request.HTTPBasicAuthHandler(password_mgr=None)

Обработка аутентификации с удалённым хостом. Если задано password_mgr, оно должно быть совместимо с HTTPPasswordMgr; см. раздел Объекты HTTPPasswordMgr для получения информации о поддерживаемом интерфейсе. HTTPBasicAuthHandler вызовет ValueError, если встретит неправильную схему аутентификации.

class urllib.request.ProxyBasicAuthHandler(password_mgr=None)

Обработка аутентификации с прокси. Если задано password_mgr, оно должно быть совместимо с HTTPPasswordMgr; см. раздел Объекты HTTPPasswordMgr для получения информации о поддерживаемом интерфейсе.

class urllib.request.AbstractDigestAuthHandler(password_mgr=None)

Это миксин-класс, который помогает с аутентификацией HTTP, как к удалённому хосту, так и к прокси. password_mgr, если задан, должен быть совместим с HTTPPasswordMgr; обратитесь к разделу Объекты HTTPPasswordMgr за информацией об интерфейсе, который должен быть поддерживаемым.

class urllib.request.HTTPDigestAuthHandler(password_mgr=None)

Обрабатывает аутентификацию с удалённым хостом. password_mgr, если задан, должен быть совместим с HTTPPasswordMgr; обратитесь к разделу Объекты HTTPPasswordMgr за информацией об интерфейсе, который должен быть поддерживаемым. Когда как Digest Authentication Handler, так и Basic Authentication Handler добавлены, Digest Authentication всегда пробуется первой. Если Digest Authentication возвращает ответ 40x, он отправляется в Basic Authentication handler для обработки. Этот метод Handler вызовет ValueError при представлении схемы аутентификации, отличной от Digest или Basic.

Изменено в версии 3.3: Вызывать ValueError при недопустимой схеме аутентификации.

class urllib.request.ProxyDigestAuthHandler(password_mgr=None)

Обрабатывает аутентификацию с прокси. password_mgr, если задан, должен быть совместим с HTTPPasswordMgr; обратитесь к разделу Объекты HTTPPasswordMgr за информацией об интерфейсе, который должен быть поддерживаемым.

class urllib.request.HTTPHandler

Класс для обработки открытия HTTP-URL.

class urllib.request.HTTPSHandler(debuglevel=0, context=None, check_hostname=None)

Класс для обработки открытия HTTPS-URL. context и check_hostname имеют такое же значение, как и в http.client.HTTPSConnection.

Изменено в версии 3.2: Были добавлены context и check_hostname.

class urllib.request.FileHandler

Открытие локальных файлов.

class urllib.request.DataHandler

Открытие данных URL.

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

class urllib.request.FTPHandler

Открытие FTP-URL.

class urllib.request.CacheFTPHandler

Открытие FTP-URL, сохраняя кеш открытых FTP-соединений для минимизации задержек.

class urllib.request.UnknownHandler

Универсальный класс для обработки неизвестных URL.

class urllib.request.HTTPErrorProcessor

Обработка HTTP-ответов с ошибками.

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

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

Request.get_header(header_name, default=None)

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

Request.header_items()

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

2. Объекты OpenerDirector

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

OpenerDirector.add_handler(handler)

handler должен быть экземпляром BaseHandler. Будут проверены следующие методы и добавлены в возможные цепочки (обратите внимание, что ошибки HTTP являются особым случаем).

• protocol_open() — показывает, что обработчик умеет открывать URL-адреса протокола.
• http_error_type() — показывает, что обработчик умеет обрабатывать ошибки HTTP с кодом ошибки type.
• protocol_error() — показывает, что обработчик умеет обрабатывать ошибки от (не-http) протокола.
• protocol_request() — показывает, что обработчик умеет предварительно обрабатывать запросы протокола.
• protocol_response() — показывает, что обработчик умеет послеобрабатывать ответы протокола.

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

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

OpenerDirector.error(proto, *args)

Обрабатывает ошибку заданного протокола. Это вызовет зарегистрированные обработчики ошибок для данного протокола с заданными аргументами (которые специфичны для протокола). Протокол HTTP является особым случаем, который использует код ответа HTTP для определения конкретного обработчика ошибок; обратитесь к методам http_error_*() классов обработчиков.

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

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

Порядок вызова этих методов в каждом этапе определяется сортировкой экземпляров обработчиков.

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

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

   Фактически, сначала пытается применить алгоритм для методов, похожих на default_open(). Если все такие методы возвращают None, алгоритм повторяется для методов, похожих на protocol_open(). Если все такие методы возвращают None, алгоритм повторяется для методов, похожих на unknown_open().

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

3. Каждый обработчик с методом, похожим на protocol_response(), вызывает этот метод для послеобработки ответа.

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

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

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

5. Объекты HTTPCookieProcessor

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

HTTPCookieProcessor.cookiejar

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

6. Объекты ProxyHandler

ProxyHandler.protocol_open(request)

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

7. Объекты 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 нет соответствующего имени пользователя/пароля.

8. Объекты 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 игнорируется.

HTTPPasswordMgr.find_user_password(realm, authuri)

Аналогично объектам HTTPPasswordMgrWithDefaultRealm.

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

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

HTTPPasswordMgrWithPriorAuth.is_authenticated(self, authuri)

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

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

10. Объекты HTTPBasicAuthHandler

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

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

11. Объекты ProxyBasicAuthHandler

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

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

12. Объекты AbstractDigestAuthHandler

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

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

13. Объекты HTTPDigestAuthHandler

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

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

14. Объекты ProxyDigestAuthHandler

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

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

15. Объекты HTTPHandler

HTTPHandler.http_open(req)

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

16. Объекты HTTPSHandler

HTTPSHandler.https_open(req)

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

17. Объекты FileHandler

FileHandler.file_open(req)

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

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

18. Объекты DataHandler

DataHandler.data_open(req)

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

19. Объекты FTPHandler

FTPHandler.ftp_open(req)

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

20. Объекты CacheFTPHandler

CacheFTPHandler objects are FTPHandler objects with the following additional methods:

CacheFTPHandler.setTimeout(t)

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

CacheFTPHandler.setMaxConns(m)

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

21. Объекты UnknownHandler

UnknownHandler.unknown_open()

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

22. Объекты HTTPErrorProcessor

HTTPErrorProcessor.http_response()

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

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

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

HTTPErrorProcessor.https_response()

Обработать HTTPS-ответы об ошибках.

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

23. Примеры

Помимо примеров ниже, дополнительные примеры приведены в ПОСОБИЕ. Получение ресурсов в Интернете с помощью пакета 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, как указано в его теге meta, мы будем использовать её для декодирования объекта bytes.

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

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

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

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

>>> import urllib.request
>>> req = urllib.request.Request(url='https://localhost/cgi-bin/test.cgi',
...                       data=b'This data is passed to stdin of the CGI')
>>> with urllib.request.urlopen(req) as f:
...     print(f.read().decode('utf-8'))
...
Got Data: "This data is passed to stdin of the CGI"

Код образца CGI, используемого в приведенном выше примере:

#!/usr/bin/env python
import sys
data = sys.stdin.read()
print('Content-type: text/plain\n\nGot Data: "%s"' % data)

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

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

Использование базовой HTTP-аутентификации:

import urllib.request
# 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')
...

24. Легальный интерфейс

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

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

Скопировать сетевой объект, обозначенный URL, в локальный файл. Если URL указывает на локальный файл, объект не будет скопирован, если не указано имя файла. Возвращает кортеж (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:, ftp:, или file:, вы, вероятно, захотите использовать FancyURLopener.

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

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

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

Объекты URLopener сгенерируют исключение OSError, если сервер вернёт код ошибки.

open(fullurl, data=None)

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

open_unknown(fullurl, data=None)

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

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

Извлекает содержимое url и помещает его в filename. Результатом является кортеж, состоящий из локального имени файла и объекта email.message.Message (содержащего заголовки ответа для удалённых URL) или None (для локальных URL). Вызывающий код должен открыть и прочитать содержимое filename. Если filename не задан и URL относится к локальному файлу, возвращается имя входного файла. Если URL не является локальным и filename не задан, имя файла — результат вызова функции tempfile.mktemp() с суффиксом, соответствующим суффиксу последнего компонента пути входного URL. Если задан reporthook, он должен быть функцией, принимающей три числовых параметра: номер блока, максимальный размер блоков для чтения и общий размер загрузки (-1, если неизвестен). Он будет вызван один раз в начале и после каждого блока данных, прочитанного из сети. 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. Для перечисленных выше кодов ответов 30х заголовок 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), который может быть использован для базовой аутентификации.

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

25. 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 для удовлетворения ваших потребностей.

urllib.response — Классы ответов, используемые urllib

Модуль urllib.response определяет функции и классы, которые определяют минимальный интерфейс типа файла, включая read() и readline(). Типичный объект ответа — это экземпляр addinfourl, который определяет метод info() для возвращения заголовков и метод geturl() для возвращения URL. Определяемые в этом модуле функции используются модулем urllib.request внутри.