# `urllib.request` — Extensible library for opening URLs

Вихідний код: Lib/urllib/request.py

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

Дивись також

Пакет запитів рекомендовано для клієнтського інтерфейсу HTTP вищого рівня.

Попередження

On macOS it is unsafe to use this module in programs using `os.fork()` because the `getproxies()` implementation for macOS uses a higher-level system API. Set the environment variable `no_proxy` to `*` to avoid this problem (e.g. `os.environ["no_proxy"] = "*"`).

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms `wasm32-emscripten` and `wasm32-wasi`. See WebAssembly platforms for more information.

Модуль `urllib.request` визначає такі функції:

urllib.request.urlopen(url, data=None, [timeout, ]*, cafile=None, capath=None, cadefault=False, context=None)

  Open url, which can be either a string containing a valid, properly encoded URL, or a `Request` object.

  data має бути об’єктом, який визначає додаткові дані для надсилання на сервер, або `None`, якщо такі дані не потрібні. Дивіться `Request` для деталей.

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

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

  Якщо вказано контекст, це має бути екземпляр `ssl.SSLContext`, який описує різні параметри SSL. Перегляньте `HTTPSConnection` для отримання додаткової інформації.

  The optional cafile and capath parameters specify a set of trusted CA certificates for HTTPS requests. cafile should point to a single file containing a bundle of CA certificates, whereas capath should point to a directory of hashed certificate files. More information can be found in `ssl.SSLContext.load_verify_locations()`.

  The cadefault parameter is ignored.

  Ця функція завжди повертає об’єкт, який може працювати як context manager і має властивості url, headers і status. Дивіться `urllib.response.addinfourl`, щоб дізнатися більше про ці властивості.

  Для URL-адрес HTTP і HTTPS ця функція повертає дещо змінений об’єкт `http.client.HTTPResponse`. На додаток до трьох нових методів, наведених вище, атрибут msg містить ту саму інформацію, що й атрибут `reason` — фразу причини, яку повертає сервер — замість заголовків відповіді, як це вказано в документації для `HTTPResponse`.

  Для FTP, файлів і URL-адрес даних і запитів, які явно обробляються застарілими класами `URLopener` і `FancyURLopener`, ця функція повертає об’єкт `urllib.response.addinfourl`.

  Викликає `URLError` через помилки протоколу.

  Зауважте, що `None` може бути повернуто, якщо жоден обробник не обробляє запит (хоча стандартний встановлений глобальний `OpenerDirector` використовує `UnknownHandler`, щоб гарантувати, що цього ніколи не станеться).

  In addition, if proxy settings are detected (for example, when a `*_proxy` environment variable like `http_proxy` is set), `ProxyHandler` is default installed and makes sure the requests are handled through the proxy.

  Застарілу функцію `urllib.urlopen` від Python 2.6 і попередніх версій було припинено; `urllib.request.urlopen()` відповідає старому `urllib2.urlopen`. Обробку проксі, яку було виконано шляхом передачі параметра словника до `urllib.urlopen`, можна отримати за допомогою об’єктів `ProxyHandler`.

  Відкривач за замовчуванням викликає подію аудиту `urllib.Request` з аргументами `fullurl`, `data`, `headers`, `method`, взяті з об’єкта запиту .

  Змінено в версії 3.2: cafile і capath були додані.

  HTTPS virtual hosts are now supported if possible (that is, if `ssl.HAS_SNI` is true).

  data може бути ітерованим об’єктом.

  Змінено в версії 3.3: Додано cadefault.

  Змінено в версії 3.4.3: додано контекст.

  Змінено в версії 3.10: HTTPS connection now send an ALPN extension with protocol indicator `http/1.1` when no context is given. Custom context should set ALPN protocols with `set_alpn_protocols()`.

  Застаріло починаючи з версії 3.6: cafile, capath and cadefault are deprecated in favor of context. Please use `ssl.SSLContext.load_cert_chain()` instead, or let `ssl.create_default_context()` select the system’s trusted CA certificates for you.

urllib.request.install_opener(opener)

  Встановіть екземпляр `OpenerDirector` як глобальний засіб відкриття за умовчанням. Встановлення відкривача необхідно, лише якщо ви хочете, щоб urlopen використовував цей відкривач; інакше просто викликайте `OpenerDirector.open()` замість `urlopen()`. Код не перевіряє справжнього `OpenerDirector`, і будь-який клас із відповідним інтерфейсом працюватиме.

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

  Повертає екземпляр `OpenerDirector`, який об’єднує обробники у вказаному порядку. handlers можуть бути або екземплярами `BaseHandler`, або підкласами `BaseHandler` (у цьому випадку повинна бути можливість викликати конструктор без будь-яких параметрів). Екземпляри наступних класів будуть перед обробникамиs, якщо тільки обробникине містять їх, їх екземпляри або їхні підкласи: `ProxyHandler` (якщо виявлено налаштування проксі), `UnknownHandler`, `HTTPHandler`, `HTTPDefaultErrorHandler`, `HTTPRedirectHandler`, `FTPHandler`, `FileHandler`, `HTTPErrorProcessor`.

  Якщо встановлення Python підтримує SSL (тобто якщо модуль `ssl` можна імпортувати), `HTTPSHandler` також буде додано.

  Підклас `BaseHandler` також може змінити свій атрибут `handler_order`, щоб змінити його позицію в списку обробників.

urllib.request.pathname2url(path)

  Convert the pathname path from the local syntax for a path to the form used in the path component of a URL. This does not produce a complete URL. The return value will already be quoted using the `quote()` function.

urllib.request.url2pathname(path)

  Convert the path component path from a percent-encoded URL to the local syntax for a path. This does not accept a complete URL. This function uses `unquote()` to decode path.

urllib.request.getproxies()

  Ця допоміжна функція повертає словник схеми зіставлення URL-адрес проксі-сервера. Він сканує середовище на наявність змінних із назвою `<scheme> _proxy`, без урахування регістру, для всіх операційних систем спочатку, а якщо не може їх знайти, шукає інформацію про проксі-сервер у системній конфігурації для macOS і системному реєстрі Windows для Windows. Якщо існують (і не узгоджуються) змінні середовища як у нижньому, так і у верхньому регістрах, перевага віддається нижньому регістру.

  Примітка

  Якщо встановлено змінну середовища `REQUEST_METHOD`, що зазвичай вказує на те, що ваш сценарій працює в середовищі CGI, змінна середовища `HTTP_PROXY` (великий регістр `_PROXY`) буде проігноровано. Це пояснюється тим, що ця змінна може бути введена клієнтом за допомогою HTTP-заголовка «Proxy:». Якщо вам потрібно використовувати HTTP-проксі в середовищі CGI, або явно використовуйте `ProxyHandler`, або переконайтеся, що назва змінної написана малими літерами (або принаймні суфікс `_proxy`).

