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

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

См.также

Рекомендуется пакет requests для более высокоуровневого клиентского HTTP интерфейса.

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

urllib.request.urlopen(url, data=None, [timeout, ]*, cafile=None, capath=None, cadefault=False, 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 для получения более подробной информации.

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

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

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

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

Для URL-адресов HTTP и HTTPS функция возвращает слегка измененный объект 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.

Средство открытия по умолчанию вызывает событие аудита urllib.Request с аргументами fullurl, data, headers, method, взятыми из объекта запроса.

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

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

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

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

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

Не рекомендуется, начиная с версии 3.6: cafile, capath и cadefault устарели и заменены context. Вместо этого используйте ssl.SSLContext.load_cert_chain() или позвольте ssl.create_default_context() выбрать для вас доверенные сертификаты CA системы.

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

headers должен быть словарем и будет обрабатываться так, как если бы 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.

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

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

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

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

Примечание

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

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

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

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

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

class urllib.request.ProxyHandler(proxies=None)

Вызвать запросы для прохождения через прокси. Если задан proxies, это должен быть словарь, отображающий имена протокола для URL-адресов прокси. По умолчанию список прокси-серверов считывается из переменных среды <protocol>_proxy. Если переменные среды прокси-сервера не заданы, то в среде Windows параметры прокси-сервера берутся из раздела «Параметры интернета» реестра, а в среде Mac OS X информация о прокси-сервере извлекается из среды конфигурации системы 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 для получения информации о поддерживаемом интерфейсе. Если добавлены оба обработчика дайджест-проверки подлинности и обработчик базовой проверки подлинности, дайджест-проверка подлинности всегда выполняется первой. Если дайджест-проверка подлинности снова возвращает ответ 40x, он отправляется обработчику базовой проверки подлинности для обработки. Данный метод обработчика вызовет ValueError при представлении схемы аутентификации, отличной от Digest или Basic.

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

class urllib.request.ProxyDigestAuthHandler(password_mgr=None)

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

class urllib.request.HTTPHandler

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

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

Открыть 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 использует прокси, то селектором будет полный 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()

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

Изменено в версии 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-адреса protocol.

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

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

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

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

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

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

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

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

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

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

OpenerDirector.error(proto, *args)

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

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

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

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

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

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

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

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

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

Объекты BaseHandler

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

BaseHandler.add_parent(director)

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

HTTPRedirectHandler.redirect_request(req, fp, code, msg, hdrs, newurl)

Возвращает Request или None в ответ на перенаправление. Это вызывается реализациями по умолчанию методов http_error_30*(), когда перенаправление получено с сервера. Если перенаправление должно иметь место, возвращает новый Request, чтобы позволить http_error_30*() выполнить перенаправление на newurl. В противном случае вызывается HTTPError, если никакой другой обработчик не должен пытаться обработать этот URL, или возвращает None, если вы не можете, но другой обработчик может.

Примечание

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

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

Перенаправление на URL-адрес Location: или URI:. Этот метод вызывается родительским OpenerDirector при получении HTTP-ответа «перемещено окончательно».

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

То же, что и http_error_301(), но требует ответа «найдено».

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

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

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

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

Объекты HTTPCookieProcessor

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

HTTPCookieProcessor.cookiejar

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

Объекты ProxyHandler

ProxyHandler.<protocol>_open(request)

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

Объекты HTTPPasswordMgr

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

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

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

HTTPPasswordMgr.find_user_password(realm, authuri)

Получить пользователя/пароль для данной области и 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:[email protected]" — нет).

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

Примеры

В дополнение к примерам, приведённым ниже, в HOWTO получение интернет-ресурсов с использованием пакета urllib приведены другие примеры.

Этот пример получает главную страницу python.org и отображает её первые 300 байтов.

>>> import urllib.request
>>> with urllib.request.urlopen('http://www.python.org/') as f:
...     print(f.read(300))
...
b'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">\n\n\n<html
xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">\n\n<head>\n
<meta http-equiv="content-type" content="text/html; charset=utf-8" />\n
<title>Python Programming '

Обратите внимание, что urlopen возвращает байтовый объект. Это связано с тем, что urlopen не может автоматически определять кодировку байтового потока, получаемого от HTTP-сервера. В общем, программа будет декодировать возвращенный объект байтов в строку, как только она определит или угадывает подходящую кодировку.

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

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

>>> 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
# Создать OpenerDirector с поддержкой базовой HTTP-аутентификации ...
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)
# ...и устанавливаем его глобально, чтобы его можно было использовать с 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)
# На этот раз вместо установки OpenerDirector мы используем его напрямую:
opener.open('http://www.example.com/login.html')

Добавление заголовков HTTP:

Использовать аргумент headers для конструктора Request или:

