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)