Передбачені такі заняття:

class urllib.request.Request(url, data=None, headers={}, origin_req_host=None, unverifiable=False, method=None)

  Цей клас є абстракцією URL-запиту.

  url should be a string containing a valid, properly encoded URL.

  data має бути об’єктом, який визначає додаткові дані для надсилання на сервер, або `None`, якщо такі дані не потрібні. Наразі запити HTTP є єдиними, які використовують data. Підтримувані типи об’єктів включають байти, файлоподібні об’єкти та ітерації байтоподібних об’єктів. Якщо поля заголовка `Content-Length` або `Transfer-Encoding` не надано, `HTTPHandler` встановить ці заголовки відповідно до типу data. `Content-Length` використовуватиметься для надсилання байтових об’єктів, тоді як `Transfer-Encoding: chunked`, як зазначено в RFC 7230, розділ 3.3.1, використовуватиметься для надсилання файлів та інших ітерацій.

  Для методу запиту HTTP POST data має бути буфером у стандартному форматі application/x-www-form-urlencoded. Функція `urllib.parse.urlencode()` приймає відображення або послідовність 2-кортежів і повертає рядок ASCII у цьому форматі. Перш ніж використовувати як параметр data, його слід закодувати в байти.

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

  An appropriate `Content-Type` header should be included if the data argument is present. If this header has not been provided and data is not None, `Content-Type: application/x-www-form-urlencoded` will be added as a default.

  Наступні два аргументи цікаві лише для правильної обробки сторонніх файлів cookie HTTP:

  origin_req_host має бути хостом запиту вихідної транзакції, як визначено RFC 2965. За замовчуванням `http.cookiejar.request_host(self)`. Це ім’я хоста або IP-адреса вихідного запиту, ініційованого користувачем. Наприклад, якщо запит стосується зображення в документі HTML, це має бути хост запиту для сторінки, що містить зображення.

  unverifiable має вказувати, чи є запит неперевіреним, як визначено RFC 2965. За замовчуванням має значення `False`. Неперевірений запит — це запит, URL-адресу якого користувач не мав можливості схвалити. Наприклад, якщо запит стосується зображення в документі HTML, і користувач не мав можливості підтвердити автоматичне отримання зображення, це має бути правдою.

  method should be a string that indicates the HTTP request method that will be used (e.g. `'HEAD'`). If provided, its value is stored in the `method` attribute and is used by `get_method()`. The default is `'GET'` if data is `None` or `'POST'` otherwise. Subclasses may indicate a different default method by setting the `method` attribute in the class itself.

  Примітка

  Запит не працюватиме належним чином, якщо об’єкт даних не зможе доставити свій вміст більше одного разу (наприклад, файл або ітераційний елемент, який може створити вміст лише один раз), і запит повторюється для перенаправлення HTTP або автентифікації. Дані надсилаються на сервер HTTP одразу після заголовків. У бібліотеці немає підтримки очікування 100 продовжень.

  Змінено в версії 3.3: `Request.method` argument is added to the Request class.

  Змінено в версії 3.4: Типовий `Request.method` може бути вказаний на рівні класу.

  Змінено в версії 3.6: Не створюйте повідомлення про помилку, якщо `Content-Length` не було надано, а data не є ні `None`, ні об’єктом bytes. Поверніться до використання фрагментованого кодування передачі.

class urllib.request.OpenerDirector

  Клас `OpenerDirector` відкриває URL-адреси через `BaseHandler`об’єднані разом. Він керує ланцюжком обробників і відновленням після помилок.

class urllib.request.BaseHandler

  Це базовий клас для всіх зареєстрованих обробників — і обробляє лише просту механіку реєстрації.

class urllib.request.HTTPDefaultErrorHandler

  Клас, який визначає обробник за замовчуванням для відповідей на помилки HTTP; усі відповіді перетворюються на винятки `HTTPError`.

class urllib.request.HTTPRedirectHandler

  Клас для обробки переспрямувань.

class urllib.request.HTTPCookieProcessor(cookiejar=None)

  Клас для обробки файлів cookie HTTP.

class urllib.request.ProxyHandler(proxies=None)

  Змусити запити проходити через проксі. Якщо вказано проксі, це має бути словник, який зіставляє назви протоколів з URL-адресами проксі. За замовчуванням список проксі-серверів читається зі змінних середовища `<protocol> _proxy`. Якщо не встановлено жодних змінних середовища проксі, у середовищі Windows параметри проксі-сервера отримуються з розділу параметрів Інтернету реєстру, а в середовищі macOS інформація проксі-сервера отримується з System Configuration Framework.

  Щоб вимкнути автоматичне визначення проксі, передайте порожній словник.

  Змінну середовища `no_proxy` можна використовувати для визначення хостів, до яких не можна звертатися через проксі; якщо встановлено, це має бути розділений комами список суфіксів імен хостів, необов’язково з додаванням `:port`, наприклад `cern.ch,ncsa.uiuc.edu,some.host:8080`.

  Примітка

  `HTTP_PROXY` ігноруватиметься, якщо встановлено змінну `REQUEST_METHOD`; перегляньте документацію на `getproxies()`.

class urllib.request.HTTPPasswordMgr

  Зберігайте базу даних відповідностей `(сфера, uri) -> (користувач, пароль)`.

class urllib.request.HTTPPasswordMgrWithDefaultRealm

  Зберігайте базу даних відповідностей `(сфера, uri) -> (користувач, пароль)`. Сфера `None` вважається всеохоплюючою областю, у якій виконується пошук, якщо жодна інша область не підходить.

class urllib.request.HTTPPasswordMgrWithPriorAuth

  Варіант `HTTPPasswordMgrWithDefaultRealm`, який також має базу даних зіставлень `uri -> is_authenticated`. Може використовуватися обробником BasicAuth, щоб визначити, коли надсилати облікові дані для автентифікації негайно замість очікування відповіді `401`.

  Нове в версії 3.5.

