`urllib.request.md`

1061 строк · 78.8 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.0/library/urllib.request.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `urllib.request` – расширяемая библиотека для открытия URL-адресов89Модуль `urllib.request` определяет функции и классы, которые помогают открывать URL (в основном HTTP) в сложном мире – базовая и дайджест-аутентификация, перенаправления, куки и многое другое.1011Модуль `urllib.request` определяет следующие функции:1213#### `[urllib.request.urlopen]urllib.request.urlopen(url[, data][, timeout])`1415Открывает URL *url*, который может быть строкой или объектом [`Request`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.Request).1617*data* может быть строкой, задающей дополнительные данные для отправки серверу, или `None`, если такие данные не нужны. В настоящее время только HTTP-запросы используют *data*; если указан параметр *data*, HTTP-запрос будет типа POST вместо GET. Значение *data* должно быть буфером в стандартном формате *application/x-www-form-urlencoded*. Функция [`urllib.parse.urlencode()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.urlencode) принимает отображение или последовательность кортежей из двух элементов и возвращает строку в этом формате.1819Необязательный параметр *timeout* задаёт тайм-аут в секундах для блокирующих операций, таких как попытка подключения (если не указан, будет использоваться глобальная настройка тайм-аута по умолчанию). На самом деле это работает только для соединений HTTP, HTTPS, FTP и FTPS.2021Эта функция возвращает объект, похожий на файл, с двумя дополнительными методами из модуля `urllib.response`2223- `geturl()` – возвращает URL полученного ресурса; обычно используется для определения, был ли выполнен редирект.24- `info()` – возвращает метаинформацию страницы, такую как заголовки, в виде экземпляра `http.client.HTTPMessage` (см. [Краткий справочник по HTTP-заголовкам](https://python-all.ru/3.0/library/urllib.request.html))2526Возбуждает `URLError` при ошибках.2728Обратите внимание, что `None` может быть возвращён, если ни один обработчик не обрабатывает запрос (хотя установленный по умолчанию глобальный [`OpenerDirector`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.OpenerDirector) использует [`UnknownHandler`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.UnknownHandler), чтобы гарантировать, что этого никогда не произойдёт). Функция urlopen из предыдущей версии, Python 2.6 и ранее, модуля urllib была прекращена, поскольку urlopen может возвращать файловый объект, как и раньше. Обработка прокси, которая ранее передавалась как параметр dict в urlopen, теперь доступна через использование объектов [`ProxyHandler`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.ProxyHandler).2930#### `[urllib.request.install_opener]urllib.request.install_opener(opener)`3132Устанавливает экземпляр3334[`OpenerDirector`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.OpenerDirector)3536в качестве глобального открывателя по умолчанию. Установка открывателя необходима только в том случае, если требуется, чтобы urlopen использовал именно этот открыватель; в противном случае просто вызывайте3738[`OpenerDirector.open()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.OpenerDirector.open)3940вместо4142[`urlopen()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.urlopen)4344. Код не проверяет, является ли объект реальным4546[`OpenerDirector`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.OpenerDirector)4748; подойдет любой класс с подходящим интерфейсом.4950#### `[urllib.request.build_opener]urllib.request.build_opener([handler, ...])`5152Возвращает экземпляр [`OpenerDirector`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.OpenerDirector), который объединяет обработчики в указанном порядке. *обработчики* могут быть как экземплярами [`BaseHandler`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.BaseHandler), так и подклассами [`BaseHandler`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.BaseHandler) (в этом случае конструктор должен вызываться без параметров). Экземпляры следующих классов будут размещены перед *обработчиками*, если только *обработчики* не содержат их, их экземпляры или подклассы: [`ProxyHandler`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.ProxyHandler), [`UnknownHandler`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.UnknownHandler), [`HTTPHandler`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.HTTPHandler), [`HTTPDefaultErrorHandler`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.HTTPDefaultErrorHandler), [`HTTPRedirectHandler`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.HTTPRedirectHandler), [`FTPHandler`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.FTPHandler), [`FileHandler`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.FileHandler), `HTTPErrorProcessor`.5354Если установка Python поддерживает SSL (т.е. если модуль [`ssl`](https://python-all.ru/3.0/library/ssl.html#module-ssl) может быть импортирован), то будет добавлен также [`HTTPSHandler`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.HTTPSHandler).5556Подкласс [`BaseHandler`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.BaseHandler) также может изменить свою переменную-член `handler_order`, чтобы изменить свою позицию в списке обработчиков.5758#### `[urllib.request.urlretrieve]urllib.request.urlretrieve(url[, filename[, reporthook[, data]]])`5960Копирует сетевой объект, заданный URL, в локальный файл, если это необходимо. Если URL указывает на локальный файл или существует валидная кешированная копия объекта, объект не копируется. Возвращает кортеж `(filename, headers)`, где *filename* – это имя локального файла, в котором можно найти объект, а *headers* – то, что вернул метод `info()` объекта, возвращенного [`urlopen()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.urlopen) (для удаленного объекта, возможно кешированного). Исключения те же, что и для [`urlopen()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.urlopen).6162Второй аргумент, если он задан, указывает, в какой файл копировать данные (если отсутствует, данные будут записаны во временный файл с автоматически сгенерированным именем). Третий аргумент, если он задан, – это функция-обработчик, которая будет вызвана один раз при установке сетевого соединения и затем после каждого прочитанного блока. Функция будет получать три аргумента: количество переданных блоков, размер блока в байтах и общий размер файла. Третий аргумент может быть `-1` на старых FTP-серверах, которые не возвращают размер файла в ответ на запрос получения.6364Если *url* использует идентификатор схемы `http:`, необязательный аргумент *data* может быть передан для указания запроса `POST` (обычно тип запроса – `GET`). Аргумент *data* должен быть в стандартном формате *application/x-www-form-urlencoded*; см. функцию `urlencode()` ниже.6566[`urlretrieve()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.urlretrieve) вызовет исключение `ContentTooShortError`, если обнаружит, что объём доступных данных меньше ожидаемого (то есть размера, указанного в заголовке *Content-Length*). Это может произойти, например, если загрузка была прервана.6768Заголовок *Content-Length* рассматривается как нижняя граница: если доступно больше данных для чтения, urlretrieve читает больше данных, но если данных меньше, он вызывает исключение.6970В этом случае загруженные данные всё ещё можно получить, они хранятся в атрибуте `content` экземпляра исключения.7172Если заголовок *Content-Length* не был передан, urlretrieve не может проверить размер загруженных данных и просто возвращает их. В этом случае остаётся только предполагать, что загрузка прошла успешно.7374#### `[urllib.request._urlopener]urllib.request._urlopener`7576Публичные функции [`urlopen()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.urlopen) и [`urlretrieve()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.urlretrieve) создают экземпляр класса [`FancyURLopener`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.FancyURLopener) и используют его для выполнения запрошенных действий. Чтобы переопределить это поведение, программисты могут создать подкласс [`URLopener`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.URLopener) или [`FancyURLopener`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.FancyURLopener), затем присвоить экземпляр этого класса переменной `urllib._urlopener` перед вызовом нужной функции. Например, приложения могут захотеть указать другой заголовок *User-Agent*, чем тот, который определяет [`URLopener`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.URLopener). Это можно сделать следующим кодом:7778```python79import urllib.request8081class AppURLopener(urllib.request.FancyURLopener):82    version = "App/1.7"8384urllib._urlopener = AppURLopener()85```8687#### `[urllib.request.urlcleanup]urllib.request.urlcleanup()`8889Очищает кеш, который мог накопиться при предыдущих вызовах9091[`urlretrieve()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.urlretrieve)9293.9495#### `[urllib.request.pathname2url]urllib.request.pathname2url(path)`9697Преобразует имя пути9899*path*100101из локального синтаксиса в форму, используемую в компоненте пути URL. При этом не создаётся полный URL. Возвращаемое значение уже будет экранировано с помощью функции102103`quote()`104105.106107#### `[urllib.request.url2pathname]urllib.request.url2pathname(path)`108109Преобразует компонент пути110111*path*112113из закодированного URL в локальный синтаксис пути. Эта функция не принимает полный URL. Для декодирования114115*path*116117используется118119`unquote()`120121.122123Предоставляются следующие классы:124125#### `[urllib.request.Request]class urllib.request.Request(url[, data][, headers][, origin_req_host][, unverifiable])`126127Этот класс представляет абстракцию URL-запроса.128129*url* должен быть строкой, содержащей корректный URL.130131*data* может быть строкой, задающей дополнительные данные для отправки серверу, или `None`, если такие данные не нужны. В настоящее время только HTTP-запросы используют *data*; если указан параметр *data*, HTTP-запрос будет типа POST вместо GET. Значение *data* должно быть буфером в стандартном формате *application/x-www-form-urlencoded*. Функция [`urllib.parse.urlencode()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.urlencode) принимает отображение или последовательность кортежей из двух элементов и возвращает строку в этом формате.132133*headers* должен быть словарём, и он будет обработан так, как если бы [`add_header()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.Request.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).134135Последние два аргумента представляют интерес только для корректной обработки сторонних HTTP-куки:136137*origin\_req\_host* должен быть хостом запроса исходной транзакции, как определено в [**RFC 2965**](https://python-all.ru/3.0/library/urllib.request.html). По умолчанию он равен `http.cookiejar.request_host(self)`. Это имя хоста или IP-адрес исходного запроса, инициированного пользователем. Например, если запрос относится к изображению на HTML-странице, то это должен быть хост запроса страницы, содержащей изображение.138139*unverifiable* должен указывать, является ли запрос непроверяемым, как определено в RFC 2965. По умолчанию он равен False. Непроверяемый запрос – это запрос, URL которого пользователь не имел возможности одобрить. Например, если запрос относится к изображению в HTML-документе, и у пользователя не было возможности одобрить автоматическую загрузку изображения, этот флаг должен быть true.140141#### `[urllib.request.URLopener]class urllib.request.URLopener([proxies[, **x509]])`142143Базовый класс для открытия и чтения URL. Если не требуется поддержка открытия объектов с использованием схем, отличных от `http:`, `ftp:` или `file:`, вероятно, стоит использовать [`FancyURLopener`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.FancyURLopener).144145По умолчанию класс [`URLopener`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.URLopener) отправляет заголовок *User-Agent* со значением `urllib/VVV`, где *VVV* – это номер версии `urllib`. Приложения могут определить свой собственный заголовок *User-Agent*, создав подкласс [`URLopener`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.URLopener) или [`FancyURLopener`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.FancyURLopener) и установив атрибут класса [`version`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.URLopener.version) в соответствующее строковое значение в определении подкласса.146147Необязательный параметр *proxies* должен быть словарём, сопоставляющим имена схем с URL прокси, причём пустой словарь полностью отключает прокси. По умолчанию значение равно `None`; в этом случае будут использованы настройки прокси из окружения, если они присутствуют, как описано в определении [`urlopen()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.urlopen) выше.148149Дополнительные именованные параметры, собранные в *x509*, могут использоваться для аутентификации клиента при использовании схемы `https:`. Поддерживаются ключи *key\_file* и *cert\_file* для предоставления SSL-ключа и сертификата; оба необходимы для поддержки аутентификации клиента.150151Объекты [`URLopener`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.URLopener) возбуждают исключение [`IOError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.IOError), если сервер возвращает код ошибки.152153> #### `[urllib.request.URLopener.open]open(fullurl[, data])`154>155> Открывает156>157> *fullurl*158>159> , используя соответствующий протокол. Этот метод настраивает кеш и информацию о прокси, затем вызывает соответствующий метод open с его входными аргументами. Если схема не распознана, вызывается160>161> [`open_unknown()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.URLopener.open_unknown)162>163> . Аргумент164>165> *data*166>167> имеет тот же смысл, что и аргумент168>169> *data*170>171> функции172>173> [`urlopen()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.urlopen)174>175> .176>177> #### `[urllib.request.URLopener.open_unknown]open_unknown(fullurl[, data])`178>179> Переопределяемый интерфейс для открытия неизвестных типов URL.180>181> #### `[urllib.request.URLopener.retrieve]retrieve(url[, filename[, reporthook[, data]]])`182>183> Извлекает содержимое *url* и помещает его в *filename*. Возвращаемое значение – это кортеж, состоящий из локального имени файла и либо объекта [`email.message.Message`](https://python-all.ru/3.0/library/email.message.html#email.message.Message), содержащего заголовки ответа (для удаленных URL), либо `None` (для локальных URL). Вызывающий код затем должен открыть и прочитать содержимое *filename*. Если *filename* не указан и URL ссылается на локальный файл, возвращается исходное имя файла. Если URL не локальный и *filename* не указан, имя файла – результат вызова [`tempfile.mktemp()`](https://python-all.ru/3.0/library/tempfile.html#tempfile.mktemp) с суффиксом, соответствующим суффиксу последнего компонента пути входного URL. Если указан *reporthook*, он должен быть функцией, принимающей три числовых параметра. Она будет вызываться после каждого чтения блока данных из сети. *reporthook* игнорируется для локальных URL.184>185> Если *url* использует идентификатор схемы `http:`, необязательный аргумент *data* может быть передан для указания запроса `POST` (обычно тип запроса – `GET`). Аргумент *data* должен быть в стандартном формате *application/x-www-form-urlencoded*; см. функцию `urlencode()` ниже.186>187> #### `[urllib.request.URLopener.version]version`188>189> Переменная, задающая пользовательский агент объекта opener. Чтобы заставить190>191> `urllib`192>193> сообщать серверам, что он использует определённый пользовательский агент, задайте эту переменную в подклассе как переменную класса или в конструкторе перед вызовом конструктора базового класса.194195#### `[urllib.request.FancyURLopener]class urllib.request.FancyURLopener(...)`196197[`FancyURLopener`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.FancyURLopener) является подклассом [`URLopener`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.URLopener), предоставляющим стандартную обработку следующих кодов ответа HTTP: 301, 302, 303, 307 и 401. Для перечисленных выше кодов 30x заголовок *Location* используется для получения фактического URL. Для кода 401 (требуется аутентификация) выполняется базовая HTTP-аутентификация. Для кодов 30x рекурсия ограничена значением атрибута *maxtries*, по умолчанию равным 10.198199Для всех остальных кодов ответа вызывается метод `http_error_default()`, который можно переопределить в подклассах для соответствующей обработки ошибки.200201> **Примечание**202>203> В соответствии с буквой [**RFC 2616**](https://python-all.ru/3.0/library/urllib.request.html) ответы 301 и 302 на POST-запросы не должны автоматически перенаправляться без подтверждения пользователем. Однако на практике браузеры разрешают автоматическое перенаправление таких ответов, изменяя POST на GET, и `urllib` воспроизводит это поведение.204205Параметры конструктора такие же, как и для [`URLopener`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.URLopener).206207> **Примечание**208>209> > При выполнении базовой аутентификации экземпляр210> >211> > [`FancyURLopener`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.FancyURLopener)212> >213> > вызывает свой метод214> >215> > [`prompt_user_passwd()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.FancyURLopener.prompt_user_passwd)216> >217> > . Реализация по умолчанию запрашивает у пользователя необходимые сведения на управляющем терминале. При необходимости подкласс может переопределить этот метод, чтобы обеспечить более подходящее поведение.218>219> Класс [`FancyURLopener`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.FancyURLopener) предоставляет один дополнительный метод, который следует переопределить для обеспечения соответствующего поведения:220>221> #### `[urllib.request.FancyURLopener.prompt_user_passwd]prompt_user_passwd(host, realm)`222>223> Возвращает информацию, необходимую для аутентификации пользователя на указанном хосте в заданной области безопасности. Возвращаемое значение должно быть кортежем, `(user, password)`, который можно использовать для базовой аутентификации.224>225> Реализация запрашивает эту информацию на терминале; приложение должно переопределить этот метод, чтобы использовать подходящую модель взаимодействия в локальной среде.226227#### `[urllib.request.OpenerDirector]class urllib.request.OpenerDirector`228229Класс230231[`OpenerDirector`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.OpenerDirector)232233открывает URL-адреса через цепочку обработчиков234235[`BaseHandler`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.BaseHandler)236237. Он управляет объединением обработчиков в цепочку и восстановлением после ошибок.238239#### `[urllib.request.BaseHandler]class urllib.request.BaseHandler`240241Это базовый класс для всех зарегистрированных обработчиков – он отвечает только за простую механику регистрации.242243#### `[urllib.request.HTTPDefaultErrorHandler]class urllib.request.HTTPDefaultErrorHandler`244245Класс, который определяет обработчик по умолчанию для HTTP-ответов с ошибками; все ответы преобразуются в исключения246247`HTTPError`248249.250251#### `[urllib.request.HTTPRedirectHandler]class urllib.request.HTTPRedirectHandler`252253Класс для обработки перенаправлений.254255#### `[urllib.request.HTTPCookieProcessor]class urllib.request.HTTPCookieProcessor([cookiejar])`256257Класс для обработки HTTP-куки.258259#### `[urllib.request.ProxyHandler]class urllib.request.ProxyHandler([proxies])`260261Заставляет запросы идти через прокси. Если262263*proxies*264265задан, это должен быть словарь, сопоставляющий имена протоколов с URL прокси. По умолчанию список прокси читается из переменных окружения266267. Чтобы отключить автоматическое определение прокси, передайте пустой словарь.268269#### `[urllib.request.HTTPPasswordMgr]class urllib.request.HTTPPasswordMgr`270271Ведёт базу данных соответствий между272273`(realm, uri) -> и (user, password)`274275.276277#### `[urllib.request.HTTPPasswordMgrWithDefaultRealm]class urllib.request.HTTPPasswordMgrWithDefaultRealm`278279Ведёт базу данных соответствий между280281`(realm, uri) -> и (user, password)`282283. Область (realm) со значением284285`None`286287считается универсальной – она используется, если не подходит ни одна другая.288289#### `[urllib.request.AbstractBasicAuthHandler]class urllib.request.AbstractBasicAuthHandler([password_mgr])`290291Это миксин-класс, который помогает с HTTP-аутентификацией как на удалённом хосте, так и на прокси.292293*password\_mgr*294295, если задан, должен быть совместим с296297[`HTTPPasswordMgr`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.HTTPPasswordMgr)298299; информацию об интерфейсе, который должен поддерживаться, см. в разделе300301[*HTTPPasswordMgr Objects*](https://python-all.ru/3.0/library/urllib.request.html#http-password-mgr)302303.304305#### `[urllib.request.HTTPBasicAuthHandler]class urllib.request.HTTPBasicAuthHandler([password_mgr])`306307Обрабатывает аутентификацию с удалённым хостом. Если указан,308309*password\_mgr*310311должен быть совместим с312313[`HTTPPasswordMgr`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.HTTPPasswordMgr)314315; информацию о том, какой интерфейс должен поддерживаться, см. в разделе316317[*HTTPPasswordMgr Objects*](https://python-all.ru/3.0/library/urllib.request.html#http-password-mgr)318319.320321#### `[urllib.request.ProxyBasicAuthHandler]class urllib.request.ProxyBasicAuthHandler([password_mgr])`322323Обрабатывает аутентификацию с прокси.324325*password\_mgr*326327, если задан, должен быть совместим с328329[`HTTPPasswordMgr`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.HTTPPasswordMgr)330331; информацию об интерфейсе, который должен поддерживаться, см. в разделе332333[*HTTPPasswordMgr Objects*](https://python-all.ru/3.0/library/urllib.request.html#http-password-mgr)334335.336337#### `[urllib.request.AbstractDigestAuthHandler]class urllib.request.AbstractDigestAuthHandler([password_mgr])`338339Это миксин-класс, который помогает с HTTP-аутентификацией как на удалённом хосте, так и на прокси.340341*password\_mgr*342343, если задан, должен быть совместим с344345[`HTTPPasswordMgr`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.HTTPPasswordMgr)346347; информацию об интерфейсе, который должен поддерживаться, см. в разделе348349[*HTTPPasswordMgr Objects*](https://python-all.ru/3.0/library/urllib.request.html#http-password-mgr)350351.352353#### `[urllib.request.HTTPDigestAuthHandler]class urllib.request.HTTPDigestAuthHandler([password_mgr])`354355Обрабатывает аутентификацию с удалённым хостом. Если указан,356357*password\_mgr*358359должен быть совместим с360361[`HTTPPasswordMgr`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.HTTPPasswordMgr)362363; информацию о том, какой интерфейс должен поддерживаться, см. в разделе364365[*HTTPPasswordMgr Objects*](https://python-all.ru/3.0/library/urllib.request.html#http-password-mgr)366367.368369#### `[urllib.request.ProxyDigestAuthHandler]class urllib.request.ProxyDigestAuthHandler([password_mgr])`370371Обрабатывает аутентификацию с прокси.372373*password\_mgr*374375, если задан, должен быть совместим с376377[`HTTPPasswordMgr`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.HTTPPasswordMgr)378379; информацию об интерфейсе, который должен поддерживаться, см. в разделе380381[*HTTPPasswordMgr Objects*](https://python-all.ru/3.0/library/urllib.request.html#http-password-mgr)382383.384385#### `[urllib.request.HTTPHandler]class urllib.request.HTTPHandler`386387Класс для открытия HTTP-URL.388389#### `[urllib.request.HTTPSHandler]class urllib.request.HTTPSHandler`390391Класс для открытия HTTPS-URL.392393#### `[urllib.request.FileHandler]class urllib.request.FileHandler`394395Открывает локальные файлы.396397#### `[urllib.request.FTPHandler]class urllib.request.FTPHandler`398399Открывает FTP-URL.400401#### `[urllib.request.CacheFTPHandler]class urllib.request.CacheFTPHandler`402403Открывает FTP-URL, сохраняя кеш открытых FTP-соединений для минимизации задержек.404405#### `[urllib.request.UnknownHandler]class urllib.request.UnknownHandler`406407Универсальный класс для обработки неизвестных URL.408409## Объекты запроса410411Следующие методы описывают весь публичный интерфейс [`Request`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.Request), поэтому все они должны быть переопределены в подклассах.412413#### `[urllib.request.Request.add_data]Request.add_data(data)`414415Устанавливает данные416417[`Request`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.Request)418419в420421*data*422423. Это игнорируется всеми обработчиками, кроме HTTP-обработчиков – в них это должна быть строка байтов, и изменит запрос на424425`POST`426427вместо428429`GET`430431.432433#### `[urllib.request.Request.get_method]Request.get_method()`434435Возвращает строку, указывающую метод HTTP-запроса. Это имеет смысл только для HTTP-запросов, и в настоящее время всегда возвращает436437`'GET'`438439или440441`'POST'`442443.444445#### `[urllib.request.Request.has_data]Request.has_data()`446447Возвращает, есть ли у экземпляра данные, отличные от448449`None`450451.452453#### `[urllib.request.Request.get_data]Request.get_data()`454455Возвращает данные экземпляра.456457#### `[urllib.request.Request.add_header]Request.add_header(key, val)`458459Добавляет ещё один заголовок к запросу. В настоящее время заголовки игнорируются всеми обработчиками, кроме HTTP-обработчиков, где они добавляются в список заголовков, отправляемых серверу. Обратите внимание, что не может быть более одного заголовка с одним и тем же именем, и последующие вызовы перезапишут предыдущие в случае совпадения460461*ключа*462463. В настоящее время это не приводит к потере функциональности HTTP, поскольку все заголовки, имеющие смысл при многократном использовании, имеют (специфичный для заголовка) способ достижения той же функциональности с помощью только одного заголовка.464465#### `[urllib.request.Request.add_unredirected_header]Request.add_unredirected_header(key, header)`466467Добавляет заголовок, который не будет добавлен в перенаправленный запрос.468469#### `[urllib.request.Request.has_header]Request.has_header(header)`470471Возвращает, имеет ли экземпляр указанный заголовок (проверяет как обычные, так и неперенаправленные).472473#### `[urllib.request.Request.get_full_url]Request.get_full_url()`474475Возвращает URL, переданный в конструктор.476477#### `[urllib.request.Request.get_type]Request.get_type()`478479Возвращает тип URL – также известный как схема.480481#### `[urllib.request.Request.get_host]Request.get_host()`482483Возвращает хост, к которому будет установлено соединение.484485#### `[urllib.request.Request.get_selector]Request.get_selector()`486487Возвращает селектор – часть URL, которая отправляется серверу.488489#### `[urllib.request.Request.set_proxy]Request.set_proxy(host, type)`490491Подготавливает запрос, подключаясь к прокси-серверу.492493*host*494495и496497*type*498499заменят соответствующие значения экземпляра, а selector экземпляра будет содержать исходный URL, переданный в конструктор.500501#### `[urllib.request.Request.get_origin_req_host]Request.get_origin_req_host()`502503Возвращает хост запроса исходной транзакции, как определено в504505[**RFC 2965**](https://python-all.ru/3.0/library/urllib.request.html)506507. См. документацию к конструктору508509[`Request`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.Request)510511.512513#### `[urllib.request.Request.is_unverifiable]Request.is_unverifiable()`514515Возвращает, является ли запрос непроверяемым, как определено в RFC 2965. См. документацию к конструктору516517[`Request`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.Request)518519.520521## Объекты OpenerDirector522523[`OpenerDirector`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.OpenerDirector) имеет следующие методы:524525#### `[urllib.request.OpenerDirector.add_handler]OpenerDirector.add_handler(handler)`526527*handler* должен быть экземпляром [`BaseHandler`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.BaseHandler). Ищутся и добавляются в возможные цепочки следующие методы (обратите внимание, что ошибки HTTP являются особым случаем).528529- `protocol_open()` – сигнал о том, что обработчик умеет открывать URL-адреса *протокол*.530- `http_error_type()` – сигнал о том, что обработчик умеет обрабатывать ошибки HTTP с кодом ошибки HTTP *type*.531- `protocol_error()` – сигнал о том, что обработчик умеет обрабатывать ошибки от протокола *протокол* (кроме `http`).532- `protocol_request()` – сигнал о том, что обработчик умеет предварительно обрабатывать запросы *протокол*.533- `protocol_response()` – сигнал о том, что обработчик умеет выполнять последующую обработку ответов *протокол*.534535#### `[urllib.request.OpenerDirector.open]OpenerDirector.open(url[, data][, timeout])`536537Открывает заданный538539*url*540541(который может быть объектом запроса или строкой), опционально передавая заданные542543*data*544545. Аргументы, возвращаемые значения и исключения такие же, как у546547[`urlopen()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.urlopen)548549(которая просто вызывает метод550551[`open()`](https://python-all.ru/3.0/library/functions.html#open)552553текущего глобального554555[`OpenerDirector`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.OpenerDirector)556557). Необязательный параметр558559*timeout*560561задаёт тайм-аут в секундах для блокирующих операций, таких как попытка соединения (если не указан, используется глобальная настройка тайм-аута по умолчанию). Возможность тайм-аута работает только для соединений HTTP, HTTPS, FTP и FTPS).562563#### `[urllib.request.OpenerDirector.error]OpenerDirector.error(proto[, arg[, ...]])`564565Обрабатывает ошибку указанного протокола. Вызывает зарегистрированные обработчики ошибок для данного протокола с указанными аргументами (которые зависят от протокола). Протокол HTTP является особым случаем, использующим код ответа HTTP для определения конкретного обработчика ошибок; обратитесь к методам `http_error_*()` классов обработчиков.566567Возвращаемые значения и исключения такие же, как у [`urlopen()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.urlopen).568569Объекты OpenerDirector открывают URL в три этапа:570571Порядок вызова этих методов в каждом этапе определяется сортировкой экземпляров обработчиков.5725731. У каждого обработчика, имеющего метод с именем вида `protocol_request()`, этот метод вызывается для предварительной обработки запроса.5742. Обработчики с методом, названным как `protocol_open()`, вызываются для обработки запроса. Этот этап завершается, когда обработчик либо возвращает значение, отличное от [`None`](https://python-all.ru/3.0/library/constants.html#None) (т.е. ответ), либо вызывает исключение (обычно `URLError`). Исключения могут распространяться.575576   На самом деле описанный алгоритм сначала применяется к методам с именем `default_open()`. Если все такие методы возвращают [`None`](https://python-all.ru/3.0/library/constants.html#None), алгоритм повторяется для методов с именем вида `protocol_open()`. Если все такие методы возвращают [`None`](https://python-all.ru/3.0/library/constants.html#None), алгоритм повторяется для методов с именем `unknown_open()`.577578   Обратите внимание, что реализация этих методов может включать вызовы методов [`open()`](https://python-all.ru/3.0/library/functions.html#open) и `error()` родительского экземпляра [`OpenerDirector`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.OpenerDirector).5793. У каждого обработчика, имеющего метод с именем вида `protocol_response()`, этот метод вызывается для последующей обработки ответа.580581## Объекты BaseHandler582583Объекты [`BaseHandler`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.BaseHandler) предоставляют несколько методов, которые полезны непосредственно, и другие, предназначенные для использования производными классами. Следующие предназначены для прямого использования:584585#### `[urllib.request.BaseHandler.add_parent]BaseHandler.add_parent(director)`586587Добавляет директор в качестве родителя.588589#### `[urllib.request.BaseHandler.close]BaseHandler.close()`590591Удаляет всех родителей.592593Следующие атрибуты и методы должны использоваться только классами, производными от [`BaseHandler`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.BaseHandler).594595> **Примечание**596>597> Принято соглашение: подклассы, определяющие методы `protocol_request()` или `protocol_response()`, называются `*Processor`; все остальные называются `*Handler`.598599#### `[urllib.request.BaseHandler.parent]BaseHandler.parent`600601Действительный объект602603[`OpenerDirector`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.OpenerDirector)604605, который можно использовать для открытия с помощью другого протокола или для обработки ошибок.606607#### `[urllib.request.BaseHandler.default_open]BaseHandler.default_open(req)`608609Этот метод *не* определён в [`BaseHandler`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.BaseHandler), но подклассы должны определить его, если хотят перехватывать все URL.610611Этот метод, если реализован, будет вызван родительским [`OpenerDirector`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.OpenerDirector). Он должен вернуть объект, похожий на файл, как описано в возвращаемом значении [`open()`](https://python-all.ru/3.0/library/functions.html#open) класса [`OpenerDirector`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.OpenerDirector), или `None`. Он должен вызывать `URLError`, если только не происходит действительно исключительная ситуация (например, [`MemoryError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.MemoryError) не должно преобразовываться в `URLError`).612613Этот метод будет вызван перед любым методом открытия, специфичным для протокола.614615#### `BaseHandler.protocol_open(req)`616617Этот метод *не* определён в [`BaseHandler`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.BaseHandler), но подклассы должны определить его, если хотят обрабатывать URL с указанным протоколом.618619Этот метод, если он определён, вызывается родительским [`OpenerDirector`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.OpenerDirector). Возвращаемые значения должны быть такими же, как и для [`default_open()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.BaseHandler.default_open).620621#### `[urllib.request.BaseHandler.unknown_open]BaseHandler.unknown_open(req)`622623Этот метод *не* определён в [`BaseHandler`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.BaseHandler), но подклассы должны определить его, если хотят перехватывать все URL, для открытия которых нет зарегистрированного конкретного обработчика.624625Этот метод, если он реализован, вызывается родительским [`родительский`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.BaseHandler.parent) [`OpenerDirector`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.OpenerDirector). Возвращаемые значения должны быть такими же, как и для [`default_open()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.BaseHandler.default_open).626627#### `[urllib.request.BaseHandler.http_error_default]BaseHandler.http_error_default(req, fp, code, msg, hdrs)`628629Этот метод *не* определён в [`BaseHandler`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.BaseHandler), но подклассы должны переопределить его, если намерены предоставить универсальный обработчик для всех прочих необработанных HTTP-ошибок. Он будет автоматически вызван [`OpenerDirector`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.OpenerDirector) при получении ошибки и обычно не должен вызываться в других обстоятельствах.630631*req* будет объектом [`Request`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.Request), *fp* – файлоподобным объектом с телом HTTP-ошибки, *code* – трёхзначным кодом ошибки, *msg* – понятным пользователю пояснением кода, а *hdrs* – объектом-отображением с заголовками ошибки.632633Возвращаемые значения и возбуждаемые исключения должны быть такими же, как у [`urlopen()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.urlopen).634635#### `[urllib.request.BaseHandler.http_error_nnn]BaseHandler.http_error_nnn(req, fp, code, msg, hdrs)`636637*nnn* должен быть трёхзначным кодом HTTP-ошибки. Этот метод также не определён в [`BaseHandler`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.BaseHandler), но будет вызван, если он существует, на экземпляре подкласса при возникновении HTTP-ошибки с кодом *nnn*.638639Подклассы должны переопределить этот метод для обработки конкретных HTTP-ошибок.640641Аргументы, возвращаемые значения и возбуждаемые исключения должны быть такими же, как и для [`http_error_default()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.BaseHandler.http_error_default).642643#### `BaseHandler.protocol_request(req)`644645Этот метод *не* определён в [`BaseHandler`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.BaseHandler), но подклассы должны определить его, если хотят предварительно обрабатывать запросы указанного протокола.646647Этот метод, если он определён, вызывается родительским [`OpenerDirector`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.OpenerDirector). *req* будет объектом [`Request`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.Request). Возвращаемое значение должно быть объектом [`Request`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.Request).648649#### `BaseHandler.protocol_response(req, response)`650651Этот метод *не* определён в [`BaseHandler`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.BaseHandler), но подклассы должны определить его, если хотят выполнять последующую обработку ответов указанного протокола.652653Этот метод, если он определён, вызывается родительским [`OpenerDirector`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.OpenerDirector). *req* будет объектом [`Request`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.Request). *response* будет объектом, реализующим тот же интерфейс, что и возвращаемое значение [`urlopen()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.urlopen). Возвращаемое значение должно реализовывать тот же интерфейс, что и возвращаемое значение [`urlopen()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.urlopen).654655## Объекты HTTPRedirectHandler656657> **Примечание**658>659> Некоторые HTTP-перенаправления требуют действий со стороны клиентского кода этого модуля. Если это так, возбуждается `HTTPError`. Подробнее о точном значении различных кодов перенаправления см. [**RFC 2616**](https://python-all.ru/3.0/library/urllib.request.html).660661#### `[urllib.request.HTTPRedirectHandler.redirect_request]HTTPRedirectHandler.redirect_request(req, fp, code, msg, hdrs)`662663Возвращает [`Request`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.Request) или `None` в ответ на перенаправление. Этот метод вызывается реализациями по умолчанию методов `http_error_30*()`, когда с сервера получено перенаправление. Если перенаправление должно произойти, возвращает новый [`Request`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.Request), чтобы позволить `http_error_30*()` выполнить перенаправление. В противном случае возбуждает `HTTPError`, если никакой другой обработчик не должен пытаться обработать этот URL, или возвращает `None`, если не может, но другой обработчик может.664665> **Примечание**666>667> Реализация этого метода по умолчанию не строго следует [**RFC 2616**](https://python-all.ru/3.0/library/urllib.request.html), в котором сказано, что ответы с кодами 301 и 302 на `POST` запросы не должны автоматически перенаправляться без подтверждения пользователем. На практике браузеры разрешают автоматическое перенаправление этих ответов, заменяя POST на `GET`, и реализация по умолчанию воспроизводит такое поведение.668669#### `[urllib.request.HTTPRedirectHandler.http_error_301]HTTPRedirectHandler.http_error_301(req, fp, code, msg, hdrs)`670671Перенаправляет на URL из заголовка672673`Location:`674675. Этот метод вызывается родительским676677[`OpenerDirector`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.OpenerDirector)678679при получении HTTP-ответа «перемещён навсегда».680681#### `[urllib.request.HTTPRedirectHandler.http_error_302]HTTPRedirectHandler.http_error_302(req, fp, code, msg, hdrs)`682683То же, что и684685[`http_error_301()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.HTTPRedirectHandler.http_error_301)686687, но вызывается для ответа «found».688689#### `[urllib.request.HTTPRedirectHandler.http_error_303]HTTPRedirectHandler.http_error_303(req, fp, code, msg, hdrs)`690691То же, что и692693[`http_error_301()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.HTTPRedirectHandler.http_error_301)694695, но вызывается для ответа «see other».696697#### `[urllib.request.HTTPRedirectHandler.http_error_307]HTTPRedirectHandler.http_error_307(req, fp, code, msg, hdrs)`698699То же, что и700701[`http_error_301()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.HTTPRedirectHandler.http_error_301)702703, но вызывается для ответа «temporary redirect».704705## Объекты HTTPCookieProcessor706707Экземпляры [`HTTPCookieProcessor`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.HTTPCookieProcessor) имеют один атрибут:708709#### `[urllib.request.HTTPCookieProcessor.cookiejar]HTTPCookieProcessor.cookiejar`710711Объект712713[`http.cookiejar.CookieJar`](https://python-all.ru/3.0/library/http.cookiejar.html#http.cookiejar.CookieJar)714715, в котором хранятся куки.716717## Объекты ProxyHandler718719#### `ProxyHandler.protocol_open(request)`720721Для каждого722723*протокола*724725, для которого в словаре726727*proxies*728729, переданном в конструктор, указан прокси, объект730731[`ProxyHandler`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.ProxyHandler)732733будет иметь метод734735`protocol_open()`736737. Этот метод изменяет запрос для направления через прокси, вызывая738739`request.set_proxy()`740741, и передаёт управление следующему обработчику в цепочке для фактического выполнения протокола.742743## Объекты HTTPPasswordMgr744745Эти методы доступны для объектов [`HTTPPasswordMgr`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.HTTPPasswordMgr) и [`HTTPPasswordMgrWithDefaultRealm`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.HTTPPasswordMgrWithDefaultRealm).746747#### `[urllib.request.HTTPPasswordMgr.add_password]HTTPPasswordMgr.add_password(realm, uri, user, passwd)`748749*uri*750751может быть как одним URI, так и последовательностью URI.752753*realm*754755,756757*user*758759и760761*passwd*762763должны быть строками. В результате764765`(user, passwd)`766767будет использоваться в качестве токенов аутентификации при запросе аутентификации для768769*realm*770771и супер-URI любого из указанных URI.772773#### `[urllib.request.HTTPPasswordMgr.find_user_password]HTTPPasswordMgr.find_user_password(realm, authuri)`774775Возвращает пару пользователь/пароль для указанных realm и URI, если они есть. Если совпадений нет, этот метод вернёт `(None, None)`.776777Для объектов [`HTTPPasswordMgrWithDefaultRealm`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.HTTPPasswordMgrWithDefaultRealm), если для указанного *realm* нет подходящей пары пользователь/пароль, будет выполнен поиск по realm `None`.778779## Объекты AbstractBasicAuthHandler780781#### `[urllib.request.AbstractBasicAuthHandler.http_error_auth_reqed]AbstractBasicAuthHandler.http_error_auth_reqed(authreq, host, req, headers)`782783Обрабатывает запрос аутентификации, получая пару пользователь/пароль и повторяя запрос. *authreq* должно быть именем заголовка, в котором содержится информация о realm, *host* указывает URL и путь для аутентификации, *req* должен быть (неудачным) объектом [`Request`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.Request), а *headers* – заголовками ошибки.784785*host* – это либо полномочное имя (например, `"python.org"`), либо URL, содержащий компонент полномочного имени (например, `"http://python.org/"`). В любом случае полномочное имя не должно содержать компонента userinfo (так что `"python.org"` и `"python.org:80"` допустимы, а `"joe:password@python.org"` – нет).786787## Объекты HTTPBasicAuthHandler788789#### `[urllib.request.HTTPBasicAuthHandler.http_error_401]HTTPBasicAuthHandler.http_error_401(req, fp, code, msg, hdrs)`790791Повторяет запрос с информацией аутентификации, если она доступна.792793## Объекты ProxyBasicAuthHandler794795#### `[urllib.request.ProxyBasicAuthHandler.http_error_407]ProxyBasicAuthHandler.http_error_407(req, fp, code, msg, hdrs)`796797Повторяет запрос с информацией аутентификации, если она доступна.798799## Объекты AbstractDigestAuthHandler800801#### `[urllib.request.AbstractDigestAuthHandler.http_error_auth_reqed]AbstractDigestAuthHandler.http_error_auth_reqed(authreq, host, req, headers)`802803*authreq*804805должно быть именем заголовка, в котором содержится информация о realm,806807*host*808809должен быть хостом для аутентификации,810811*req*812813должен быть (неудачным) объектом814815[`Request`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.Request)816817, а818819*headers*820821– заголовками ошибки.822823## Объекты HTTPDigestAuthHandler824825#### `[urllib.request.HTTPDigestAuthHandler.http_error_401]HTTPDigestAuthHandler.http_error_401(req, fp, code, msg, hdrs)`826827Повторяет запрос с информацией аутентификации, если она доступна.828829## Объекты ProxyDigestAuthHandler830831#### `[urllib.request.ProxyDigestAuthHandler.http_error_407]ProxyDigestAuthHandler.http_error_407(req, fp, code, msg, hdrs)`832833Повторяет запрос с информацией аутентификации, если она доступна.834835## Объекты HTTPHandler836837#### `[urllib.request.HTTPHandler.http_open]HTTPHandler.http_open(req)`838839Отправляет HTTP-запрос, который может быть GET или POST, в зависимости от840841`req.has_data()`842843.844845## Объекты HTTPSHandler846847#### `[urllib.request.HTTPSHandler.https_open]HTTPSHandler.https_open(req)`848849Отправляет HTTPS-запрос, который может быть GET или POST, в зависимости от850851`req.has_data()`852853.854855## Объекты FileHandler856857#### `[urllib.request.FileHandler.file_open]FileHandler.file_open(req)`858859Открывает файл локально, если имя хоста отсутствует или равно860861`'localhost'`862863. В противном случае меняет протокол на864865`ftp`866867и повторяет попытку открытия с помощью868869`parent`870871.872873## Объекты FTPHandler874875#### `[urllib.request.FTPHandler.ftp_open]FTPHandler.ftp_open(req)`876877Открывает FTP-файл, указанный878879*req*880881. Вход всегда выполняется с пустыми именем пользователя и паролем.882883## Объекты CacheFTPHandler884885Объекты [`CacheFTPHandler`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.CacheFTPHandler) являются объектами [`FTPHandler`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.FTPHandler) с дополнительными методами:886887#### `[urllib.request.CacheFTPHandler.setTimeout]CacheFTPHandler.setTimeout(t)`888889Устанавливает тайм-аут соединений равным890891*t*892893секунд.894895#### `[urllib.request.CacheFTPHandler.setMaxConns]CacheFTPHandler.setMaxConns(m)`896897Устанавливает максимальное количество кэшированных соединений равным898899*m*900901.902903## Объекты UnknownHandler904905#### `[urllib.request.UnknownHandler.unknown_open]UnknownHandler.unknown_open()`906907Возбуждает исключение908909`URLError`910911.912913## Объекты HTTPErrorProcessor914915#### `[urllib.request.HTTPErrorProcessor.unknown_open]HTTPErrorProcessor.unknown_open()`916917Обрабатывает ошибочные HTTP-ответы.918919Для кода 200 объект ответа возвращается немедленно.920921Для кодов ошибок, отличных от 200, этот метод просто передает задачу методам-обработчикам `protocol_error_code()` через [`OpenerDirector.error()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.OpenerDirector.error). В конечном итоге [`HTTPDefaultErrorHandler`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.HTTPDefaultErrorHandler) возбудит `HTTPError`, если ни один другой обработчик не обработает ошибку.922923## Примеры924925В этом примере загружается главная страница python.org и выводятся первые 100 байт её содержимого:926927```python928>>> import urllib.request929>>> f = urllib.request.urlopen('http://www.python.org/')930>>> print(f.read(100))931<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">932<?xml-stylesheet href="./css/ht2html933```934935Здесь мы отправляем поток данных на stdin CGI и читаем данные, которые он возвращает. Обратите внимание: этот пример работает только при наличии поддержки SSL в установке Python.936937```python938>>> import urllib.request939>>> req = urllib.request.Request(url='https://localhost/cgi-bin/test.cgi',940...                       data='This data is passed to stdin of the CGI')941>>> f = urllib.request.urlopen(req)942>>> print(f.read())943Got Data: "This data is passed to stdin of the CGI"944```945946Код образца CGI, использованного в приведённом выше примере:947948```python949#!/usr/bin/env python950import sys951data = sys.stdin.read()952print('Content-type: text-plain\n\nGot Data: "%s"' % data)953```954955Использование базовой HTTP-аутентификации:956957```python958import urllib.request959# Создать OpenerDirector с поддержкой базовой HTTP-аутентификации...960auth_handler = urllib.request.HTTPBasicAuthHandler()961auth_handler.add_password(realm='PDQ Application',962                          uri='https://mahler:8092/site-updates.py',963                          user='klem',964                          passwd='kadidd!ehopper')965opener = urllib.request.build_opener(auth_handler)966# ...и установить его глобально, чтобы его можно было использовать с urlopen.967urllib.request.install_opener(opener)968urllib.request.urlopen('http://www.example.com/login.html')969```970971[`build_opener()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.build_opener) по умолчанию предоставляет множество обработчиков, включая [`ProxyHandler`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.ProxyHandler). По умолчанию [`ProxyHandler`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.ProxyHandler) использует переменные окружения с именами вида `<scheme>_proxy`, где `<scheme>` – это схема URL. Например, переменная окружения **http\_proxy** считывается для получения URL HTTP-прокси.972973В этом примере стандартный [`ProxyHandler`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.ProxyHandler) заменяется на тот, который использует программно задаваемые URL прокси, и добавляется поддержка авторизации прокси с помощью [`ProxyBasicAuthHandler`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.ProxyBasicAuthHandler).974975```python976proxy_handler = urllib.request.ProxyHandler({'http': 'http://www.example.com:3128/'})977proxy_auth_handler = urllib.request.HTTPBasicAuthHandler()978proxy_auth_handler.add_password('realm', 'host', 'username', 'password')979980opener = build_opener(proxy_handler, proxy_auth_handler)981# На этот раз, вместо установки OpenerDirector, используется напрямую:982opener.open('http://www.example.com/login.html')983```984985Добавление HTTP-заголовков:986987Используйте аргумент *headers* конструктора [`Request`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.Request) или:988989```python990import urllib.request991req = urllib.request.Request('http://www.example.com/')992req.add_header('Referer', 'http://www.python.org/')993r = urllib.request.urlopen(req)994```995996[`OpenerDirector`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.OpenerDirector) автоматически добавляет заголовок *User-Agent* к каждому [`Request`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.Request). Чтобы изменить это:997998```python999import urllib.request1000opener = urllib.request.build_opener()1001opener.addheaders = [('User-agent', 'Mozilla/5.0')]1002opener.open('http://www.example.com/')1003```10041005Также помните, что несколько стандартных заголовков (*Content-Length*, *Content-Type* и *Host*) добавляются, когда [`Request`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.Request) передаётся в [`urlopen()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.urlopen) (или [`OpenerDirector.open()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.OpenerDirector.open)).10061007Ниже приведён пример сеанса, в котором используется метод `GET` для получения URL, содержащего параметры:10081009```python1010>>> import urllib.request1011>>> import urllib.parse1012>>> params = urllib.parse.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})1013>>> f = urllib.request.urlopen("http://www.musi-cal.com/cgi-bin/query?%s" % params)1014>>> print(f.read())1015```10161017В следующем примере вместо этого используется метод `POST`:10181019```python1020>>> import urllib.request1021>>> import urllib.parse1022>>> params = urllib.parse.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})1023>>> f = urllib.request.urlopen("http://www.musi-cal.com/cgi-bin/query", params)1024>>> print(f.read())1025```10261027В следующем примере используется явно указанный HTTP-прокси, переопределяющий настройки окружения:10281029```python1030>>> import urllib.request1031>>> proxies = {'http': 'http://proxy.example.com:8080/'}1032>>> opener = urllib.request.FancyURLopener(proxies)1033>>> f = opener.open("http://www.python.org")1034>>> f.read()1035```10361037В следующем примере прокси не используются вовсе, переопределяя настройки окружения:10381039```python1040>>> import urllib.request1041>>> opener = urllib.request.FancyURLopener({})1042>>> f = opener.open("http://www.python.org/")1043>>> f.read()1044```10451046## `urllib.request` Ограничения10471048>10491050- В настоящее время поддерживаются только следующие протоколы: HTTP (версии 0.9 и 1.0), FTP и локальные файлы.1051- Возможность кэширования [`urlretrieve()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.urlretrieve) отключена, пока не найдётся время на реализацию корректной обработки заголовков срока действия.1052- Должна быть функция для проверки, находится ли определённый URL в кэше.1053- Для обратной совместимости, если URL указывает на локальный файл, но файл не удаётся открыть, URL интерпретируется заново с использованием протокола FTP. Это иногда может приводить к запутанным сообщениям об ошибках.1054- Функции [`urlopen()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.urlopen) и [`urlretrieve()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.urlretrieve) могут вызывать сколь угодно долгие задержки при ожидании установки сетевого соединения. Это означает, что создать интерактивный веб-клиент с помощью этих функций без использования потоков сложно.1055- Данные, возвращаемые [`urlopen()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.urlopen) или [`urlretrieve()`](https://python-all.ru/3.0/library/urllib.request.html#urllib.request.urlretrieve), представляют собой необработанные данные, возвращаемые сервером. Это могут быть бинарные данные (например, изображение), обычный текст или, скажем, HTML. Протокол HTTP предоставляет информацию о типе в заголовке ответа, которую можно узнать, посмотрев на заголовок *Content-Type*. Если возвращаемые данные являются HTML, можно использовать модуль [`html.parser`](https://python-all.ru/3.0/library/html.parser.html#module-html.parser) для его разбора.1056- Код, обрабатывающий протокол FTP, не может различить файл и каталог. Это может привести к неожиданному поведению при попытке чтения URL, который указывает на недоступный файл. Если URL заканчивается на `/`, считается, что он ссылается на каталог, и он обрабатывается соответствующим образом. Но если попытка чтения файла приводит к ошибке 550 (означающей, что URL не найден или недоступен, часто по причинам прав доступа), то путь обрабатывается как каталог, чтобы учесть случай, когда каталог задан URL, но завершающий `/` опущен. Это может привести к вводящим в заблуждение результатам при попытке получить файл, права на чтение которого делают его недоступным; код FTP попытается прочитать его, получит ошибку 550, а затем выполнит список содержимого каталога для этого недоступного файла. Если требуется более детальный контроль, рассмотрите возможность использования модуля [`ftplib`](https://python-all.ru/3.0/library/ftplib.html#module-ftplib), создания подкласса `FancyURLOpener` или изменения *\_urlopener* в соответствии с вашими потребностями.10571058# `urllib.response` – Классы ответов, используемые urllib.10591060Модуль `urllib.response` определяет функции и классы, которые предоставляют минимальный файлоподобный интерфейс, включая `read()` и `readline()`. Типичный объект ответа – это экземпляр addinfourl, который определяет метод `info()`, возвращающий заголовки, и метод `geturl()`, возвращающий URL. Функции, определённые в этом модуле, используются внутри модуля `urllib.request`.1061