import urllib.request
req = urllib.request.Request('http://www.example.com/')
req.add_header('Referer', 'http://www.python.org/')
# Customize the default User-Agent header value:
req.add_header('User-Agent', 'urllib-example/0.1 (Contact: . . .)')
r = urllib.request.urlopen(req)

OpenerDirector автоматически добавляет заголовок User- Agent к каждому Request. Чтобы изменить это:

import urllib.request
opener = urllib.request.build_opener()
opener.addheaders = [('User-agent', 'Mozilla/5.0')]
opener.open('http://www.example.com/')

Также помните, что несколько стандартных заголовков (Content- Length, Content-Type и Host) добавляются, когда Request передается в urlopen() (или OpenerDirector.open()).

Вот пример сеанса, который использует метод GET для получения URL-адреса, содержащего параметры:

>>> import urllib.request
>>> import urllib.parse
>>> params = urllib.parse.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
>>> url = "http://www.musi-cal.com/cgi-bin/query?%s" % params
>>> with urllib.request.urlopen(url) as f:
...     print(f.read().decode('utf-8'))
...

В следующем примере вместо этого используется метод POST. Обратите внимание, что вывод params из urlencode кодируется в байты перед отправкой в urlopen как данные:

>>> import urllib.request
>>> import urllib.parse
>>> data = urllib.parse.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
>>> data = data.encode('ascii')
>>> with urllib.request.urlopen("http://requestb.in/xrbl82xr", data) as f:
...     print(f.read().decode('utf-8'))
...

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

>>> import urllib.request
>>> proxies = {'http': 'http://proxy.example.com:8080/'}
>>> opener = urllib.request.FancyURLopener(proxies)
>>> with opener.open("http://www.python.org") as f:
...     f.read().decode('utf-8')
...

В следующем примере прокси-серверы вообще не используются, а параметры среды переопределяются:

>>> import urllib.request
>>> opener = urllib.request.FancyURLopener({})
>>> with opener.open("http://www.python.org/") as f:
...     f.read().decode('utf-8')
...

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

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

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

Скопировать сетевой объект, обозначенный URL-адресом, в локальный файл. Если URL-адрес указывает на локальный файл, объект не будет скопирован, если не указано имя файла. Возвращает кортеж (filename, 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_unknown(). У аргумента data то же значение, что и аргумент data для urlopen().

Данный метод всегда цитирует fullurl, используя quote().

open_unknown(fullurl, data=None)

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

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

Извлекает содержимое url и помещает его в filename. Возвращаемое значение представляет собой кортеж, состоящий из локального имени файла и объекта email.message.Message, содержащего заголовки ответа (для удаленных URL-адресов) или None (для локальных URL-адресов). Затем вызывающий абонент должен открыть и прочитать содержимое filename. Если filename не указан, а URL-адрес относится к локальному файлу, возвращается имя входного файла. Если URL-адрес нелокальный и filename не указан, имя файла — это результат tempfile.mktemp() с суффиксом, который совпадает с суффиксом последнего компонента пути входного URL-адреса. Если задан reporthook, это должна быть функция, принимающая три числовых параметра: номер фрагмента, считываемые фрагменты максимального размера и общий размер загрузки (-1, если неизвестно). Он будет вызываться один раз в начале и после чтения каждого блока данных из сети. reporthook игнорируется для локальных URL.

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

version

Переменная, определяющая пользовательский агент объекта открытия. Чтобы urllib сообщал серверам, что это пользовательский агент, устанавливает его в подклассе как переменную класса или в конструкторе перед вызовом базового конструктора.

class urllib.request.FancyURLopener(...)

Не рекомендуется, начиная с версии 3.3.

FancyURLopener подклассы URLopener, обеспечивающие обработку по умолчанию для следующих кодов ответа HTTP: 301, 302, 303, 307 и 401. Для кодов ответа 30x, перечисленных выше, заголовок Location используется для получения фактического URL-адреса. Для кодов ответа 401 (требуется аутентификация) выполняется базовая HTTP- аутентификация. Для кодов ответа 30x рекурсия ограничена значением атрибута maxtries, которое по умолчанию равно 10.

Для всех остальных кодов ответов вызывается метод http_error_default(), который можно переопределить в подклассах для соответствующей обработки ошибки.

Примечание

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

Параметры конструктора такие же, как и для URLopener.

Примечание

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

Класс FancyURLopener предлагает один дополнительный метод, который следует перегрузить для обеспечения надлежащего поведения:

prompt_user_passwd(host, realm)

Возвращает информацию, необходимую для аутентификации пользователя на данном хосте в указанной области безопасности. Возвращаемое значение должно быть кортежем (user, password), который можно использовать для базовой аутентификации.

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

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

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

    Изменено в версии В: 3.4 добавлена поддержка data 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.