class urllib.request.AbstractBasicAuthHandler(password_mgr=None)

  Це клас mixin, який допомагає з автентифікацією HTTP як на віддаленому хості, так і на проксі. password_mgr, якщо надано, має бути чимось сумісним із `HTTPPasswordMgr`; зверніться до розділу Об’єкти HTTPPasswordMgr для отримання інформації про інтерфейс, який має підтримуватися. Якщо passwd_mgr також надає методи `is_authenticated` і `update_authenticated` (див. Об’єкти HTTPPasswordMgrWithPriorAuth), тоді обробник використовуватиме результат `is_authenticated` для заданого URI, щоб визначити, чи надсилати облікові дані автентифікації разом із запитом. Якщо `is_authenticated` повертає `True` для URI, облікові дані надсилаються. Якщо `is_authenticated` має значення `False`, облікові дані не надсилаються, а потім, якщо отримано відповідь `401`, запит повторно надсилається з обліковими даними автентифікації. Якщо автентифікація проходить успішно, `update_authenticated` викликається, щоб встановити `is_authenticated` `True` для URI, щоб наступні запити до URI або будь-якого з його супер-URI автоматично включали облікові дані автентифікації.

  Нове в версії 3.5: Додано підтримку `is_authenticated`.

class urllib.request.HTTPBasicAuthHandler(password_mgr=None)

  Керувати автентифікацією на віддаленому хості. password_mgr, якщо його вказано, має бути сумісним із `HTTPPasswordMgr`; зверніться до розділу Об’єкти HTTPPasswordMgr для отримання інформації про інтерфейс, який має підтримуватися. HTTPBasicAuthHandler викличе помилку `ValueError`, якщо надано неправильну схему автентифікації.

class urllib.request.ProxyBasicAuthHandler(password_mgr=None)

  Керувати автентифікацією за допомогою проксі. password_mgr, якщо його вказано, має бути сумісним із `HTTPPasswordMgr`; зверніться до розділу Об’єкти HTTPPasswordMgr для отримання інформації про інтерфейс, який має підтримуватися.

class urllib.request.AbstractDigestAuthHandler(password_mgr=None)

  Це клас mixin, який допомагає з автентифікацією HTTP як на віддаленому хості, так і на проксі. password_mgr, якщо його вказано, має бути сумісним із `HTTPPasswordMgr`; зверніться до розділу Об’єкти HTTPPasswordMgr для отримання інформації про інтерфейс, який має підтримуватися.

class urllib.request.HTTPDigestAuthHandler(password_mgr=None)

  Керувати автентифікацією на віддаленому хості. password_mgr, якщо його вказано, має бути сумісним із `HTTPPasswordMgr`; зверніться до розділу Об’єкти HTTPPasswordMgr для отримання інформації про інтерфейс, який має підтримуватися. Якщо додано як обробник дайджест-автентифікації, так і обробник базової автентифікації, дайджест-автентифікація завжди виконується першою. Якщо дайджест автентифікації знову повертає відповідь 40x, він надсилається обробнику базової автентифікації для обробки. Цей метод обробника викличе `ValueError`, коли представлено схему автентифікації, відмінну від Digest або Basic.

  Змінено в версії 3.3: Викликати `ValueError` на непідтримуваній схемі автентифікації.

class urllib.request.ProxyDigestAuthHandler(password_mgr=None)

  Керувати автентифікацією за допомогою проксі. password_mgr, якщо його вказано, має бути сумісним із `HTTPPasswordMgr`; зверніться до розділу Об’єкти HTTPPasswordMgr для отримання інформації про інтерфейс, який має підтримуватися.

class urllib.request.HTTPHandler

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

class urllib.request.HTTPSHandler(debuglevel=0, context=None, check_hostname=None)

  Клас для обробки URL-адрес HTTPS. context і check_hostname мають те саме значення, що й у `http.client.HTTPSConnection`.

  Змінено в версії 3.2: context і check_hostname були додані.

class urllib.request.FileHandler

  Відкрийте локальні файли.

class urllib.request.DataHandler

  URL-адреси відкритих даних.

  Нове в версії 3.4.

class urllib.request.FTPHandler

  Відкрийте URL-адреси FTP.

class urllib.request.CacheFTPHandler

  Відкриті URL-адреси FTP, зберігаючи кеш відкритих з’єднань FTP, щоб мінімізувати затримки.

class urllib.request.UnknownHandler

  Універсальний клас для обробки невідомих URL-адрес.

class urllib.request.HTTPErrorProcessor

  Обробляти відповіді на помилки HTTP.

## Об’єкти запиту

Наступні методи описують публічний інтерфейс `Request`, тому всі вони можуть бути перевизначені в підкласах. Він також визначає кілька публічних атрибутів, які можуть використовуватися клієнтами для перевірки аналізованого запиту.

Request.full_url

  Вихідна URL-адреса передається конструктору.

  Змінено в версії 3.4.

  Request.full_url — це властивість із установником, отримувачем і видаленням. Отримання `full_url` повертає початкову URL-адресу запиту з фрагментом, якщо він був присутній.

Request.type

  Схема URI.

Request.host

  Повноваження URI, як правило, хост, але також може містити порт, розділений двокрапкою.

Request.origin_req_host

  Оригінальний хост для запиту, без порту.

Request.selector

  Шлях URI. Якщо `Request` використовує проксі, тоді селектором буде повна URL-адреса, яка передається проксі.

Request.data

  Тіло сутності для запиту або `None`, якщо не вказано.

  Змінено в версії 3.4: Зміна значення `Request.data` тепер видаляє заголовок «Content-Length», якщо він був раніше встановлений або обчислений.

Request.unverifiable

  логічне значення, вказує, чи запит не можна перевірити, як визначено RFC 2965.

Request.method

  Метод запиту HTTP для використання. За замовчуванням його значення `None`, що означає, що `get_method()` виконає звичайне обчислення методу, який буде використано. Його значення можна встановити (таким чином замінюючи обчислення за замовчуванням у `get_method()`) або шляхом надання значення за замовчуванням, установивши його на рівні класу в підкласі `Request`, або передавши значення у конструктор `Request` через аргумент method.

  Нове в версії 3.3.

  Змінено в версії 3.4: Значення за замовчуванням тепер можна встановити в підкласах; раніше його можна було встановити лише через аргумент конструктора.

