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"

Определяется следующая исключительная ситуация:

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)

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

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

Изменено в версии 3.7: параметр preferred добавлен в качестве ключевого.

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

Примечания:

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

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

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)