`urllib.request.md`

955 строк · 95.6 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.16/library/urllib.request.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `urllib.request` – Расширяемая библиотека для открытия URL89**Исходный код:** [Lib/urllib/request.py](https://python-all.ru/src/main/Lib/urllib/request.py)1011---1213Модуль `urllib.request` определяет функции и классы, которые помогают открывать URL (в основном HTTP) в сложном мире – базовая и дайджест-аутентификация, перенаправления, куки и многое другое.1415> **См. также**16>17> Для высокоуровневого интерфейса HTTP-клиента рекомендуется [пакет Requests](https://python-all.ru/3.16/library/urllib.request.html).1819> **Предупреждение**20>21> В macOS использовать этот модуль в программах, использующих [`os.fork()`](https://python-all.ru/3.16/library/os.html#os.fork), небезопасно, поскольку реализация [`getproxies()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.getproxies) для macOS использует системный API более высокого уровня. Установите переменную окружения `no_proxy` в `*`, чтобы избежать этой проблемы (например, `os.environ["no_proxy"] = "*"`).2223[Доступность](https://python-all.ru/3.16/library/intro.html#availability): не WASI.2425Этот модуль не работает или недоступен на WebAssembly. Подробнее см. [платформы WebAssembly](https://python-all.ru/3.16/library/intro.html#wasm-availability).2627Модуль `urllib.request` определяет следующие функции:2829#### `urllib.request.urlopen(url, data=None, [timeout, ]*, context=None)`3031Открывает *url*, который может быть строкой, содержащей корректный, правильно закодированный URL, или объектом [`Request`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.Request).3233*data* должен быть объектом, задающим дополнительные данные для отправки серверу, или `None`, если такие данные не нужны. Подробнее см. [`Request`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.Request).3435Модуль urllib.request использует HTTP/1.1 и включает заголовок `Connection:close` в свои HTTP-запросы.3637Необязательный параметр *timeout* задает таймаут в секундах для блокирующих операций, таких как попытка подключения (если не указан, используется глобальная настройка таймаута по умолчанию). Это на самом деле работает только для HTTP, HTTPS и FTP-соединений.3839Если указан *context*, он должен быть экземпляром [`ssl.SSLContext`](https://python-all.ru/3.16/library/ssl.html#ssl.SSLContext), описывающим различные параметры SSL. Подробнее см. [`HTTPSConnection`](https://python-all.ru/3.16/library/http.client.html#http.client.HTTPSConnection).4041Эта функция всегда возвращает объект, который может работать как [контекстный менеджер](https://python-all.ru/3.16/glossary.html#term-context-manager) и имеет свойства *url*, *headers* и *status*. Подробнее об этих свойствах см. [`urllib.response.addinfourl`](https://python-all.ru/3.16/library/urllib.request.html#urllib.response.addinfourl).4243Для HTTP и HTTPS URL эта функция возвращает слегка измененный объект [`http.client.HTTPResponse`](https://python-all.ru/3.16/library/http.client.html#http.client.HTTPResponse). В дополнение к трем новым методам, указанным выше, атрибут msg содержит ту же информацию, что и атрибут [`reason`](https://python-all.ru/3.16/library/http.client.html#http.client.HTTPResponse.reason) – фразу причины, возвращаемую сервером – вместо заголовков ответа, как указано в документации для `HTTPResponse`.4445Для FTP, file и data URL эта функция возвращает объект [`urllib.response.addinfourl`](https://python-all.ru/3.16/library/urllib.request.html#urllib.response.addinfourl).4647Возбуждает [`URLError`](https://python-all.ru/3.16/library/urllib.error.html#urllib.error.URLError) при ошибках протокола.4849Обратите внимание, что может быть возвращен `None`, если ни один обработчик не обрабатывает запрос (хотя установленный по умолчанию глобальный [`OpenerDirector`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.OpenerDirector) использует [`UnknownHandler`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.UnknownHandler), чтобы гарантировать, что этого никогда не произойдет).5051Кроме того, если обнаружены настройки прокси (например, когда установлена переменная окружения `*_proxy`, например `http_proxy`), [`ProxyHandler`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.ProxyHandler) устанавливается по умолчанию и гарантирует, что запросы обрабатываются через прокси.5253Устаревшая функция `urllib.urlopen` из Python 2.6 и более ранних версий была прекращена; `urllib.request.urlopen()` соответствует старому `urllib2.urlopen`. Обработка прокси, которая осуществлялась передачей словаря в параметр функции `urllib.urlopen`, может быть получена с помощью объектов [`ProxyHandler`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.ProxyHandler).5455Стандартный открыватель возбуждает [событие аудита](https://python-all.ru/3.16/library/sys.html#auditing) `urllib.Request` с аргументами `fullurl`, `data`, `headers`, `method`, взятыми из объекта запроса.5657Изменено в версии 3.2: добавлены *cafile* и *capath*.5859Виртуальные хосты HTTPS теперь поддерживаются, если это возможно (то есть, если [`ssl.HAS_SNI`](https://python-all.ru/3.16/library/ssl.html#ssl.HAS_SNI) истинно).6061*data* может быть итерируемым объектом.6263Изменено в версии 3.3: добавлен *cadefault*.6465Изменено в версии 3.4.3: добавлен *context*.6667Изменено в версии 3.10: HTTPS-соединение теперь отправляет расширение ALPN с индикатором протокола `http/1.1`, если не указан *context*. Пользовательский *context* должен устанавливать протоколы ALPN с помощью [`set_alpn_protocols()`](https://python-all.ru/3.16/library/ssl.html#ssl.SSLContext.set_alpn_protocols).6869Изменено в версии 3.13: Удалены параметры *cafile*, *capath* и *cadefault*: вместо них используйте параметр *context*.7071#### `urllib.request.install_opener(opener)`7273Устанавливает экземпляр [`OpenerDirector`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.OpenerDirector) в качестве глобального открывателя по умолчанию. Установка открывателя необходима только в том случае, если требуется, чтобы urlopen использовал именно его; в противном случае просто вызывайте [`OpenerDirector.open()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.OpenerDirector.open) вместо [`urlopen()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.urlopen). Код не проверяет, является ли объект настоящим `OpenerDirector`; подойдет любой класс с соответствующим интерфейсом.7475#### `urllib.request.build_opener([handler, ...])`7677Возвращает экземпляр [`OpenerDirector`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.OpenerDirector), который объединяет обработчики в заданном порядке. *обработчик*и могут быть либо экземплярами [`BaseHandler`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.BaseHandler), либо подклассами `BaseHandler` (в этом случае должна быть возможность вызвать конструктор без параметров). Экземпляры следующих классов будут помещены перед *обработчик*ами, если только *обработчик*и не содержат их, их экземпляры или подклассы: [`ProxyHandler`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.ProxyHandler) (если обнаружены настройки прокси), [`UnknownHandler`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.UnknownHandler), [`HTTPHandler`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.HTTPHandler), [`HTTPDefaultErrorHandler`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.HTTPDefaultErrorHandler), [`HTTPRedirectHandler`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.HTTPRedirectHandler), [`FTPHandler`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.FTPHandler), [`FileHandler`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.FileHandler), [`HTTPErrorProcessor`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.HTTPErrorProcessor).7879Если установка Python поддерживает SSL (т.е. если модуль [`ssl`](https://python-all.ru/3.16/library/ssl.html#module-ssl) может быть импортирован), [`HTTPSHandler`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.HTTPSHandler) также будет добавлен.8081Подкласс [`BaseHandler`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.BaseHandler) также может изменить свой атрибут `handler_order`, чтобы изменить свою позицию в списке обработчиков.8283#### `urllib.request.pathname2url(path, *, add_scheme=False)`8485Преобразует указанный локальный путь в URL `file:`. Для кодирования пути используется функция [`quote()`](https://python-all.ru/3.16/library/urllib.parse.html#urllib.parse.quote).8687Если *add\_scheme* равен false (по умолчанию), возвращаемое значение не включает префикс схемы `file:`. Задайте *add\_scheme* равным true, чтобы вернуть полный URL.8889В этом примере показано использование функции в Windows:9091```python92>>> from urllib.request import pathname2url93>>> path = 'C:\\Program Files'94>>> pathname2url(path, add_scheme=True)95'file:///C:/Program%20Files'96```9798Изменено в версии 3.14: Буквы дисков Windows больше не преобразуются в верхний регистр, а символы `:`, не следующие за буквой диска, больше не вызывают исключение [`OSError`](https://python-all.ru/3.16/library/exceptions.html#OSError) в Windows.99100Изменено в версии 3.14: Пути, начинающиеся с косой черты, преобразуются в URL с компонентом authority. Например, путь `/etc/hosts` преобразуется в URL `///etc/hosts`.101102Изменено в версии 3.14: Был добавлен параметр *add\_scheme*.103104#### `urllib.request.url2pathname(url, *, require_scheme=False, resolve_host=False)`105106Преобразует указанный URL `file:` в локальный путь. Для декодирования URL используется [`unquote()`](https://python-all.ru/3.16/library/urllib.parse.html#urllib.parse.unquote).107108Если *require\_scheme* равен false (по умолчанию), указанное значение должно не включать префикс схемы `file:`. Если *require\_scheme* задан как true, указанное значение должно включать префикс; в противном случае возбуждается исключение [`URLError`](https://python-all.ru/3.16/library/urllib.error.html#urllib.error.URLError).109110The URL authority is discarded if it is empty, `localhost`, or the local hostname. Otherwise, if *resolve\_host* is set to true, the authority is resolved using [`socket.gethostbyname()`](https://python-all.ru/3.16/library/socket.html#socket.gethostbyname) and discarded if it matches a local IP address (as per [**RFC 8089 §3**](https://python-all.ru/3.16/library/urllib.request.html)). If the authority is still unhandled, then on Windows a UNC path is returned, and on other platforms a [`URLError`](https://python-all.ru/3.16/library/urllib.error.html#urllib.error.URLError) is raised.111112В этом примере показано использование функции в Windows:113114```python115>>> from urllib.request import url2pathname116>>> url = 'file:///C:/Program%20Files'117>>> url2pathname(url, require_scheme=True)118'C:\\Program Files'119```120121Изменено в версии 3.14: Буквы дисков Windows больше не преобразуются в верхний регистр, а символы `:`, не следующие за буквой диска, больше не вызывают исключение [`OSError`](https://python-all.ru/3.16/library/exceptions.html#OSError) в Windows.122123Изменено в версии 3.14: Authority URL отбрасывается, если оно совпадает с локальным именем хоста. В противном случае, если authority не пусто и не равно `localhost`, то в Windows возвращается UNC-путь (как и раньше), а на других платформах возбуждается [`URLError`](https://python-all.ru/3.16/library/urllib.error.html#urllib.error.URLError).124125Изменено в версии 3.14: Компоненты запроса и фрагмента URL отбрасываются, если они присутствуют.126127Изменено в версии 3.14: Были добавлены параметры *require\_scheme* и *resolve\_host*.128129#### `urllib.request.getproxies()`130131Эта вспомогательная функция возвращает словарь, отображающий схему в URL прокси-сервера. Она сканирует окружение на наличие переменных с именем `<scheme>_proxy`, без учёта регистра, сначала для всех операционных систем, а если не удаётся найти, ищет информацию о прокси в System Configuration для macOS и в реестре Windows для Windows. Если существуют и переменные в нижнем, и в верхнем регистре (и они различаются), предпочтение отдаётся нижнему регистру.132133> **Примечание**134>135> Если установлена переменная окружения `REQUEST_METHOD`, что обычно указывает на выполнение скрипта в CGI-среде, переменная окружения `HTTP_PROXY` (в верхнем регистре `_PROXY`) будет проигнорирована. Это связано с тем, что эта переменная может быть вставлена клиентом через HTTP-заголовок «Proxy:». Если необходимо использовать HTTP-прокси в CGI-среде, либо явно используйте `ProxyHandler`, либо убедитесь, что имя переменной указано в нижнем регистре (или, по крайней мере, суффикс `_proxy`).136137Предоставляются следующие классы:138139#### `class urllib.request.Request(url, data=None, headers={}, origin_req_host=None, unverifiable=False, method=None)`140141Этот класс представляет абстракцию URL-запроса.142143*url* должен быть строкой, содержащей корректный, правильно закодированный URL.144145*data* must be an object specifying additional data to send to the server, or `None` if no such data is needed. Currently HTTP requests are the only ones that use *data*. The supported object types include bytes, file-like objects, and iterables of bytes-like objects. If no `Content-Length` nor `Transfer-Encoding` header field has been provided, [`HTTPHandler`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.HTTPHandler) will set these headers according to the type of *data*. `Content-Length` will be used to send bytes objects, while `Transfer-Encoding: chunked` as specified in [**RFC 7230**](https://python-all.ru/3.16/library/urllib.request.html), Section 3.3.1 will be used to send files and other iterables.146147Для метода запроса HTTP POST *data* должен быть буфером в стандартном формате *application/x-www-form-urlencoded*. Функция [`urllib.parse.urlencode()`](https://python-all.ru/3.16/library/urllib.parse.html#urllib.parse.urlencode) принимает отображение или последовательность кортежей из двух элементов и возвращает строку ASCII в этом формате. Перед использованием в качестве параметра *data* её следует закодировать в байты.148149*headers* должен быть словарём, и будет обрабатываться так, как если бы [`add_header()`](https://python-all.ru/3.16/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`](https://python-all.ru/3.16/library/urllib.html#module-urllib) – `"Python-urllib/2.6"` (в Python 2.6). Все ключи заголовков отправляются в верблюжьем регистре.150151Подходящий заголовок `Content-Type` следует включить, если присутствует аргумент *data*. Если этот заголовок не был предоставлен и *data* не равен `None`, по умолчанию будет добавлен `Content-Type: application/x-www-form-urlencoded`.152153Следующие два аргумента представляют интерес только для корректной обработки сторонних HTTP-куки:154155*origin\_req\_host* should be the request-host of the origin transaction, as defined by [**RFC 2965**](https://python-all.ru/3.16/library/urllib.request.html). It defaults to `http.cookiejar.request_host(self)`. This is the host name or IP address of the original request that was initiated by the user. For example, if the request is for an image in an HTML document, this should be the request-host of the request for the page containing the image.156157*unverifiable* should indicate whether the request is unverifiable, as defined by [**RFC 2965**](https://python-all.ru/3.16/library/urllib.request.html). It defaults to `False`. An unverifiable request is one whose URL the user did not have the option to approve. For example, if the request is for an image in an HTML document, and the user had no option to approve the automatic fetching of the image, this should be true.158159*method* должен быть строкой, указывающей метод HTTP-запроса, который будет использоваться (например, `'HEAD'`). Если указан, его значение сохраняется в атрибуте [`method`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.Request.method) и используется [`get_method()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.Request.get_method). По умолчанию используется `'GET'`, если *data* равен `None`, и `'POST'` в противном случае. Подклассы могут указать другой метод по умолчанию, установив атрибут `method` в самом классе.160161> **Примечание**162>163> Запрос не будет работать должным образом, если объект data не может предоставить своё содержимое более одного раза (например, файл или итерируемый объект, который может создать содержимое только один раз), и запрос повторяется из-за HTTP-перенаправлений или аутентификации. *data* отправляется на HTTP-сервер сразу после заголовков. В библиотеке нет поддержки ожидания 100-continue.164165Изменено в версии 3.3: Добавлен аргумент [`Request.method`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.Request.method) в класс Request.166167Изменено в версии 3.4: Метод по умолчанию [`Request.method`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.Request.method) может быть указан на уровне класса.168169Изменено в версии 3.6: Не вызывать ошибку, если `Content-Length` не был предоставлен, а *data* не является ни `None`, ни объектом bytes. Вместо этого использовать чанкованное кодирование передачи.170171#### `class urllib.request.OpenerDirector`172173Класс `OpenerDirector` открывает URL-адреса через цепочку [`BaseHandler`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.BaseHandler). Он управляет объединением обработчиков в цепочку и восстановлением после ошибок.174175#### `class urllib.request.BaseHandler`176177Это базовый класс для всех зарегистрированных обработчиков – он отвечает только за простую механику регистрации.178179#### `class urllib.request.HTTPDefaultErrorHandler`180181Класс, определяющий обработчик по умолчанию для HTTP-ответов с ошибками; все ответы преобразуются в исключения [`HTTPError`](https://python-all.ru/3.16/library/urllib.error.html#urllib.error.HTTPError).182183#### `class urllib.request.HTTPRedirectHandler`184185Класс для обработки перенаправлений.186187#### `class urllib.request.HTTPCookieProcessor(cookiejar=None)`188189Класс для обработки HTTP-куки.190191#### `class urllib.request.ProxyHandler(proxies=None)`192193Заставляет запросы проходить через прокси. Если передан *proxies*, это должен быть словарь, сопоставляющий имена протоколов с URL-адресами прокси. По умолчанию список прокси читается из переменных окружения `<protocol>_proxy`. Если переменные окружения для прокси не заданы, то в среде Windows настройки прокси берутся из раздела Internet Settings реестра, а в среде macOS информация о прокси извлекается из System Configuration Framework.194195Чтобы отключить автоматически обнаруженный прокси, передайте пустой словарь.196197Переменная окружения `no_proxy` может использоваться для указания узлов, к которым не следует обращаться через прокси; если она задана, то должна представлять собой разделённый запятыми список суффиксов имён узлов, опционально с добавленным `:port`, например `cern.ch,ncsa.uiuc.edu,some.host:8080`.198199> **Примечание**200>201> `HTTP_PROXY` будет игнорироваться, если задана переменная `REQUEST_METHOD`; см. документацию по [`getproxies()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.getproxies).202203#### `class urllib.request.HTTPPasswordMgr`204205Хранит базу данных соответствий `(realm, uri) -> (user, password)`.206207#### `class urllib.request.HTTPPasswordMgrWithDefaultRealm`208209Хранит базу данных соответствий `(realm, uri) -> (user, password)`. Область (realm) `None` считается универсальной областью, которая используется, если не подходит ни одна другая.210211#### `class urllib.request.HTTPPasswordMgrWithPriorAuth`212213Вариант [`HTTPPasswordMgrWithDefaultRealm`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.HTTPPasswordMgrWithDefaultRealm), который также содержит базу данных соответствий `uri -> is_authenticated`. Может использоваться обработчиком BasicAuth для определения, когда отправлять учётные данные аутентификации немедленно, не дожидаясь сначала ответа `401`.214215Добавлено в версии 3.5.216217#### `class urllib.request.AbstractBasicAuthHandler(password_mgr=None)`218219Это миксин-класс, который помогает с HTTP-аутентификацией как на удалённом хосте, так и через прокси. Если передан *password\_mgr*, он должен быть совместимым с [`HTTPPasswordMgr`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.HTTPPasswordMgr); обратитесь к разделу [HTTPPasswordMgr Objects](https://python-all.ru/3.16/library/urllib.request.html#http-password-mgr) для получения информации об интерфейсе, который необходимо поддерживать. Если *passwd\_mgr* также предоставляет методы `is_authenticated` и `update_authenticated` (см. [HTTPPasswordMgrWithPriorAuth Objects](https://python-all.ru/3.16/library/urllib.request.html#http-password-mgr-with-prior-auth)), то обработчик будет использовать результат `is_authenticated` для заданного URI, чтобы определить, следует ли отправлять учётные данные аутентификации вместе с запросом. Если `is_authenticated` возвращает `True` для URI, учётные данные отправляются. Если `is_authenticated` равно `False`, учётные данные не отправляются, и после получения ответа `401` запрос отправляется повторно с учётными данными аутентификации. Если аутентификация прошла успешно, вызывается `update_authenticated` для установки `is_authenticated` `True` для URI, так что последующие запросы к этому URI или любым его супер-URI будут автоматически включать учётные данные аутентификации.220221Добавлено в версии 3.5: Добавлена поддержка `is_authenticated`.222223#### `class urllib.request.HTTPBasicAuthHandler(password_mgr=None)`224225Обрабатывает аутентификацию на удалённом хосте. Если передан *password\_mgr*, он должен быть совместим с [`HTTPPasswordMgr`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.HTTPPasswordMgr); обратитесь к разделу [HTTPPasswordMgr Objects](https://python-all.ru/3.16/library/urllib.request.html#http-password-mgr) для получения информации об интерфейсе, который необходимо поддерживать. HTTPBasicAuthHandler вызовет [`ValueError`](https://python-all.ru/3.16/library/exceptions.html#ValueError) при получении неправильной схемы аутентификации.226227#### `class urllib.request.ProxyBasicAuthHandler(password_mgr=None)`228229Управляет аутентификацией с прокси. *password\_mgr*, если указан, должен быть совместим с [`HTTPPasswordMgr`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.HTTPPasswordMgr); обращайтесь к разделу [HTTPPasswordMgr Objects](https://python-all.ru/3.16/library/urllib.request.html#http-password-mgr) за информацией об интерфейсе, который должен поддерживаться.230231#### `class urllib.request.AbstractDigestAuthHandler(password_mgr=None)`232233Это миксин-класс, который помогает с HTTP-аутентификацией как на удалённом хосте, так и через прокси. Если передан *password\_mgr*, он должен быть совместимым с [`HTTPPasswordMgr`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.HTTPPasswordMgr); обратитесь к разделу [HTTPPasswordMgr Objects](https://python-all.ru/3.16/library/urllib.request.html#http-password-mgr) для получения информации об интерфейсе, который необходимо поддерживать.234235Изменено в версии 3.14: Добавлена поддержка алгоритма дайджест-аутентификации HTTP `SHA-256`.236237#### `class urllib.request.HTTPDigestAuthHandler(password_mgr=None)`238239Управляет аутентификацией с удалённым хостом. *password\_mgr*, если указан, должен быть совместим с [`HTTPPasswordMgr`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.HTTPPasswordMgr); обращайтесь к разделу [HTTPPasswordMgr Objects](https://python-all.ru/3.16/library/urllib.request.html#http-password-mgr) за информацией об интерфейсе, который должен поддерживаться. Когда добавлены обработчик дайджест-аутентификации (Digest Authentication Handler) и обработчик базовой аутентификации (Basic Authentication Handler), дайджест-аутентификация всегда выполняется первой. Если дайджест-аутентификация снова возвращает ответ 40x, он передаётся обработчику базовой аутентификации. Этот метод обработчика вызовет исключение [`ValueError`](https://python-all.ru/3.16/library/exceptions.html#ValueError) при использовании схемы аутентификации, отличной от Digest или Basic.240241Изменено в версии 3.3: Возбуждает исключение [`ValueError`](https://python-all.ru/3.16/library/exceptions.html#ValueError) при неподдерживаемой схеме аутентификации.242243#### `class urllib.request.ProxyDigestAuthHandler(password_mgr=None)`244245Управляет аутентификацией с прокси. *password\_mgr*, если указан, должен быть совместим с [`HTTPPasswordMgr`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.HTTPPasswordMgr); обращайтесь к разделу [HTTPPasswordMgr Objects](https://python-all.ru/3.16/library/urllib.request.html#http-password-mgr) за информацией об интерфейсе, который должен поддерживаться.246247#### `class urllib.request.HTTPHandler`248249Класс для открытия HTTP-URL.250251#### `class urllib.request.HTTPSHandler(debuglevel=0, context=None, check_hostname=None)`252253Класс для открытия HTTPS-URL. *context* и *check\_hostname* имеют то же значение, что и в [`http.client.HTTPSConnection`](https://python-all.ru/3.16/library/http.client.html#http.client.HTTPSConnection).254255Изменено в версии 3.2: Добавлены параметры *context* и *check\_hostname*.256257#### `class urllib.request.FileHandler`258259Открывает локальные файлы.260261#### `class urllib.request.DataHandler`262263Открывает data-URL.264265Добавлено в версии 3.4.266267#### `class urllib.request.FTPHandler`268269Открывает FTP-URL.270271#### `class urllib.request.CacheFTPHandler`272273Открывает FTP-URL, сохраняя кеш открытых FTP-соединений для минимизации задержек.274275#### `class urllib.request.UnknownHandler`276277Универсальный класс для обработки неизвестных URL.278279#### `class urllib.request.HTTPErrorProcessor`280281Обрабатывает ошибочные HTTP-ответы.282283## Объекты запроса284285Следующие методы описывают открытый интерфейс [`Request`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.Request), поэтому все они могут быть переопределены в подклассах. Также определяет несколько открытых атрибутов, которые могут использоваться клиентами для анализа разобранного запроса.286287#### `Request.full_url`288289Оригинальный URL, переданный конструктору.290291Изменено в версии 3.4.292293Request.full\_url – это свойство с сеттером, геттером и делитером. При получении `full_url` возвращает оригинальный URL запроса вместе с фрагментом, если он присутствовал.294295#### `Request.type`296297Схема URI.298299#### `Request.host`300301Авторитетная часть URI, обычно хост, но может также содержать порт, отделённый двоеточием.302303#### `Request.origin_req_host`304305Исходный хост запроса, без порта.306307#### `Request.selector`308309Путь URI. Если [`Request`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.Request) использует прокси, то selector будет содержать полный URL, который передаётся прокси.310311#### `Request.data`312313Тело сущности запроса или `None`, если не задано.314315Изменено в версии 3.4: Изменение значения `Request.data` теперь удаляет заголовок “Content-Length” , если он был ранее установлен или вычислен.316317#### `Request.unverifiable`318319логическое значение, указывает, является ли запрос непроверяемым, как определено в [**RFC 2965**](https://python-all.ru/3.16/library/urllib.request.html).320321#### `Request.method`322323HTTP-метод запроса. По умолчанию его значение равно [`None`](https://python-all.ru/3.16/library/constants.html#None), что означает, что [`get_method()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.Request.get_method) выполнит обычное вычисление метода. Значение можно задать (тем самым переопределив вычисление по умолчанию в `get_method()`), либо установив значение по умолчанию на уровне класса в подклассе [`Request`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.Request), либо передав значение в конструктор `Request` через аргумент *method*.324325Добавлено в версии 3.3.326327Изменено в версии 3.4: Теперь значение по умолчанию можно задавать в подклассах; ранее его можно было установить только через аргумент конструктора.328329#### `Request.get_method()`330331Возвращает строку, указывающую HTTP-метод запроса. Если [`Request.method`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.Request.method) не равно `None`, возвращается его значение; иначе возвращается `'GET'`, если [`Request.data`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.Request.data) равно `None`, или `'POST'` в противном случае. Это имеет смысл только для HTTP-запросов.332333Изменено в версии 3.3: get\_method теперь учитывает значение [`Request.method`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.Request.method).334335#### `Request.add_header(key, val)`336337Добавляет ещё один заголовок в запрос. В настоящее время заголовки игнорируются всеми обработчиками, кроме HTTP-обработчиков, где они добавляются в список заголовков, отправляемых серверу. Обратите внимание, что не может быть более одного заголовка с одним и тем же именем, и последующие вызовы перезаписывают предыдущие, если *key* совпадает. В настоящее время это не приводит к потере функциональности HTTP, поскольку все заголовки, которые имеют смысл при многократном использовании, имеют (заголовок-специфичный) способ достижения той же функциональности с помощью только одного заголовка. Обратите внимание, что заголовки, добавленные этим методом, также добавляются в перенаправленные запросы.338339#### `Request.add_unredirected_header(key, header)`340341Добавляет заголовок, который не будет добавлен в перенаправленный запрос.342343#### `Request.has_header(header)`344345Возвращает, имеет ли экземпляр указанный заголовок (проверяет как обычные, так и неперенаправленные).346347#### `Request.remove_header(header)`348349Удаляет указанный заголовок из экземпляра запроса (как из обычных, так и из неперенаправленных заголовков).350351Добавлено в версии 3.4.352353#### `Request.get_full_url()`354355Возвращает URL, переданный в конструктор.356357Изменено в версии 3.4.358359Возвращает [`Request.full_url`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.Request.full_url)360361#### `Request.set_proxy(host, type)`362363Подготавливает запрос, подключаясь к прокси-серверу. *host* и *type* заменят соответствующие значения экземпляра, а selector экземпляра будет содержать исходный URL, переданный в конструктор.364365#### `Request.get_header(header_name, default=None)`366367Возвращает значение указанного заголовка. Если заголовок отсутствует, возвращает значение по умолчанию.368369#### `Request.header_items()`370371Возвращает список кортежей (имя\_заголовка, значение\_заголовка) заголовков запроса.372373Изменено в версии 3.4:Методы запроса add\_data, has\_data, get\_data, get\_type, get\_host, get\_selector, get\_origin\_req\_host и is\_unverifiable, которые были объявлены устаревшими начиная с версии 3.3, удалены.374375## Объекты OpenerDirector376377Экземпляры [`OpenerDirector`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.OpenerDirector) имеют следующие методы:378379#### `OpenerDirector.add_handler(handler)`380381*handler* должен быть экземпляром [`BaseHandler`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.BaseHandler). Поиск осуществляется среди следующих методов, и они добавляются в возможные цепочки (обратите внимание: ошибки HTTP являются особым случаем). Обратите внимание, что в следующих методах *протокол* следует заменить на фактический обрабатываемый протокол, например `http_response()` будет обработчиком ответа протокола HTTP. Кроме того, *type* следует заменить на фактический код HTTP, например `http_error_404()` будет обрабатывать ошибки HTTP 404.382383- `<protocol>_open()` – сигнал о том, что обработчик умеет открывать URL *протокол*.384385  Подробнее см. [`BaseHandler.<protocol>_open()`](https://python-all.ru/3.16/library/urllib.request.html#protocol-open).386- `http_error_<type>()` – сигнал о том, что обработчик умеет обрабатывать ошибки HTTP с кодом ошибки HTTP *type*.387388  Подробнее см. [`BaseHandler.http_error_<nnn>()`](https://python-all.ru/3.16/library/urllib.request.html#http-error-nnn).389- `<protocol>_error()` – сигнал о том, что обработчик умеет обрабатывать ошибки от (не-`http`) *протокол*.390- `<protocol>_request()` – сигнал о том, что обработчик умеет предварительно обрабатывать запросы *протокол*.391392  Подробнее см. [`BaseHandler.<protocol>_request()`](https://python-all.ru/3.16/library/urllib.request.html#protocol-request).393- `<protocol>_response()` – сигнал о том, что обработчик умеет постобрабатывать ответы *протокол*.394395  Подробнее см. [`BaseHandler.<protocol>_response()`](https://python-all.ru/3.16/library/urllib.request.html#protocol-response).396397#### `OpenerDirector.open(url, data=None[, timeout])`398399Открывает указанный *url* (который может быть объектом запроса или строкой), при необходимости передавая указанные *data*. Аргументы, возвращаемые значения и вызываемые исключения такие же, как у [`urlopen()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.urlopen) (который просто вызывает метод `open()` текущего установленного глобального [`OpenerDirector`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.OpenerDirector)). Необязательный параметр *timeout* задаёт тайм-аут в секундах для блокирующих операций, таких как попытка подключения (если не указан, будет использоваться глобальная настройка тайм-аута по умолчанию). Функция тайм-аута на самом деле работает только для HTTP, HTTPS и FTP соединений.400401#### `OpenerDirector.error(proto, *args)`402403Обрабатывает ошибку указанного протокола. Вызывает зарегистрированные обработчики ошибок для данного протокола с указанными аргументами (зависящими от протокола). Протокол HTTP является особым случаем: для определения конкретного обработчика ошибок используется код ответа HTTP; обратитесь к методам `http_error_<type>()` классов обработчиков.404405Возвращаемые значения и вызываемые исключения такие же, как у [`urlopen()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.urlopen).406407Объекты OpenerDirector открывают URL в три этапа:408409Порядок вызова этих методов в каждом этапе определяется сортировкой экземпляров обработчиков.4104111. Каждый обработчик, имеющий метод с именем `<protocol>_request()`, вызывает этот метод для предварительной обработки запроса.4122. Обработчики, имеющие метод с именем `<protocol>_open()`, вызываются для обработки запроса. Этот этап завершается, когда обработчик либо возвращает значение, отличное от [`None`](https://python-all.ru/3.16/library/constants.html#None) (т.е. ответ), либо вызывает исключение (обычно [`URLError`](https://python-all.ru/3.16/library/urllib.error.html#urllib.error.URLError)). Исключения могут распространяться дальше.413414   На самом деле, описанный выше алгоритм сначала применяется для методов с именем [`default_open()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.BaseHandler.default_open). Если все такие методы возвращают [`None`](https://python-all.ru/3.16/library/constants.html#None), алгоритм повторяется для методов с именем `<protocol>_open()`. Если все такие методы возвращают `None`, алгоритм повторяется для методов с именем [`unknown_open()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.BaseHandler.unknown_open).415416   Обратите внимание, что реализация этих методов может включать вызовы методов [`open()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.OpenerDirector.open) и [`error()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.OpenerDirector.error) родительского экземпляра [`OpenerDirector`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.OpenerDirector).4173. Каждый обработчик, имеющий метод с именем `<protocol>_response()`, вызывает этот метод для постобработки ответа.418419## Объекты BaseHandler420421Объекты [`BaseHandler`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.BaseHandler) предоставляют несколько методов, которые непосредственно полезны, а также другие методы, предназначенные для использования производными классами. Они предназначены для прямого использования:422423#### `BaseHandler.add_parent(director)`424425Добавляет директор в качестве родителя.426427#### `BaseHandler.close()`428429Удаляет всех родителей.430431Следующие атрибут и методы должны использоваться только классами, производными от [`BaseHandler`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.BaseHandler).432433> **Примечание**434>435> Принято соглашение, что подклассы, определяющие методы `<protocol>_request()` или `<protocol>_response()`, называются `*Processor`; все остальные называются `*Handler`.436437#### `BaseHandler.parent`438439Действительный [`OpenerDirector`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.OpenerDirector), который можно использовать для открытия через другой протокол или для обработки ошибок.440441#### `BaseHandler.default_open(req)`442443Этот метод *не* определён в [`BaseHandler`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.BaseHandler), но подклассы должны определить его, если хотят перехватывать все URL.444445Если этот метод реализован, он будет вызван родительским [`OpenerDirector`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.OpenerDirector). Он должен возвращать файлоподобный объект, как описано в возвращаемом значении метода [`open()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.OpenerDirector.open) класса `OpenerDirector`, или `None`. Он должен вызывать исключение [`URLError`](https://python-all.ru/3.16/library/urllib.error.html#urllib.error.URLError), если не происходит действительно исключительной ситуации (например, [`MemoryError`](https://python-all.ru/3.16/library/exceptions.html#MemoryError) не должен отображаться на `URLError`).446447Этот метод будет вызван перед любым методом открытия, специфичным для протокола.448449#### `BaseHandler.<protocol>_open(req)`450451Этот метод *не* определён в [`BaseHandler`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.BaseHandler), но подклассы должны определить его, если хотят обрабатывать URL с указанным протоколом.452453Если этот метод определён, он будет вызван родительским [`OpenerDirector`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.OpenerDirector). Возвращаемые значения должны быть такими же, как для [`default_open()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.BaseHandler.default_open).454455#### `BaseHandler.unknown_open(req)`456457Этот метод *не* определён в [`BaseHandler`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.BaseHandler), но подклассы должны определить его, если хотят перехватывать все URL, для которых нет зарегистрированного обработчика для открытия.458459Если этот метод реализован, он будет вызван [`parent`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.BaseHandler.parent) [`OpenerDirector`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.OpenerDirector). Возвращаемые значения должны быть такими же, как для [`default_open()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.BaseHandler.default_open).460461#### `BaseHandler.http_error_default(req, fp, code, msg, hdrs)`462463Этот метод *не* определён в [`BaseHandler`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.BaseHandler), но подклассы должны переопределить его, если они намерены обеспечить всеобъемлющую обработку для иначе необработанных HTTP-ошибок. Он будет автоматически вызван [`OpenerDirector`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.OpenerDirector) при получении ошибки и обычно не должен вызываться в других обстоятельствах.464465[`OpenerDirector`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.OpenerDirector) вызовет этот метод с пятью позиционными аргументами:4664671. объект [`Request`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.Request),4682. файлоподобный объект с телом HTTP-ошибки,4693. трёхзначный код ошибки в виде строки,4704. понятное пользователю объяснение кода в виде строки и4715. заголовки ошибки в виде объекта отображения.472473Возвращаемые значения и вызываемые исключения должны быть такими же, как у [`urlopen()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.urlopen).474475#### `BaseHandler.http_error_<nnn>(req, fp, code, msg, hdrs)`476477*nnn* должен быть трёхзначным HTTP-кодом ошибки. Этот метод также не определён в [`BaseHandler`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.BaseHandler), но будет вызван, если он существует, на экземпляре подкласса, когда возникает HTTP-ошибка с кодом *nnn*.478479Подклассы должны переопределить этот метод для обработки конкретных HTTP-ошибок.480481Аргументы, возвращаемые значения и вызываемые исключения должны быть такими же, как для [`http_error_default()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.BaseHandler.http_error_default).482483#### `BaseHandler.<protocol>_request(req)`484485Этот метод *не* определён в [`BaseHandler`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.BaseHandler), но подклассы должны определить его, если хотят предварительно обрабатывать запросы заданного протокола.486487Если этот метод определён, он будет вызван родительским [`OpenerDirector`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.OpenerDirector). *req* будет объектом [`Request`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.Request). Возвращаемое значение должно быть объектом `Request`.488489#### `BaseHandler.<protocol>_response(req, response)`490491Этот метод *не* определён в [`BaseHandler`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.BaseHandler), но подклассы должны определить его, если хотят выполнять постобработку ответов заданного протокола.492493Этот метод, если он определён, будет вызван родительским [`OpenerDirector`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.OpenerDirector). *req* будет объектом [`Request`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.Request). *response* будет объектом, реализующим тот же интерфейс, что и возвращаемое значение [`urlopen()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.urlopen). Возвращаемое значение должно реализовывать тот же интерфейс, что и возвращаемое значение `urlopen()`.494495## Объекты HTTPRedirectHandler496497> **Примечание**498>499> Некоторые HTTP-перенаправления требуют действий от клиентского кода этого модуля. В таком случае возбуждается [`HTTPError`](https://python-all.ru/3.16/library/urllib.error.html#urllib.error.HTTPError). См. [**RFC 2616**](https://python-all.ru/3.16/library/urllib.request.html) для подробностей о точном значении различных кодов перенаправления.500>501> Исключение [`HTTPError`](https://python-all.ru/3.16/library/urllib.error.html#urllib.error.HTTPError), возбуждаемое по соображениям безопасности, если HTTPRedirectHandler получает URL перенаправления, который не является HTTP, HTTPS или FTP URL.502503#### `HTTPRedirectHandler.redirect_request(req, fp, code, msg, hdrs, newurl)`504505Возвращает [`Request`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.Request) или `None` в ответ на перенаправление. Этот метод вызывается реализациями по умолчанию методов `http_error_30*()`, когда от сервера получено перенаправление. Если перенаправление должно произойти, верните новый `Request`, чтобы `http_error_30*()` смог выполнить перенаправление на *newurl*. В противном случае возбудите [`HTTPError`](https://python-all.ru/3.16/library/urllib.error.html#urllib.error.HTTPError), если никакой другой обработчик не должен пытаться обработать этот URL, или верните `None`, если вы не можете, но другой обработчик смог бы.506507> **Примечание**508>509> Реализация по умолчанию этого метода не следует строго [**RFC 2616**](https://python-all.ru/3.16/library/urllib.request.html), который говорит, что ответы 301 и 302 на запросы `POST` не должны автоматически перенаправляться без подтверждения пользователем. В действительности браузеры разрешают автоматическое перенаправление таких ответов, меняя POST на `GET`, и реализация по умолчанию воспроизводит такое поведение.510511#### `HTTPRedirectHandler.http_error_301(req, fp, code, msg, hdrs)`512513Перенаправляет на URL `Location:` или `URI:`. Этот метод вызывается родительским [`OpenerDirector`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.OpenerDirector) при получении HTTP-ответа «Moved Permanently».514515#### `HTTPRedirectHandler.http_error_302(req, fp, code, msg, hdrs)`516517То же, что и [`http_error_301()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.HTTPRedirectHandler.http_error_301), но вызывается для ответа «Found».518519#### `HTTPRedirectHandler.http_error_303(req, fp, code, msg, hdrs)`520521То же, что и [`http_error_301()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.HTTPRedirectHandler.http_error_301), но вызывается для ответа «See Other».522523#### `HTTPRedirectHandler.http_error_307(req, fp, code, msg, hdrs)`524525То же, что и [`http_error_301()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.HTTPRedirectHandler.http_error_301), но вызывается для ответа «Temporary Redirect». Не разрешает изменять метод запроса с `POST` на `GET`.526527#### `HTTPRedirectHandler.http_error_308(req, fp, code, msg, hdrs)`528529То же, что и [`http_error_301()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.HTTPRedirectHandler.http_error_301), но вызывается для ответа «Permanent Redirect». Не разрешает изменять метод запроса с `POST` на `GET`.530531Добавлено в версии 3.12.532533## Объекты HTTPCookieProcessor534535Экземпляры [`HTTPCookieProcessor`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.HTTPCookieProcessor) имеют один атрибут:536537#### `HTTPCookieProcessor.cookiejar`538539[`http.cookiejar.CookieJar`](https://python-all.ru/3.16/library/http.cookiejar.html#http.cookiejar.CookieJar), в котором хранятся куки.540541## Объекты ProxyHandler542543#### `ProxyHandler.<protocol>_open(request)`544545Объект [`ProxyHandler`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.ProxyHandler) будет иметь метод `<protocol>_open()` для каждого *протокол*, для которого есть прокси в словаре *proxies*, переданном в конструктор. Метод будет изменять запросы для прохождения через прокси, вызывая `request.set_proxy()`, и вызывать следующий обработчик в цепочке для непосредственного выполнения протокола.546547## Объекты HTTPPasswordMgr548549Эти методы доступны у объектов [`HTTPPasswordMgr`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.HTTPPasswordMgr) и [`HTTPPasswordMgrWithDefaultRealm`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.HTTPPasswordMgrWithDefaultRealm).550551#### `HTTPPasswordMgr.add_password(realm, uri, user, passwd)`552553*uri* может быть как одним URI, так и последовательностью URI. *realm*, *user* и *passwd* должны быть строками. В результате `(user, passwd)` будет использоваться в качестве токенов аутентификации, когда запрашивается аутентификация для *realm* и супер-URI любого из заданных URI.554555#### `HTTPPasswordMgr.find_user_password(realm, authuri)`556557Получает имя пользователя/пароль для заданных realm и URI, если они есть. Этот метод вернёт `(None, None)`, если нет соответствующей пары пользователь/пароль.558559Для объектов [`HTTPPasswordMgrWithDefaultRealm`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.HTTPPasswordMgrWithDefaultRealm) область `None` будет проверена, если заданная *realm* не имеет соответствующей пары пользователь/пароль.560561## Объекты HTTPPasswordMgrWithPriorAuth562563Этот менеджер паролей расширяет [`HTTPPasswordMgrWithDefaultRealm`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.HTTPPasswordMgrWithDefaultRealm), чтобы поддерживать отслеживание URI, для которых учётные данные аутентификации должны всегда отправляться.564565#### `HTTPPasswordMgrWithPriorAuth.add_password(realm, uri, user, passwd, is_authenticated=False)`566567*realm*, *uri*, *user*, *passwd* – как и для [`HTTPPasswordMgr.add_password()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.HTTPPasswordMgr.add_password). *is\_authenticated* устанавливает начальное значение флага `is_authenticated` для указанного URI или списка URI. Если *is\_authenticated* указан как `True`, *realm* игнорируется.568569#### `HTTPPasswordMgrWithPriorAuth.find_user_password(realm, authuri)`570571То же, что и для объектов [`HTTPPasswordMgrWithDefaultRealm`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.HTTPPasswordMgrWithDefaultRealm)572573#### `HTTPPasswordMgrWithPriorAuth.update_authenticated(self, uri, is_authenticated=False)`574575Обновляет флаг `is_authenticated` для указанного *uri* или списка URI.576577#### `HTTPPasswordMgrWithPriorAuth.is_authenticated(self, authuri)`578579Возвращает текущее состояние флага `is_authenticated` для указанного URI.580581## Объекты AbstractBasicAuthHandler582583#### `AbstractBasicAuthHandler.http_error_auth_reqed(authreq, host, req, headers)`584585Обрабатывает запрос аутентификации, получая пару пользователь/пароль и повторяя запрос. *authreq* должен быть именем заголовка, в котором содержится информация о realm в запросе, *host* указывает URL и путь для аутентификации, *req* должен быть (неудачным) объектом [`Request`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.Request), а *headers* – заголовками ошибки.586587*host* – это либо authority (например, `"python.org"`), либо URL, содержащий компонент authority (например, `"https://python.org/"`). В любом случае, authority не должен содержать компонент userinfo (поэтому `"python.org"` и `"python.org:80"` подходят, а `"joe:password@python.org"` – нет).588589## Объекты HTTPBasicAuthHandler590591#### `HTTPBasicAuthHandler.http_error_401(req, fp, code, msg, hdrs)`592593Повторяет запрос с информацией аутентификации, если она доступна.594595## Объекты ProxyBasicAuthHandler596597#### `ProxyBasicAuthHandler.http_error_407(req, fp, code, msg, hdrs)`598599Повторяет запрос с информацией аутентификации, если она доступна.600601## Объекты AbstractDigestAuthHandler602603#### `AbstractDigestAuthHandler.http_error_auth_reqed(authreq, host, req, headers)`604605*authreq* должен быть именем заголовка, в котором содержится информация о realm в запросе, *host* должен быть хостом для аутентификации, *req* должен быть (неудачным) объектом [`Request`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.Request), а *headers* – заголовками ошибки.606607## Объекты HTTPDigestAuthHandler608609#### `HTTPDigestAuthHandler.http_error_401(req, fp, code, msg, hdrs)`610611Повторяет запрос с информацией аутентификации, если она доступна.612613## Объекты ProxyDigestAuthHandler614615#### `ProxyDigestAuthHandler.http_error_407(req, fp, code, msg, hdrs)`616617Повторяет запрос с информацией аутентификации, если она доступна.618619## Объекты HTTPHandler620621#### `HTTPHandler.http_open(req)`622623Отправляет HTTP-запрос, который может быть GET или POST, в зависимости от `req.data`.624625## Объекты HTTPSHandler626627#### `HTTPSHandler.https_open(req)`628629Отправляет HTTPS-запрос, который может быть GET или POST, в зависимости от `req.data`.630631## Объекты FileHandler632633#### `FileHandler.file_open(req)`634635Открывает файл локально, если имя хоста отсутствует или равно `'localhost'`.636637Изменено в версии 3.2: Этот метод применим только для локальных имён хостов. При указании удалённого имени хоста вызывается исключение [`URLError`](https://python-all.ru/3.16/library/urllib.error.html#urllib.error.URLError).638639## Объекты DataHandler640641#### `DataHandler.data_open(req)`642643Читает data URL. Такой URL содержит содержимое, закодированное непосредственно в самом URL. Синтаксис data URL описан в [**RFC 2397**](https://python-all.ru/3.16/library/urllib.request.html). Эта реализация игнорирует пробелы в data URL с base64-кодированием, поэтому URL может быть перенесён в любом исходном файле, откуда он берётся. Но даже если некоторые браузеры не обращают внимания на отсутствие дополнения (padding) в конце base64-кодированного data URL, данная реализация в таком случае вызовет исключение [`ValueError`](https://python-all.ru/3.16/library/exceptions.html#ValueError).644645## Объекты FTPHandler646647#### `FTPHandler.ftp_open(req)`648649Открывает FTP-файл, указанный *req*. Вход всегда выполняется с пустыми именем пользователя и паролем.650651## Объекты CacheFTPHandler652653Объекты [`CacheFTPHandler`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.CacheFTPHandler) являются объектами [`FTPHandler`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.FTPHandler) со следующими дополнительными методами:654655#### `CacheFTPHandler.setTimeout(t)`656657Устанавливает тайм-аут соединений равным *t* секунд.658659#### `CacheFTPHandler.setMaxConns(m)`660661Устанавливает максимальное количество кэшированных соединений равным *m*.662663## Объекты UnknownHandler664665#### `UnknownHandler.unknown_open()`666667Вызывает исключение [`URLError`](https://python-all.ru/3.16/library/urllib.error.html#urllib.error.URLError).668669## Объекты HTTPErrorProcessor670671#### `HTTPErrorProcessor.http_response(request, response)`672673Обрабатывает ошибочные HTTP-ответы.674675Для кода 200 объект ответа возвращается немедленно.676677Для кодов ошибок, отличных от 200, этот метод просто передаёт задачу методам обработчика `http_error_<type>()` через [`OpenerDirector.error()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.OpenerDirector.error). В конечном счёте, [`HTTPDefaultErrorHandler`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.HTTPDefaultErrorHandler) вызовет исключение [`HTTPError`](https://python-all.ru/3.16/library/urllib.error.html#urllib.error.HTTPError), если ни один другой обработчик не обработает ошибку.678679#### `HTTPErrorProcessor.https_response(request, response)`680681Обрабатывает ошибочные HTTPS-ответы.682683Поведение аналогично [`http_response()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.HTTPErrorProcessor.http_response).684685## Примеры686687В дополнение к примерам ниже, больше примеров приведено в [HOWTO Fetch Internet Resources Using The urllib Package](https://python-all.ru/3.16/howto/urllib2.html#urllib-howto).688689Этот пример получает главную страницу python.org и отображает первые 300 байт.690691```python692>>> import urllib.request693>>> with urllib.request.urlopen('https://www.python.org/') as f:694...     # Ответ может быть сжат (например, 'gzip').695...     print(f.headers.get('Content-Encoding'))696...     data = f.read()697...     if f.headers.get('Content-Encoding') == 'gzip':698...         import gzip699...         data = gzip.decompress(data)700...     print(data[:300].decode('utf-8', errors='replace'))701```702703Обратите внимание, что urlopen возвращает объект bytes. Это связано с тем, что urlopen не может автоматически определить кодировку байтового потока, полученного от HTTP-сервера. Как правило, программа декодирует возвращённый объект bytes в строку, как только определит или угадает подходящую кодировку.704705В следующем документе спецификации HTML, [https://html.spec.whatwg.org/#charset](https://python-all.ru/3.16/library/urllib.request.html), перечислены различные способы указания информации о кодировке в HTML- или XML-документе.706707Дополнительную информацию см. в документе W3C: [https://www.w3.org/International/questions/qa-html-encoding-declarations](https://python-all.ru/3.16/library/urllib.request.html).708709Поскольку на сайте python.org используется кодировка *utf-8*, как указано в его мета-теге, мы будем использовать её же для декодирования байтового объекта:710711```python712>>> with urllib.request.urlopen('https://www.python.org/') as f:713...     # Проверить сжатие и декодировать соответствующим образом.714...     enc = f.headers.get('Content-Encoding')715...     data = f.read()716...     if enc == 'gzip':717...         import gzip718...         data = gzip.decompress(data)719...     print(data[:100].decode('utf-8', errors='replace'))720...721```722723Тот же результат можно получить и без использования подхода [контекстного менеджера](https://python-all.ru/3.16/glossary.html#term-context-manager):724725```python726>>> import urllib.request727>>> f = urllib.request.urlopen('https://www.python.org/')728>>> try:729...     enc = f.headers.get('Content-Encoding')730...     data = f.read()731...     if enc == 'gzip':732...         import gzip733...         data = gzip.decompress(data)734...     print(data[:100].decode('utf-8', errors='replace'))735... finally:736...     f.close()737```738739В следующем примере мы отправляем поток данных на стандартный ввод CGI и читаем данные, которые он возвращает. Обратите внимание: этот пример будет работать только в том случае, если установка Python поддерживает SSL.740741```python742>>> import urllib.request743>>> req = urllib.request.Request(url='https://localhost/cgi-bin/test.cgi',744...                       data=b'This data is passed to stdin of the CGI')745>>> with urllib.request.urlopen(req) as f:746...     print(f.read().decode('utf-8'))747...748Got Data: "This data is passed to stdin of the CGI"749```750751Код образца CGI, использованного в приведённом выше примере:752753```python754#!/usr/bin/env python755import sys756data = sys.stdin.read()757print('Content-type: text/plain\n\nGot Data: "%s"' % data)758```759760Вот пример выполнения запроса `PUT` с помощью [`Request`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.Request):761762```python763import urllib.request764DATA = b'some data'765req = urllib.request.Request(url='http://localhost:8080', data=DATA, method='PUT')766with urllib.request.urlopen(req) as f:767    pass768print(f.status)769print(f.reason)770```771772Использование базовой HTTP-аутентификации:773774```python775import urllib.request776# Создать OpenerDirector с поддержкой базовой HTTP-аутентификации...777auth_handler = urllib.request.HTTPBasicAuthHandler()778auth_handler.add_password(realm='PDQ Application',779                          uri='https://mahler:8092/site-updates.py',780                          user='klem',781                          passwd='kadidd!ehopper')782opener = urllib.request.build_opener(auth_handler)783# ...и установить его глобально, чтобы его можно было использовать с urlopen.784urllib.request.install_opener(opener)785with urllib.request.urlopen('http://www.example.com/login.html') as f:786    print(f.read().decode('utf-8'))787```788789[`build_opener()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.build_opener) предоставляет множество обработчиков по умолчанию, включая [`ProxyHandler`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.ProxyHandler). По умолчанию `ProxyHandler` использует переменные окружения с именами `<scheme>_proxy`, где `<scheme>` – это используемая схема URL. Например, переменная окружения `http_proxy` читается для получения URL HTTP-прокси.790791Этот пример заменяет обработчик по умолчанию [`ProxyHandler`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.ProxyHandler) на тот, который использует программно заданные URL прокси, и добавляет поддержку авторизации прокси с помощью [`ProxyBasicAuthHandler`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.ProxyBasicAuthHandler).792793```python794proxy_handler = urllib.request.ProxyHandler({'http': 'http://www.example.com:3128/'})795proxy_auth_handler = urllib.request.ProxyBasicAuthHandler()796proxy_auth_handler.add_password('realm', 'host', 'username', 'password')797798opener = urllib.request.build_opener(proxy_handler, proxy_auth_handler)799# На этот раз, вместо установки OpenerDirector, используется напрямую:800with opener.open('http://www.example.com/login.html') as f:801   print(f.read().decode('utf-8'))802```803804Добавление HTTP-заголовков:805806Используйте аргумент *headers* конструктора [`Request`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.Request) или:807808```python809import urllib.request810req = urllib.request.Request('http://www.example.com/')811req.add_header('Referer', 'https://www.python.org/')812# Настроить значение заголовка User-Agent по умолчанию:813req.add_header('User-Agent', 'urllib-example/0.1 (Contact: . . .)')814with urllib.request.urlopen(req) as f:815    print(f.read().decode('utf-8'))816```817818[`OpenerDirector`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.OpenerDirector) автоматически добавляет заголовок *User-Agent* к каждому запросу [`Request`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.Request). Чтобы изменить это:819820```python821import urllib.request822opener = urllib.request.build_opener()823opener.addheaders = [('User-agent', 'Mozilla/5.0')]824with opener.open('http://www.example.com/') as f:825   print(f.read().decode('utf-8'))826```827828Также помните, что несколько стандартных заголовков (*Content-Length*, *Content-Type* и *Host*) добавляются, когда [`Request`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.Request) передаётся в [`urlopen()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.urlopen) (или [`OpenerDirector.open()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.OpenerDirector.open)).829830Вот пример сеанса, в котором используется метод `GET` для получения URL с параметрами:831832```python833>>> import urllib.request834>>> import urllib.parse835>>> params = urllib.parse.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})836>>> url = "https://www.python.org/?%s" % params837>>> with urllib.request.urlopen(url) as f:838...     print(f.read().decode('utf-8'))839...840```841842В следующем примере вместо этого используется метод `POST`. Обратите внимание, что вывод параметров из urlencode кодируется в байты перед отправкой в urlopen в качестве данных:843844```python845>>> import urllib.request846>>> import urllib.parse847>>> data = urllib.parse.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})848>>> data = data.encode('ascii')849>>> with urllib.request.urlopen("https://httpbin.org/post", data) as f:850...     print(f.read().decode('utf-8'))851...852```853854В следующем примере используется явно указанный HTTP-прокси, переопределяющий настройки окружения:855856```python857>>> import urllib.request858>>> proxies = {'http': 'http://proxy.example.com:8080/'}859>>> opener = urllib.request.build_opener(urllib.request.ProxyHandler(proxies))860>>> with opener.open("https://www.python.org") as f:861...     f.read().decode('utf-8')862...863```864865В следующем примере прокси не используются вовсе, переопределяя настройки окружения:866867```python868>>> import urllib.request869>>> opener = urllib.request.build_opener(urllib.request.ProxyHandler({}))870>>> with opener.open("https://www.python.org/") as f:871...     f.read().decode('utf-8')872...873```874875## Устаревший интерфейс876877Следующие функции и классы перенесены из модуля Python 2 `urllib` (в отличие от `urllib2`). В будущем они могут стать устаревшими.878879#### `urllib.request.urlretrieve(url, filename=None, reporthook=None, data=None)`880881Копирует сетевой объект, заданный URL, в локальный файл. Если URL указывает на локальный файл, объект не будет скопирован, если не указан filename. Возвращает кортеж `(filename, headers)`, где *filename* – это имя локального файла, под которым можно найти объект, а *headers* – то, что вернул метод `info()` объекта, возвращённого [`urlopen()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.urlopen) (для удалённого объекта). Исключения те же, что и для `urlopen()`.882883Второй аргумент, если присутствует, задаёт местоположение файла для копирования (если отсутствует, местоположением будет временный файл с автоматически сгенерированным именем). Третий аргумент, если присутствует, является вызываемым объектом, который будет вызван один раз при установлении сетевого соединения и один раз после каждого последующего чтения блока. Вызываемый объект будет получать три аргумента: количество переданных блоков на данный момент, размер блока в байтах и общий размер файла. Третий аргумент может быть `-1` на старых FTP-серверах, которые не возвращают размер файла в ответ на запрос получения.884885Следующий пример иллюстрирует наиболее распространённый сценарий использования:886887```python888>>> import urllib.request889>>> local_filename, headers = urllib.request.urlretrieve('https://python.org/')890>>> html = open(local_filename)891>>> html.close()892```893894Если *url* использует идентификатор схемы `http:`, необязательный аргумент *data* может быть передан для указания запроса `POST` (обычно тип запроса – `GET`). Аргумент *data* должен быть байтовым объектом в стандартном формате *application/x-www-form-urlencoded*; см. функцию [`urllib.parse.urlencode()`](https://python-all.ru/3.16/library/urllib.parse.html#urllib.parse.urlencode).895896`urlretrieve()` вызовет исключение [`ContentTooShortError`](https://python-all.ru/3.16/library/urllib.error.html#urllib.error.ContentTooShortError), когда обнаружит, что объём доступных данных меньше ожидаемого (который указан в заголовке *Content-Length*). Это может произойти, например, при прерывании загрузки.897898Заголовок *Content-Length* рассматривается как нижняя граница: если доступно больше данных для чтения, urlretrieve читает больше данных, но если данных меньше, он вызывает исключение.899900В этом случае вы всё ещё можете получить загруженные данные, они хранятся в атрибуте `content` экземпляра исключения.901902Если заголовок *Content-Length* не был передан, urlretrieve не может проверить размер загруженных данных и просто возвращает их. В этом случае остаётся только предполагать, что загрузка прошла успешно.903904#### `urllib.request.urlcleanup()`905906Очищает временные файлы, которые могли остаться от предыдущих вызовов [`urlretrieve()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.urlretrieve).907908## Ограничения `urllib.request`909910- В настоящее время поддерживаются только следующие протоколы: HTTP (версии 0.9 и 1.0), FTP, локальные файлы и data-URL.911912  Изменено в версии 3.4: Добавлена поддержка data-URL.913- Функция кэширования [`urlretrieve()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.urlretrieve) отключена, пока не будет реализована правильная обработка заголовков Expiration time.914- Должна быть функция для проверки, находится ли определённый URL в кэше.915- Для обратной совместимости, если URL указывает на локальный файл, но файл не удаётся открыть, URL интерпретируется заново с использованием протокола FTP. Это иногда может приводить к запутанным сообщениям об ошибках.916- Функции [`urlopen()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.urlopen) и [`urlretrieve()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.urlretrieve) могут вызывать сколь угодно длительные задержки при ожидании установки сетевого соединения. Это означает, что создать интерактивный веб-клиент с помощью этих функций без использования потоков сложно.917- Данные, возвращаемые [`urlopen()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.urlopen) или [`urlretrieve()`](https://python-all.ru/3.16/library/urllib.request.html#urllib.request.urlretrieve), представляют собой необработанные данные, возвращённые сервером. Это могут быть бинарные данные (например, изображение), обычный текст или, к примеру, HTML. Протокол HTTP передаёт информацию о типе в заголовке ответа, который можно проверить, взглянув на заголовок *Content-Type*. Если возвращённые данные являются HTML, можно использовать модуль [`html.parser`](https://python-all.ru/3.16/library/html.parser.html#module-html.parser) для его разбора.918- Код, обрабатывающий протокол FTP, не может различить файл и каталог. Это может приводить к неожиданному поведению при попытке чтения URL, указывающего на недоступный файл. Если URL заканчивается на `/`, считается, что он ссылается на каталог, и обрабатывается соответствующим образом. Но если попытка чтения файла приводит к ошибке 550 (означающей, что URL не найден или недоступен, часто из-за прав доступа), то путь трактуется как каталог, чтобы обработать случай, когда каталог указан URL, но конечный `/` был опущен. Это может приводить к вводящим в заблуждение результатам при попытке получить файл, недоступный для чтения из-за прав; код FTP попытается прочитать его, получит ошибку 550, а затем выполнит листинг каталога для этого недоступного файла. Если требуется более точный контроль, стоит рассмотреть использование модуля [`ftplib`](https://python-all.ru/3.16/library/ftplib.html#module-ftplib).919920# `urllib.response` – Классы ответов, используемые urllib921922Модуль `urllib.response` определяет функции и классы, которые предоставляют минимальный файлоподобный интерфейс, включая `read()` и `readline()`. Функции, определённые в этом модуле, используются внутри модуля `urllib.request`. Типичный объект ответа – экземпляр [`urllib.response.addinfourl`](https://python-all.ru/3.16/library/urllib.request.html#urllib.response.addinfourl):923924#### `class urllib.response.addinfourl`925926#### `url`927928URL полученного ресурса, обычно используется для определения, был ли выполнен редирект.929930#### `headers`931932Возвращает заголовки ответа в виде экземпляра [`EmailMessage`](https://python-all.ru/3.16/library/email.message.html#email.message.EmailMessage).933934#### `status`935936Добавлено в версии 3.9.937938Код состояния, возвращаемый сервером.939940#### `geturl()`941942Устарело с версии 3.9: Устарело в пользу [`url`](https://python-all.ru/3.16/library/urllib.request.html#urllib.response.addinfourl.url).943944#### `info()`945946Устарело с версии 3.9: Устарело в пользу [`headers`](https://python-all.ru/3.16/library/urllib.request.html#urllib.response.addinfourl.headers).947948#### `code`949950Устарело с версии 3.9: Устарело в пользу [`status`](https://python-all.ru/3.16/library/urllib.request.html#urllib.response.addinfourl.status).951952#### `getcode()`953954Устарело с версии 3.9: Устарело в пользу [`status`](https://python-all.ru/3.16/library/urllib.request.html#urllib.response.addinfourl.status).955