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

Источник: Lib/urllib/request.py

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

См.также

Значение Requests package рекомендуется для клиентского интерфейса HTTP более высокого уровня.

Предупреждение

На macOS небезопасно использовать этот модуль в программах, использующих os.fork(), поскольку реализация getproxies() для macOS использует системный API более высокого уровня. Чтобы избежать этой проблемы, установите переменную окружения no_proxy на * (например, os.environ["no_proxy"] = "*").

Availability: не WASI.

Этот модуль не работает или недоступен на WebAssembly. Дополнительную информацию см. в разделе Платформы WebAssembly.

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

urllib.request.urlopen(url, data=None, [timeout, ]*, context=None)¶

Откройте url, который может быть либо строкой, содержащей правильный, правильно закодированный URL, либо объектом Request.

data должен быть объектом, указывающим дополнительные данные для отправки на сервер, или None, если такие данные не нужны. Подробности см. в разделе Request.

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

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

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

Эта функция всегда возвращает объект, который может работать как context manager и имеет свойства url, headers и status. Подробнее об этих свойствах см. в разделе urllib.response.addinfourl.

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

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

Поднимает auditing event urllib.Request с аргументами fullurl, data, headers, method.

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

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

data может быть итерируемым объектом.

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

Изменено в версии 3.4.3: Был добавлен контекст.

Изменено в версии 3.10: HTTPS-соединение теперь отправляет расширение ALPN с индикатором протокола http/1.1, когда не задан контекст. Пользовательский контекст должен устанавливать протоколы ALPN с показателем set_alpn_protocols().

Изменено в версии 3.13: Удалите параметры cafile, capath и cadefault: вместо них используйте параметр context.

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

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

Возвращает экземпляр OpenerDirector, который цепляет обработчики в указанном порядке. handlers могут быть либо экземплярами BaseHandler, либо подклассами BaseHandler (в этом случае конструктор должен быть возможен без параметров). Перед handlers будут стоять экземпляры следующих классов, если только handlers не содержит их, их экземпляры или их подклассы: 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 без учета регистра, сначала для всех операционных систем, а когда не находит их, ищет информацию о прокси из системной конфигурации для macOS и системного реестра 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 должен быть объектом, указывающим дополнительные данные для отправки на сервер, или None, если такие данные не нужны. В настоящее время только HTTP-запросы используют data. Поддерживаемые типы объектов включают байты, файлоподобные объекты и итерации байтоподобных объектов. Если ни поле заголовка Content-Length, ни Transfer-Encoding не были предоставлены, HTTPHandler установит эти заголовки в соответствии с типом data. Content-Length будет использоваться для передачи байтовых объектов, а Transfer-Encoding: chunked, как указано в RFC 7230, раздел 3.3.1, будет использоваться для передачи файлов и других итерабельных объектов.

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

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

Соответствующий заголовок Content-Type должен быть включен, если присутствует аргумент data. Если этот заголовок не был предоставлен и data не является None, то по умолчанию будет добавлен Content-Type: application/x-www-form-urlencoded.

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

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

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

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

Примечание

Запрос не сработает так, как ожидалось, если объект данных не может передать свое содержимое более одного раза (например, файл или итерируемый объект, который может выдать содержимое только один раз), и запрос будет повторен для HTTP-перенаправления или аутентификации. Данные* отправляются на HTTP-сервер сразу после заголовков. В библиотеке нет поддержки ожидания 100 продолжений.

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

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

Изменено в версии 3.6: Не вызывайте ошибку, если Content-Length не был предоставлен и data не является ни None, ни объектом bytes. Вместо этого перейдите к использованию кодировки chunked transfer.

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

class urllib.request.ProxyHandler(proxies=None)¶

Причиняет запросы, проходящие через прокси. Если указано proxies, то это должен быть словарь, отображающий имена протоколов на URL-адреса прокси-серверов. По умолчанию список прокси считывается из переменных окружения <protocol>_proxy. Если переменные окружения прокси не заданы, то в среде Windows настройки прокси берутся из раздела реестра «Настройки Интернета», а в среде macOS информация о прокси берется из System Configuration Framework.

Чтобы отключить автоопределение прокси, передайте пустой словарь.

Переменная окружения 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.

Added in version 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 будут автоматически включать учетные данные аутентификации.

Added in version 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 для обработки. Этот метод обработчика вызовет ошибку 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-адресов. context и check_hostname имеют то же значение, что и в http.client.HTTPSConnection.

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

class urllib.request.FileHandler¶: Открывайте локальные файлы.

class urllib.request.DataHandler¶: URL-адреса открытых данных.

Added in version 3.4.

