webbrowser — удобный контроллер веб-браузера

Исходный код: Lib/webbrowser.py

Модуль webbrowser предоставляет высокоуровневый интерфейс для отображения пользователям веб-документов. В большинстве случаев достаточно просто вызвать функцию open() из этого модуля.

В Unix графические браузеры предпочтительны при наличии X11, но если графические браузеры недоступны или отсутствует дисплей X11, будут использоваться текстовые браузеры. При использовании текстовых браузеров вызывающий процесс будет заблокирован, пока пользователь не закроет браузер.

Если существует переменная окружения BROWSER, она интерпретируется как список браузеров, разделённых os.pathsep, которые следует попробовать раньше вариантов по умолчанию для платформы. Если значение элемента списка содержит строку %s, оно интерпретируется как буквальная командная строка браузера, в которой URL-адрес аргумента подставляется вместо %s; если значение представляет собой одно слово, обозначающее один из уже зарегистрированных браузеров, этот браузер помещается в начало списка поиска; если элемент не содержит %s, он просто интерпретируется как имя запускаемого браузера. [1]

Изменено в версии 3.14: Теперь переменную BROWSER также можно использовать для изменения порядка вариантов по умолчанию для платформы. Это особенно полезно в macOS, где варианты по умолчанию для платформы не ссылаются на инструменты командной строки в PATH.

На платформах, отличных от Unix, а также в Unix при наличии удалённого браузера управляющий процесс не будет ждать, пока пользователь закончит работу с браузером, а позволит удалённому браузеру управлять собственными окнами на дисплее. Если в Unix удалённые браузеры недоступны, управляющий процесс запустит новый браузер и будет ждать.

В iOS переменная окружения BROWSER, а также любые аргументы, управляющие автоматическим поднятием окна на передний план, выбором браузера и созданием новой вкладки или окна, игнорируются. Веб-страницы всегда будут открываться в предпочитаемом пользователем браузере, в новой вкладке, а браузер будет выведен на передний план. Для использования модуля webbrowser в iOS требуется модуль ctypes. Если ctypes недоступен, вызовы open() завершатся ошибкой.

Интерфейс командной строки

Скрипт webbrowser можно использовать как интерфейс командной строки для модуля. В качестве аргумента он принимает URL-адрес. Также он принимает следующие необязательные параметры:

-n, --new-window: Открывает URL-адрес в новом окне браузера, если это возможно.

-t, --new-tab: Открывает URL-адрес в новой вкладке браузера.

Разумеется, эти параметры взаимоисключающие. Пример использования:

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

Доступность: не WASI, не Android.

Определено следующее исключение:

exception webbrowser.Error: Исключение, возникающее при ошибке управления браузером.

Определены следующие функции:

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

Отображает url в браузере по умолчанию. Если new равно 0, url открывается в том же окне браузера, если это возможно. Если new равно 1, открывается новое окно браузера, если это возможно. Если new равно 2, открывается новая страница («вкладка») браузера, если это возможно. Если autoraise равно True, окно выводится на передний план, если это возможно (обратите внимание, что во многих оконных менеджерах это произойдёт независимо от значения этой переменной).

Возвращает True, если браузер был успешно запущен, и False в противном случае.

Обратите внимание, что на некоторых платформах эта функция может открыть файл и запустить связанное с ним приложение операционной системы. Однако такая возможность не поддерживается и не является переносимой.

Вызывает событие аудита webbrowser.open с аргументом url.

webbrowser.open_new(url)

Открывает url в новом окне браузера по умолчанию, если это возможно; в противном случае открывает url в единственном окне браузера.

Возвращает True, если браузер был успешно запущен, и False в противном случае.

webbrowser.open_new_tab(url)

Открывает url на новой странице («вкладке») браузера по умолчанию, если это возможно; в противном случае действует так же, как open_new().

Возвращает True, если браузер был успешно запущен, и False в противном случае.

webbrowser.get(using=None): Возвращает объект-контроллер для типа браузера, заданного параметром using. Если using равно None, возвращает контроллер браузера по умолчанию, подходящего для окружения вызывающего процесса.

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

Регистрирует тип браузера name. После регистрации типа браузера функция get() может возвращать контроллер для этого типа браузера. Если параметр instance не задан или равен None, при необходимости для создания экземпляра будет вызван constructor без параметров. Если параметр instance задан, constructor никогда не вызывается и может быть равен None.

Если установить для preferred значение True, этот браузер станет предпочтительным результатом вызова get() без аргументов. В противном случае эта точка входа полезна только в том случае, если вы планируете задать переменную BROWSER или вызвать get() с непустым аргументом, соответствующим имени объявленного вами обработчика.

Изменено в версии 3.7: Добавлен параметр preferred, который можно указывать только по ключевому слову.

Предварительно определён ряд типов браузеров. В этой таблице приведены имена типов, которые можно передавать функции get(), и соответствующие экземпляры классов-контроллеров, определённых в этом модуле.

Имя типа	Имя класса	Примечания
`'mozilla'`	`Mozilla('mozilla')`
`'firefox'`	`Mozilla('mozilla')`
`'epiphany'`	`Epiphany('epiphany')`
`'kfmclient'`	`Konqueror()`	(1)
`'konqueror'`	`Konqueror()`	(1)
`'kfm'`	`Konqueror()`	(1)
`'opera'`	`Opera()`
`'links'`	`GenericBrowser('links')`
`'elinks'`	`Elinks('elinks')`
`'lynx'`	`GenericBrowser('lynx')`
`'w3m'`	`GenericBrowser('w3m')`
`'windows-default'`	`WindowsDefault`	(2)
`'macosx'`	`MacOSXOSAScript('default')`	(3)
`'safari'`	`MacOSXOSAScript('safari')`	(3)
`'google-chrome'`	`Chrome('google-chrome')`
`'chrome'`	`Chrome('chrome')`
`'chromium'`	`Chromium('chromium')`
`'chromium-browser'`	`Chromium('chromium-browser')`
`'iosbrowser'`	`IOSBrowser`	(4)

Примечания:

«Konqueror» — файловый менеджер среды рабочего стола KDE для Unix; его имеет смысл использовать, только если запущена KDE. Было бы полезно иметь надёжный способ обнаружения KDE; переменной KDEDIR недостаточно. Обратите также внимание, что имя «kfm» используется даже при запуске команды konqueror в KDE 2 — реализация выбирает наилучшую стратегию запуска Konqueror.
Только на платформах Windows.
Только в macOS.
Только в iOS.

Добавлено в версии 3.2: Добавлен новый класс MacOSXOSAScript, который в Mac используется вместо прежнего класса MacOSX. Он поддерживает открытие браузеров, не установленных в качестве браузера по умолчанию в ОС.

Добавлено в версии 3.3: Добавлена поддержка Chrome/Chromium.

Изменено в версии 3.12: Удалена поддержка нескольких устаревших браузеров. К удалённым браузерам относятся Grail, Mosaic, Netscape, Galeon, Skipstone, Iceape и Firefox версий 35 и ниже.

Изменено в версии 3.13: Добавлена поддержка iOS.

Ниже приведено несколько простых примеров:

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)

Объекты-контроллеры браузера

Контроллеры браузера предоставляют атрибут name и следующие три метода, соответствующие функциям модуля для упрощённого вызова:

controller.name: Зависящее от системы имя браузера.

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().

webbrowser — удобный контроллер веб-браузера

Интерфейс командной строки

Объекты-контроллеры браузера

Сноски