Request.get_method()

  Повертає рядок із зазначенням методу запиту HTTP. Якщо `Request.method` не є `None`, поверніть його значення, інакше поверніть `'GET'`, якщо `Request.data` має значення `None` або `' POST''`, якщо це не так. Це має значення лише для запитів HTTP.

  Змінено в версії 3.3: get_method тепер переглядає значення `Request.method`.

Request.add_header(key, val)

  Додайте інший заголовок до запиту. Наразі заголовки ігноруються всіма обробниками, крім обробників HTTP, де вони додаються до списку заголовків, надісланих на сервер. Зауважте, що не може бути більше одного заголовка з однаковим іменем, і пізніші виклики перезапишуть попередні виклики, якщо ключ зіткнеться. Наразі це не втрачає функціональність HTTP, оскільки всі заголовки, які мають значення при повторному використанні, мають (специфічний для заголовка) спосіб отримати ту саму функціональність, використовуючи лише один заголовок. Зауважте, що заголовки, додані за допомогою цього методу, також додаються до перенаправлених запитів.

Request.add_unredirected_header(key, header)

  Додайте заголовок, який не буде додано до переспрямованого запиту.

Request.has_header(header)

  Повертає, чи має екземпляр названий заголовок (перевіряє як звичайний, так і неперенаправлений).

Request.remove_header(header)

  Видаліть іменований заголовок із екземпляра запиту (як зі звичайних, так і з непереспрямованих заголовків).

  Нове в версії 3.4.

Request.get_full_url()

  Повертає URL-адресу, указану в конструкторі.

  Змінено в версії 3.4.

  Повертає `Request.full_url`

Request.set_proxy(host, type)

  Підготуйте запит, підключившись до проксі-сервера. host і type замінять параметри екземпляра, а селектор екземпляра буде оригінальною URL-адресою, заданою в конструкторі.

Request.get_header(header_name, default=None)

  Повертає значення заданого заголовка. Якщо заголовок відсутній, поверніть значення за замовчуванням.

Request.header_items()

  Повертає список кортежів (header_name, header_value) заголовків запиту.

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

## Об’єкти OpenerDirector

Екземпляри `OpenerDirector` мають такі методи:

OpenerDirector.add_handler(handler)

  handler має бути екземпляром `BaseHandler`. Наступні методи шукаються та додаються до можливих ланцюжків (зверніть увагу, що помилки HTTP є окремим випадком). Зауважте, що далі протокол слід замінити на фактичний протокол для обробки, наприклад, `http_response()` буде обробником відповіді протоколу HTTP. Також type слід замінити фактичним кодом HTTP, наприклад, `http_error_404()` оброблятиме помилки HTTP 404.

  - `<protocol>_open()` — signal that the handler knows how to open protocol URLs.

    Перегляньте `BaseHandler.<protocol>_open()` для отримання додаткової інформації.

  - `http_error_<type>()` — signal that the handler knows how to handle HTTP errors with HTTP error code type.

    Перегляньте `BaseHandler.http_error_<nnn>()` для отримання додаткової інформації.

  - `<protocol>_error()` — signal that the handler knows how to handle errors from (non-`http`) protocol.

  - `<protocol>_request()` — signal that the handler knows how to pre-process protocol requests.

    Перегляньте `BaseHandler.<protocol>_request()` для отримання додаткової інформації.

  - `<protocol>_response()` — signal that the handler knows how to post-process protocol responses.

    Дивіться `BaseHandler.<protocol>_response()` для отримання додаткової інформації.

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

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

OpenerDirector.error(proto, *args)

  Handle an error of the given protocol. This will call the registered error handlers for the given protocol with the given arguments (which are protocol specific). The HTTP protocol is a special case which uses the HTTP response code to determine the specific error handler; refer to the `http_error_<type>()` methods of the handler classes.

  Повернуті значення та викликані винятки такі самі, як і для `urlopen()`.

Об’єкти OpenerDirector відкривають URL-адреси в три етапи:

Порядок, у якому ці методи викликаються на кожному етапі, визначається сортуванням екземплярів обробника.

1. Every handler with a method named like `<protocol>_request()` has that method called to pre-process the request.

2. Handlers with a method named like `<protocol>_open()` are called to handle the request. This stage ends when a handler either returns a non-`None` value (ie. a response), or raises an exception (usually `URLError`). Exceptions are allowed to propagate.

   In fact, the above algorithm is first tried for methods named `default_open()`. If all such methods return `None`, the algorithm is repeated for methods named like `<protocol>_open()`. If all such methods return `None`, the algorithm is repeated for methods named `unknown_open()`.

   Зауважте, що реалізація цих методів може передбачати виклики методів `open()` і `error()` примірника батьківського `OpenerDirector`.

3. Every handler with a method named like `<protocol>_response()` has that method called to post-process the response.

## Об’єкти BaseHandler

Об’єкти `BaseHandler` надають кілька методів, які є безпосередньо корисними, а також інші, які призначені для використання похідними класами. Вони призначені для безпосереднього використання:

BaseHandler.add_parent(director)

  Додати директора як батька.

BaseHandler.close()

  Видаліть усіх батьків.

Наступний атрибут і методи мають використовуватися лише класами, похідними від `BaseHandler`.

Примітка

The convention has been adopted that subclasses defining `<protocol>_request()` or `<protocol>_response()` methods are named `*Processor`; all others are named `*Handler`.

BaseHandler.parent

  Дійсний `OpenerDirector`, який можна використовувати для відкриття за допомогою іншого протоколу або обробки помилок.

BaseHandler.default_open(req)

  Цей метод не визначено в `BaseHandler`, але підкласи повинні визначити його, якщо вони хочуть перехоплювати всі URL-адреси.

  This method, if implemented, will be called by the parent `OpenerDirector`. It should return a file-like object as described in the return value of the `open()` method of `OpenerDirector`, or `None`. It should raise `URLError`, unless a truly exceptional thing happens (for example, `MemoryError` should not be mapped to `URLError`).

  Цей метод буде викликано перед будь-яким відкритим методом протоколу.