class urllib.request.FTPHandler¶: Открывайте URL-адреса FTP.

class urllib.request.CacheFTPHandler¶: Открывайте URL-адреса FTP, сохраняя кэш открытых FTP-соединений для минимизации задержек.

class urllib.request.UnknownHandler¶: Универсальный класс для работы с неизвестными URL.

class urllib.request.HTTPErrorProcessor¶: Обработка ответов на ошибки HTTP.

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

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

Added in version 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)¶: Удаление именованного заголовка из экземпляра запроса (как из обычных, так и из ненаправленных заголовков).

Added in version 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()¶: Возвращает список кортежей (имя_заголовка, значение_заголовка) заголовков запроса.

Изменено в версии 3.4: Методы запроса add_data, has_data, get_data, get_type, get_host, get_selector, get_origin_req_host и is_unverifiable, которые были устаревшими с версии 3.3, были удалены.

Объекты 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 в три этапа:

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

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

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

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

Объекты BaseHandler¶

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

BaseHandler.add_parent(director)¶: Добавьте директора в качестве родителя.

BaseHandler.close()¶: Удалите всех родителей.

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

Примечание

Принято считать, что подклассы, определяющие методы <protocol>_request() или <protocol>_response(), называются *Processor; все остальные - *Handler.

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¶

Примечание

Некоторые HTTP-перенаправления требуют действий от клиентского кода этого модуля. Если это так, то вызывается сообщение HTTPError. Подробнее о точных значениях различных кодов перенаправления см. в RFC 2616.

Исключение HTTPError, возникающее по соображениям безопасности, если HTTPRedirectHandler представлен перенаправляемый URL, который не является HTTP, HTTPS или FTP URL.

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

HTTPRedirectHandler.http_error_308(req, fp, code, msg, hdrs)¶: То же, что и http_error_301(), но вызывается для ответа „permanent redirect“. Он не позволяет изменить метод запроса с POST на GET.

Added in version 3.11.

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

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. Обратите внимание, что вывод params из 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().

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

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

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

class urllib.response.addinfourl¶

url¶: URL-адрес полученного ресурса, обычно используется для определения того, было ли выполнено перенаправление.

headers¶: Возвращает заголовки ответа в виде экземпляра EmailMessage.

status¶: Added in version 3.9.

Код состояния, возвращаемый сервером.

geturl()¶: Не рекомендуется, начиная с версии 3.9: Утратил актуальность в пользу url.

info()¶: Не рекомендуется, начиная с версии 3.9: Утратил актуальность в пользу headers.

code¶: Не рекомендуется, начиная с версии 3.9: Утратил актуальность в пользу status.

getcode()¶: Не рекомендуется, начиная с версии 3.9: Утратил актуальность в пользу status.

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

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

Объекты OpenerDirector¶

Объекты BaseHandler¶

Объекты HTTPRedirectHandler¶

Объекты HTTPCookieProcessor¶

Объекты ProxyHandler¶

Объекты HTTPPasswordMgr¶

Объекты HTTPPasswordMgrWithPriorAuth¶

Объекты AbstractBasicAuthHandler¶

Объекты HTTPBasicAuthHandler¶

Объекты ProxyBasicAuthHandler¶

Объекты AbstractDigestAuthHandler¶

Объекты HTTPDigestAuthHandler¶

Объекты ProxyDigestAuthHandler¶

Объекты HTTPHandler¶

Объекты HTTPSHandler¶

Объекты FileHandler¶

Объекты DataHandler¶

Объекты FTPHandler¶

Объекты CacheFTPHandler¶

Объекты UnknownHandler¶

Объекты HTTPErrorProcessor¶

Примеры¶

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

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

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

Оглавление

Предыдущий раздел

Следующий раздел

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

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

Объекты OpenerDirector¶

Объекты BaseHandler¶

Объекты HTTPRedirectHandler¶

Объекты HTTPCookieProcessor¶

Объекты ProxyHandler¶

Объекты HTTPPasswordMgr¶

Объекты HTTPPasswordMgrWithPriorAuth¶

Объекты AbstractBasicAuthHandler¶

Объекты HTTPBasicAuthHandler¶

Объекты ProxyBasicAuthHandler¶

Объекты AbstractDigestAuthHandler¶

Объекты HTTPDigestAuthHandler¶

Объекты ProxyDigestAuthHandler¶

Объекты HTTPHandler¶

Объекты HTTPSHandler¶

Объекты FileHandler¶

Объекты DataHandler¶

Объекты FTPHandler¶

Объекты CacheFTPHandler¶

Объекты UnknownHandler¶

Объекты HTTPErrorProcessor¶

Примеры¶

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

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

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

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

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

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