webbrowser — Зручний контролер веб-браузера

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

Модуль webbrowser забезпечує інтерфейс високого рівня, який дозволяє відображати веб-документи користувачам. У більшості випадків простий виклик функції open() з цього модуля буде правильним.

В Unix графічні браузери є кращими під X11, але браузери текстового режиму будуть використовуватися, якщо графічні браузери недоступні або дисплей X11 недоступний. Якщо використовуються браузери текстового режиму, процес виклику блокуватиметься, доки користувач не вийде з браузера.

Якщо змінна середовища BROWSER існує, вона інтерпретується як розділений os.pathsep список браузерів, які слід спробувати перед налаштуваннями платформи за замовчуванням. Якщо значення частини списку містить рядок %s, тоді воно інтерпретується як буквальний командний рядок браузера, який буде використовуватися з аргументом URL, заміненим %s; якщо частина не містить %s, вона просто інтерпретується як назва браузера для запуску. [1]

Для платформ, відмінних від Unix, або коли в Unix доступний віддалений браузер, процес керування не чекатиме, поки користувач закінчить роботу з браузером, а дозволить віддаленому браузеру підтримувати власні вікна на дисплеї. Якщо віддалені браузери недоступні в Unix, процес керування запустить новий браузер і зачекає.

Сценарій webbrowser можна використовувати як інтерфейс командного рядка для модуля. Він приймає URL як аргумент. Він приймає наступні додаткові параметри: -n відкриває URL-адресу в новому вікні браузера, якщо це можливо; -t відкриває URL-адресу на новій сторінці браузера («вкладці»). Варіанти, природно, взаємовиключні. Приклад використання:

python -m webbrowser -t "https://www.python.org"

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.

Визначено такий виняток:

exception webbrowser.Error

Виняток виникає, коли виникає помилка керування браузером.

Визначаються такі функції:

webbrowser.open(url, new=0, autoraise=True)

Відображати url за допомогою браузера за умовчанням. Якщо new дорівнює 0, url відкривається в тому ж вікні браузера, якщо це можливо. Якщо new дорівнює 1, відкривається нове вікно браузера, якщо це можливо. Якщо new дорівнює 2, за можливості відкривається нова сторінка браузера («вкладка»). Якщо autoraise має значення True, вікно відкривається, якщо це можливо (зверніть увагу, що в багатьох віконних менеджерах це відбуватиметься незалежно від налаштування цієї змінної).

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

Викликає подію аудиту webbrowser.open з аргументом url.

webbrowser.open_new(url)

Відкрийте url у новому вікні браузера за замовчуванням, якщо можливо, інакше відкрийте url в єдиному вікні браузера.

webbrowser.open_new_tab(url)

Відкрийте url на новій сторінці («вкладці») веб-переглядача за умовчанням, якщо це можливо, інакше еквівалентно open_new().

webbrowser.get(using=None)

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

webbrowser.register(name, constructor, instance=None, *, preferred=False)

Зареєструйте тип браузера ім’я. Після реєстрації типу браузера функція get() може повернути контролер для цього типу браузера. Якщо екземпляр не надано або має значення None, конструктор буде викликано без параметрів для створення екземпляра за потреби. Якщо надано екземпляр, конструктор ніколи не буде викликаний і може бути None.

Якщо встановити preferred на True, цей браузер стане кращим результатом для виклику get() без аргументів. В іншому випадку ця точка входу корисна, лише якщо ви плануєте встановити змінну BROWSER або викликати get() з непорожнім аргументом, який відповідає імені обробника, який ви оголошуєте.

Змінено в версії 3.7: Додано переважний параметр лише для ключового слова.

Кілька типів браузерів визначено заздалегідь. У цій таблиці наведено назви типів, які можна передати функції get(), і відповідні екземпляри для класів контролерів, усі визначені в цьому модулі.

Тип імені

Назва класу

Примітки

'mozilla'

Mozilla('mozilla')

'firefox'

Mozilla('mozilla')

'Богоявлення''

Epiphany('epiphany')

'kfmclient'

Konqueror()

(1)

'завойовник'

Konqueror()

(1)

'kfm''

Konqueror()

(1)

'опера'

Opera()

'посилання'

GenericBrowser('links')

'elinks'

Elinks('elinks')

'рись''

GenericBrowser('lynx')

'w3m'

GenericBrowser('w3m')

'windows-default'

WindowsDefault

(2)

'macosx'

MacOSXOSAScript('default')

(3)

''сафарі'

MacOSXOSAScript('safari')

(3)

'google-chrome'

Chrome('google-chrome')

'хром''

Chrome('chrome')

'хром''

Chromium('chromium')

'chromium-браузер'

Chromium('chromium-browser')

Примітки:

  1. «Konqueror» — це файловий менеджер для робочого середовища KDE для Unix, і його має сенс використовувати, лише якщо запущено KDE. Якийсь спосіб надійного виявлення KDE було б добре; змінної KDEDIR недостатньо. Зауважте також, що назва «kfm» використовується навіть під час використання команди konqueror із KDE 2 — реалізація вибирає найкращу стратегію для запуску Konqueror.

  2. Тільки на платформах Windows.

  3. Тільки на платформі macOS.

Added in version 3.3: Додано підтримку Chrome/Chromium.

Змінено в версії 3.12: Support for several obsolete browsers has been removed. Removed browsers include Grail, Mosaic, Netscape, Galeon, Skipstone, Iceape, and Firefox versions 35 and below.

Застаріло з версії 3.11, буде видалено у версії 3.13: MacOSX is deprecated, use MacOSXOSAScript instead.

Ось декілька простих прикладів:

url = 'https://docs.python.org/'

# Open URL in a new tab, if a browser window is already open.
webbrowser.open_new_tab(url)

# Open URL in new window, raising the window if possible.
webbrowser.open_new(url)

Об’єкти контролера браузера

Контролери браузера надають ці методи, які паралельні трьом функціям зручності на рівні модуля:

webbrowser.name

System-dependent name for the browser.

controller.open(url, new=0, autoraise=True)

Відображення url за допомогою браузера, керованого цим контролером. Якщо new дорівнює 1, відкривається нове вікно браузера, якщо це можливо. Якщо new дорівнює 2, за можливості відкривається нова сторінка браузера («вкладка»).

controller.open_new(url)

Відкрийте url у новому вікні браузера, який обробляє цей контролер, якщо можливо, інакше відкрийте url в єдиному вікні браузера. Псевдонім open_new().

controller.open_new_tab(url)

Відкрийте url на новій сторінці («вкладці») браузера, який обробляється цим контролером, якщо можливо, інакше еквівалентно open_new().

Виноски