BaseHandler.<protocol>_open(req)

  Цей метод не визначено в `BaseHandler`, але підкласи повинні визначити його, якщо вони хочуть обробляти URL-адреси за допомогою заданого протоколу.

  This method, if defined, will be called by the parent `OpenerDirector`. Return values should be the same as for `default_open()`.

BaseHandler.unknown_open(req)

  Цей метод не визначено в `BaseHandler`, але підкласи повинні визначити його, якщо вони хочуть перехопити всі URL-адреси без спеціального зареєстрованого обробника для його відкриття.

  Цей метод, якщо він реалізований, буде викликаний `parent` `OpenerDirector`. Повернуті значення мають бути такими ж, як і для `default_open()`.

BaseHandler.http_error_default(req, fp, code, msg, hdrs)

  Цей метод не визначено в `BaseHandler`, але підкласи повинні перевизначати його, якщо вони мають намір надати збірку для всіх необроблених помилок HTTP. Він автоматично викликається `OpenerDirector`, який отримує помилку, і зазвичай не повинен викликатися за інших обставин.

  req буде об’єктом `Request`, fp буде файлоподібним об’єктом із тілом помилки HTTP, code буде тризначним кодом помилки, msg буде видиме для користувача пояснення коду та hdrs буде об’єктом відображення із заголовками помилки.

  Повернуті значення та викликані винятки мають бути такими самими, як у `urlopen()`.

BaseHandler.http_error_<nnn>(req, fp, code, msg, hdrs)

  nnn має бути тризначним кодом помилки HTTP. Цей метод також не визначено в `BaseHandler`, але буде викликаний, якщо він існує, на екземплярі підкласу, коли виникає помилка HTTP з кодом nnn.

  Підкласи повинні замінити цей метод для обробки конкретних помилок HTTP.

  Arguments, return values and exceptions raised should be the same as for `http_error_default()`.

BaseHandler.<protocol>_request(req)

  Цей метод не визначено в `BaseHandler`, але підкласи повинні визначити його, якщо вони хочуть попередньо обробляти запити даного протоколу.

  Цей метод, якщо його визначено, буде викликано батьківським `OpenerDirector`. req буде об’єктом `Request`. Поверненим значенням має бути об’єкт `Request`.

BaseHandler.<protocol>_response(req, response)

  Цей метод не визначено в `BaseHandler`, але підкласи повинні визначити його, якщо вони хочуть постобробити відповіді заданого протоколу.

  Цей метод, якщо його визначено, буде викликано батьківським `OpenerDirector`. req буде об’єктом `Request`. response буде об’єктом, який реалізує той самий інтерфейс, що й значення, що повертається `urlopen()`. Значення, що повертається, має реалізовувати той самий інтерфейс, що й значення, що повертається `urlopen()`.

## Об’єкти HTTPRedirectHandler

Примітка

Деякі перенаправлення HTTP вимагають дії від клієнтського коду цього модуля. Якщо це так, виникає `HTTPError`. Див. RFC 2616 для детальної інформації про точні значення різних кодів перенаправлення.

An `HTTPError` exception raised as a security consideration if the HTTPRedirectHandler is presented with a redirected URL which is not an HTTP, HTTPS or FTP URL.

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

  Return a `Request` or `None` in response to a redirect. This is called by the default implementations of the `http_error_30*()` methods when a redirection is received from the server. If a redirection should take place, return a new `Request` to allow `http_error_30*()` to perform the redirect to newurl. Otherwise, raise `HTTPError` if no other handler should try to handle this URL, or return `None` if you can’t but another handler might.

  Примітка

  Стандартна реалізація цього методу не відповідає суворо RFC 2616, яка говорить, що відповіді 301 і 302 на запити `POST` не повинні автоматично перенаправлятися без підтвердження користувача. Насправді браузери дозволяють автоматичне перенаправлення цих відповідей, змінюючи POST на `GET`, і реалізація за замовчуванням відтворює цю поведінку.

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

  Переспрямування на URL-адресу `Location:` або `URI:`. Цей метод викликається батьківським `OpenerDirector` під час отримання HTTP-відповіді «переміщено назавжди».

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

  Те саме, що `http_error_301()`, але викликається відповідь „знайдено“.

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

  Те саме, що `http_error_301()`, але викликається відповідь «переглянути інше».

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

  The same as `http_error_301()`, but called for the „temporary redirect“ response. It does not allow changing the request method from `POST` to `GET`.

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

  The same as `http_error_301()`, but called for the „permanent redirect“ response. It does not allow changing the request method from `POST` to `GET`.

  Нове в версії 3.11.

## Об’єкти HTTPCookieProcessor

Екземпляри `HTTPCookieProcessor` мають один атрибут:

HTTPCookieProcessor.cookiejar

  `http.cookiejar.CookieJar`, у якому зберігаються файли cookie.

## Об’єкти ProxyHandler

ProxyHandler.<protocol>_open(request)

  The `ProxyHandler` will have a method `<protocol>_open()` for every protocol which has a proxy in the proxies dictionary given in the constructor. The method will modify requests to go through the proxy, by calling `request.set_proxy()`, and call the next handler in the chain to actually execute the protocol.

## Об’єкти HTTPPasswordMgr

Ці методи доступні в об’єктах `HTTPPasswordMgr` і `HTTPPasswordMgrWithDefaultRealm`.

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

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

HTTPPasswordMgr.find_user_password(realm, authuri)

  Отримайте користувача/пароль для заданої області та URI, якщо є. Цей метод поверне `(None, None)`, якщо немає відповідного користувача/паролю.

  Для об’єктів `HTTPPasswordMgrWithDefaultRealm` шукатиметься область `None`, якщо дана сфера не має відповідного користувача/паролю.

## Об’єкти HTTPPasswordMgrWithPriorAuth

Цей менеджер паролів розширює `HTTPPasswordMgrWithDefaultRealm` для підтримки URI відстеження, для яких завжди слід надсилати облікові дані автентифікації.

HTTPPasswordMgrWithPriorAuth.add_password(realm, uri, user, passwd, is_authenticated=False)

  realm, uri, user, passwd такі ж, як для `HTTPPasswordMgr.add_password()`. is_authenticated встановлює початкове значення прапора `is_authenticated` для даного URI або списку URI. Якщо is_authenticated указано як `True`, realm ігнорується.

HTTPPasswordMgrWithPriorAuth.find_user_password(realm, authuri)

  Те саме, що для об’єктів `HTTPPasswordMgrWithDefaultRealm`

