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.
Объекты 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¶
Объекты 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¶
Объекты 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¶
Объекты 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()
.
- 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.
Код состояния, возвращаемый сервером.