HTTPPasswordMgrWithPriorAuth.update_authenticated(self, uri, is_authenticated=False)

  Оновіть прапорець `is_authenticated` для заданого uri або списку URI.

HTTPPasswordMgrWithPriorAuth.is_authenticated(self, authuri)

  Повертає поточний стан прапора `is_authenticated` для вказаного URI.

## Об’єкти AbstractBasicAuthHandler

AbstractBasicAuthHandler.http_error_auth_reqed(authreq, host, req, headers)

  Обробіть запит на автентифікацію, отримавши пару користувач/пароль і повторивши запит. authreq має бути ім’ям заголовка, де інформація про область включена в запит, host визначає URL-адресу та шлях для автентифікації, req має бути (не вдалося) об’єктом `Request` , а headers мають бути заголовками помилок.

  host — це або повноваження (наприклад, `"python.org"`), або URL-адреса, що містить компонент повноважень (наприклад, `"http://python.org/"`). У будь-якому випадку повноваження не повинні містити компонент userinfo (тому `"python.org"` і `"python.org:80"` підходять, `"joe:password@python.org"` не є).

## Об’єкти HTTPBasicAuthHandler

HTTPBasicAuthHandler.http_error_401(req, fp, code, msg, hdrs)

  Повторіть запит із інформацією для автентифікації, якщо вона доступна.

## Об’єкти ProxyBasicAuthHandler

ProxyBasicAuthHandler.http_error_407(req, fp, code, msg, hdrs)

  Повторіть запит із інформацією для автентифікації, якщо вона доступна.

## Об’єкти AbstractDigestAuthHandler

AbstractDigestAuthHandler.http_error_auth_reqed(authreq, host, req, headers)

  authreq має бути ім’ям заголовка, де інформація про область включена в запит, host має бути хостом для автентифікації, req має бути (не вдалося) об’єктом `Request`, і headers повинні бути заголовками помилок.

## Об’єкти HTTPDigestAuthHandler

HTTPDigestAuthHandler.http_error_401(req, fp, code, msg, hdrs)

  Повторіть запит із інформацією для автентифікації, якщо вона доступна.

## Об’єкти ProxyDigestAuthHandler

ProxyDigestAuthHandler.http_error_407(req, fp, code, msg, hdrs)

  Повторіть запит із інформацією для автентифікації, якщо вона доступна.

## Об’єкти HTTPHandler

HTTPHandler.http_open(req)

  Надішліть запит HTTP, який може бути GET або POST, залежно від `req.has_data()`.

## Об’єкти HTTPSHandler

HTTPSHandler.https_open(req)

  Надішліть запит HTTPS, який може бути GET або POST, залежно від `req.has_data()`.

## Об’єкти FileHandler

FileHandler.file_open(req)

  Відкрийте файл локально, якщо немає імені хоста або ім’я хоста `'localhost'`.

  Змінено в версії 3.2: This method is applicable only for local hostnames. When a remote hostname is given, an `URLError` is raised.

## Об’єкти DataHandler

DataHandler.data_open(req)

  Read a data URL. This kind of URL contains the content encoded in the URL itself. The data URL syntax is specified in RFC 2397. This implementation ignores white spaces in base64 encoded data URLs so the URL may be wrapped in whatever source file it comes from. But even though some browsers don’t mind about a missing padding at the end of a base64 encoded data URL, this implementation will raise an `ValueError` in that case.

## Об’єкти FTPHandler

FTPHandler.ftp_open(req)

  Відкрийте файл FTP, позначений req. Вхід завжди виконується з порожнім іменем користувача та паролем.

## Об’єкти CacheFTPHandler

Об’єкти `CacheFTPHandler` — це об’єкти `FTPHandler` із такими додатковими методами:

CacheFTPHandler.setTimeout(t)

  Встановіть тайм-аут підключень на t секунд.

CacheFTPHandler.setMaxConns(m)

  Установіть максимальну кількість кешованих підключень до m.

## Об’єкти UnknownHandler

UnknownHandler.unknown_open()

  Викликати виняток `URLError`.

## Об’єкти HTTPErrorProcessor

HTTPErrorProcessor.http_response(request, response)

  Обробляти відповіді на помилки HTTP.

  Для 200 кодів помилок об’єкт відповіді повертається негайно.

  For non-200 error codes, this simply passes the job on to the `http_error_<type>()` handler methods, via `OpenerDirector.error()`. Eventually, `HTTPDefaultErrorHandler` will raise an `HTTPError` if no other handler handles the error.

HTTPErrorProcessor.https_response(request, response)

  Обробляти відповіді на помилки HTTPS.

  Поведінка така ж, як `http_response()`.

## Приклади

Крім наведених нижче прикладів, більше прикладів наведено в HOWTO Отримати Інтернет-ресурси за допомогою пакета urllib.

This example gets the python.org main page and displays the first 300 bytes of it.

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

Зауважте, що urlopen повертає об’єкт bytes. Це тому, що urlopen не може автоматично визначати кодування потоку байтів, який він отримує від сервера HTTP. Загалом, програма декодує повернутий об’єкт bytes у рядок, як тільки вона визначить або вгадає відповідне кодування.

The following W3C document, https://www.w3.org/International/O-charset, lists the various ways in which an (X)HTML or an XML document could have specified its encoding information.

As the python.org website uses utf-8 encoding as specified in its meta tag, we will use the same for decoding the bytes object.

    >>> with urllib.request.urlopen('http://www.python.org/') as f:
    ...     print(f.read(100).decode('utf-8'))
    ...
    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtm

It is also possible to achieve the same result without using the context manager approach.

    >>> import urllib.request
    >>> f = urllib.request.urlopen('http://www.python.org/')
    >>> print(f.read(100).decode('utf-8'))
    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtm

У наступному прикладі ми надсилаємо потік даних на stdin CGI та зчитуємо дані, які він повертає нам. Зауважте, що цей приклад працюватиме, лише якщо інсталяція Python підтримує SSL.

    >>> import urllib.request
    >>> req = urllib.request.Request(url='https://localhost/cgi-bin/test.cgi',
    ...                       data=b'This data is passed to stdin of the CGI')
    >>> with urllib.request.urlopen(req) as f:
    ...     print(f.read().decode('utf-8'))
    ...
    Got Data: "This data is passed to stdin of the CGI"

Код для прикладу CGI, використаного у наведеному вище прикладі, такий:

    #!/usr/bin/env python
    import sys
    data = sys.stdin.read()
    print('Content-type: text/plain\n\nGot Data: "%s"' % data)

Ось приклад виконання запиту `PUT` за допомогою `Request`:

    import urllib.request
    DATA = b'some data'
    req = urllib.request.Request(url='http://localhost:8080', data=DATA, method='PUT')
    with urllib.request.urlopen(req) as f:
        pass
    print(f.status)
    print(f.reason)

Використання базової автентифікації HTTP:

    import urllib.request
    # Create an OpenerDirector with support for Basic HTTP Authentication...
    auth_handler = urllib.request.HTTPBasicAuthHandler()
    auth_handler.add_password(realm='PDQ Application',
                              uri='https://mahler:8092/site-updates.py',
                              user='klem',
                              passwd='kadidd!ehopper')
    opener = urllib.request.build_opener(auth_handler)
    # ...and install it globally so it can be used with urlopen.
    urllib.request.install_opener(opener)
    urllib.request.urlopen('http://www.example.com/login.html')

`build_opener()` provides many handlers by default, including a `ProxyHandler`. By default, `ProxyHandler` uses the environment variables named `<scheme>_proxy`, where `<scheme>` is the URL scheme involved. For example, the `http_proxy` environment variable is read to obtain the HTTP proxy’s URL.

This example replaces the default `ProxyHandler` with one that uses programmatically supplied proxy URLs, and adds proxy authorization support with `ProxyBasicAuthHandler`.

    proxy_handler = urllib.request.ProxyHandler({'http': 'http://www.example.com:3128/'})
    proxy_auth_handler = urllib.request.ProxyBasicAuthHandler()
    proxy_auth_handler.add_password('realm', 'host', 'username', 'password')

    opener = urllib.request.build_opener(proxy_handler, proxy_auth_handler)
    # This time, rather than install the OpenerDirector, we use it directly:
    opener.open('http://www.example.com/login.html')

Додавання заголовків HTTP:

Використовуйте аргумент headers для конструктора `Request` або:

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

`OpenerDirector` автоматично додає заголовок User-Agent до кожного `Request`. Щоб змінити це:

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

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

Ось приклад сеансу, який використовує метод `GET` для отримання URL-адреси, що містить параметри:

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

У наступному прикладі замість цього використовується метод `POST`. Зауважте, що параметри, виведені з urlencode, кодуються до байтів перед тим, як надсилаються до urlopen як дані:

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

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

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

У наступному прикладі проксі-сервери взагалі не використовуються, замінюючи налаштування середовища:

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

## Застарілий інтерфейс

Наступні функції та класи перенесено з модуля Python 2 `urllib` (на відміну від `urllib2`). Вони можуть стати застарілими в якийсь момент у майбутньому.

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

  Copy a network object denoted by a URL to a local file. If the URL points to a local file, the object will not be copied unless filename is supplied. Return a tuple `(filename, headers)` where filename is the local file name under which the object can be found, and headers is whatever the `info()` method of the object returned by `urlopen()` returned (for a remote object). Exceptions are the same as for `urlopen()`.

  Другий аргумент, якщо він присутній, визначає розташування файлу, куди потрібно скопіювати (якщо його немає, місцем буде тимчасовий файл зі згенерованою назвою). Третій аргумент, якщо він присутній, є викликом, який буде викликано один раз після встановлення мережевого з’єднання та один раз після кожного блоку, який буде прочитано в подальшому. Викликається буде передано три аргументи; кількість переданих блоків, розмір блоку в байтах і загальний розмір файлу. Третім аргументом може бути `-1` на старих FTP-серверах, які не повертають розмір файлу у відповідь на запит на отримання.

  Наступний приклад ілюструє найпоширеніший сценарій використання:

      >>> import urllib.request
      >>> local_filename, headers = urllib.request.urlretrieve('http://python.org/')
      >>> html = open(local_filename)
      >>> html.close()

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

  `urlretrieve()` will raise `ContentTooShortError` when it detects that the amount of data available was less than the expected amount (which is the size reported by a Content-Length header). This can occur, for example, when the download is interrupted.

  Content-Length розглядається як нижня межа: якщо є більше даних для читання, urlretrieve зчитує більше даних, але якщо доступних даних менше, виникає виняток.

  You can still retrieve the downloaded data in this case, it is stored in the `content` attribute of the exception instance.

  Якщо заголовок Content-Length не надано, urlretrieve не може перевірити розмір завантажених даних і просто повертає їх. У цьому випадку ви просто повинні припустити, що завантаження пройшло успішно.

urllib.request.urlcleanup()

  Очищає тимчасові файли, які могли бути залишені попередніми викликами `urlretrieve()`.

class urllib.request.URLopener(proxies=None, **x509)

  Застаріло починаючи з версії 3.3.

  Базовий клас для відкриття та читання URL-адрес. Якщо вам не потрібно підтримувати відкриття об’єктів за допомогою схем, відмінних від `http:`, `ftp:`або :file:`file:`, можливо, ви захочете використовувати `FancyURLopener`.

  За замовчуванням клас `URLopener` надсилає заголовок User-Agent `urllib/VVV`, де VVV — це номер версії `urllib`. Програми можуть визначати власний заголовок User-Agent, створивши підклас `URLopener` або `FancyURLopener` і встановивши атрибуту класу `version` відповідне значення рядка у визначенні підкласу.

  Необов’язковий параметр proxies має бути словником, що зіставляє імена схем із URL-адресами проксі, де порожній словник повністю вимикає проксі. Його значенням за замовчуванням є `None`, у цьому випадку будуть використані параметри середовища проксі, якщо вони присутні, як обговорювалося у визначенні `urlopen()` вище.

  Додаткові параметри ключових слів, зібрані в x509, можуть використовуватися для автентифікації клієнта під час використання схеми `https:`. Ключові слова key_file і cert_file підтримуються для надання ключа SSL і сертифіката; обидва потрібні для підтримки автентифікації клієнта.

  Об’єкти `URLopener` викличуть виняток `OSError`, якщо сервер повертає код помилки.

  open(fullurl, data=None)

    Відкрийте fullurl за допомогою відповідного протоколу. Цей метод налаштовує інформацію про кеш і проксі, а потім викликає відповідний відкритий метод із його вхідними аргументами. Якщо схема не розпізнається, викликається `open_unknown()`. Аргумент data має те саме значення, що й аргумент data `urlopen()`.

    Цей метод завжди цитує fullurl за допомогою `quote()`.

  open_unknown(fullurl, data=None)

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

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

    Отримує вміст url і поміщає його в filename. Значення, що повертається, є кортежем, що складається з імені локального файлу та об’єкта `email.message.Message`, що містить заголовки відповіді (для віддалених URL-адрес) або `None` (для локальних URL-адрес). Потім абонент повинен відкрити та прочитати вміст filename. Якщо ім’я файлу не вказано, а URL-адреса посилається на локальний файл, повертається ім’я вхідного файлу. Якщо URL-адреса нелокальна і filename не вказано, ім’я файлу є результатом `tempfile.mktemp()` із суфіксом, який відповідає суфіксу останнього компонента шляху вхідної URL-адреси. Якщо вказано reporthook, це має бути функція, яка приймає три числові параметри: номер блоку, максимальний розмір фрагментів, які зчитуються, і загальний розмір завантаження (-1, якщо невідомо). Він буде викликаний один раз на початку та після кожного зчитування даних із мережі. reporthook ігнорується для локальних URL-адрес.

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

  version

    Змінна, яка вказує агента користувача об’єкта відкривача. Щоб змусити `urllib` повідомляти серверам, що це певний агент користувача, встановіть це в підкласі як змінну класу або в конструкторі перед викликом базового конструктора.

class urllib.request.FancyURLopener(...)

  Застаріло починаючи з версії 3.3.

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

  For all other response codes, the method `http_error_default()` is called which you can override in subclasses to handle the error appropriately.

  Примітка

  Згідно з листом RFC 2616, відповіді 301 і 302 на запити POST не повинні автоматично перенаправлятися без підтвердження користувача. Насправді браузери дозволяють автоматичне перенаправлення цих відповідей, змінюючи POST на GET, і `urllib` відтворює цю поведінку.

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

  Примітка

  Під час базової автентифікації екземпляр `FancyURLopener` викликає свій метод `prompt_user_passwd()`. Стандартна реалізація запитує у користувачів необхідну інформацію на керуючому терміналі. Підклас може замінити цей метод для підтримки більш відповідної поведінки, якщо це необхідно.

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

  prompt_user_passwd(host, realm)

    Повернути інформацію, необхідну для автентифікації користувача на даному хості у вказаній області безпеки. Поверненим значенням має бути кортеж `(користувач, пароль)`, який можна використовувати для базової автентифікації.

    Реалізація запитує цю інформацію на терміналі; програма повинна замінити цей метод, щоб використовувати відповідну модель взаємодії в локальному середовищі.

## `urllib.request` Обмеження

- Наразі підтримуються лише такі протоколи: HTTP (версії 0.9 і 1.0), FTP, локальні файли та URL-адреси даних.

  Змінено в версії 3.4: Додано підтримку URL-адрес даних.

- Функцію кешування `urlretrieve()` вимкнено, доки хтось не знайде час зламати правильну обробку заголовків часу закінчення терміну дії.

- Має бути функція для запиту, чи є певна URL-адреса в кеші.

- Для зворотної сумісності, якщо URL-адреса вказує на локальний файл, але файл не може бути відкритий, URL-адреса повторно інтерпретується за допомогою протоколу FTP. Іноді це може призвести до незрозумілих повідомлень про помилки.

- Функції `urlopen()` і `urlretrieve()` можуть спричиняти довільно великі затримки під час очікування встановлення з’єднання з мережею. Це означає, що важко побудувати інтерактивний веб-клієнт за допомогою цих функцій без використання потоків.

- Дані, які повертає `urlopen()` або `urlretrieve()`, є необробленими даними, які повертає сервер. Це можуть бути двійкові дані (наприклад, зображення), звичайний текст або (наприклад) HTML. Протокол HTTP надає інформацію про тип у заголовку відповіді, яку можна перевірити, подивившись на заголовок Content-Type. Якщо повернуті дані є HTML, ви можете використати модуль `html.parser` для їх аналізу.

- Код, який обробляє протокол FTP, не може відрізнити файл від каталогу. Це може призвести до неочікуваної поведінки під час спроби прочитати URL-адресу, яка вказує на файл, до якого немає доступу. Якщо URL-адреса закінчується на `/`, передбачається, що вона посилається на каталог і буде оброблятися відповідно. Але якщо спроба прочитати файл призводить до помилки 550 (це означає, що URL-адресу неможливо знайти або вона недоступна, часто через дозвіл), тоді шлях розглядається як каталог, щоб обробити випадок, коли вказано каталог за URL-адресою, але кінцевий символ `/` було пропущено. Це може призвести до оманливих результатів, коли ви намагаєтеся отримати файл, дозволи на читання якого роблять його недоступним; код FTP спробує прочитати його, зазнає помилки 550, а потім виконає перелік каталогу для нечитабельного файлу. Якщо потрібен детальний контроль, розгляньте можливість використання модуля `ftplib`, створення підкласу `FancyURLopener` або зміни _urlopener відповідно до ваших потреб.

# `urllib.response` — Класи відповідей, які використовує urllib

Модуль `urllib.response` визначає функції та класи, які визначають мінімальний файлоподібний інтерфейс, включаючи `read()` і `readline()`. Функції, визначені цим модулем, використовуються внутрішньо модулем `urllib.request`. Типовий об’єкт відповіді – це екземпляр `urllib.response.addinfourl`:

class urllib.response.addinfourl
  url

    URL-адреса отриманого ресурсу, яка зазвичай використовується для визначення того, чи було переспрямовано.

  headers

    Повертає заголовки відповіді у формі екземпляра `EmailMessage`.

  status

    Нове в версії 3.9.

    Код статусу, повернутий сервером.

  geturl()

    Застаріло починаючи з версії 3.9: Застаріло на користь `url`.

  info()

    Застаріло починаючи з версії 3.9: Застаріло на користь `headers`.

  code

    Застаріло починаючи з версії 3.9: Застаріло на користь `status`.

  getcode()

    Застаріло починаючи з версії 3.9: Застаріло на користь `status`.